CUA Driver 跨平台 E2E 测试收敛方案Rust 类型化用例目录、桌面观察器与证据驱动报告【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-codeCUA Driver 是 qwen-code 仓库中负责跨平台桌面自动化Windows UIA、macOS AX、Linux X11/Wayland AT-SPI的 Rust 驱动。本文将完整解析仓库内packages/cua-driver/docs/test-harness-convergence-plan.md所定义的 Rust E2E 测试收敛方案如何用一份 Rust 类型化用例目录Typed Case Catalog替代历史的手写测试家族与 Python 收集器如何通过跨切面桌面观察器验证后台投递不偷焦点以及如何让 CI 报告做到每条行为证据可追溯。读完你可以掌握该驱动 E2E 测试从用例声明、结果记录、环境预检到 CI 报告的全套设计并能在仓库源码中定位每一处落地实现。需要说明的是原文档本身已标注为Historical plan历史规划其所有权与报告模型已于 2026-07-12 落地当前贡献者的实际操作流程以 test-harnesses-guide.md、test-matrix.md 与 e2e-ci-reporting.md 为准。但这份规划文档完整承载了该测试体系的设计骨架是理解整个 CUA Driver E2E 架构的最佳入口。一、收敛背景为什么需要一份收敛计划CUA Driver 早期的 E2E 测试由多个分散的测试家族组成modality 系列modality_input_e2e_test.rs、modality_background_test.rs、modality_focus_test.rs、Windows UX guard 目标、遗留的 Python 收集器与 shell 场景清单。这类结构带来了三个问题覆盖语义分裂前台/后台投递foreground/background delivery本应是动作action上的一个维度却被做成了独立的测试家族导致重复测试与语义混淆无法证伪的通过工具返回ok并不代表动作真的送达目标应用许多断言只检查了驱动响应而没有检查外部桌面状态多份矩阵源matrix.yaml、Python 收集器、shell 场景清单与 Rust 测试各自为政维护成本高且容易失同步。重新评审Re-review后规划确定了不变的方向Rust 拥有场景、断言与结果记录仓库本地repo-local的 harness 应用是唯一规范的 E2E 目标AX/PX 定位与前台/后台投递是动作的维度而非测试家族焦点focus、z 序z-order、光标cursor与桌面检查是跨切面观察cross-cutting observations。在此基础上评审对原计划做了五项关键修改成为整个收敛方案的行动纲领不把历史单元数量当作目标共享矩阵必须覆盖受支持的路径组合每一项缺失都要给出路径等价或能力不支持的理由把测试状态与驱动行为分离测试通过可能因为动作被送达也可能因为声明的不可支持路径被正确拒绝两种结果在报告中必须区分环境就绪性作为车道lane预检处理桌面缺失、TCC 授权缺失、fixture 缺失、AT-SPI 总线缺失、录制器缺失或非交互式 Windows 会话必须在行为单元运行前一次性失败以 Rust 类型化用例目录作为矩阵唯一来源不新增第二份matrix.yaml、Python 收集器或 shell 拥有的场景清单每个单元保留一份证据包但在显式状态重置证明隔离性的前提下复用驱动与 harness 进程。最终目标是一组更小但更强的测试每个单元都有明确的覆盖理由和强外部预言机oracle测试数量本身不是成功指标。二、不可协商的八条规则收敛方案的底层约束被归纳为八条不可协商规则Non-negotiable Rules它们是后续所有设计用例目录、观察器、预检、报告的检验标准成功响应 ≠ 成功投递。一次成功的工具响应永远不能证明投递成功已投递的动作必须改变 fixture 或桌面状态且由测试独立读取验证。后台动作必须证明零副作用。后台动作还必须证明未窃取焦点、未将目标窗口提升到前台、未移动真实光标、未泄漏部分输入在这些不变式适用时。拒绝仅在契约预期时才有效。只有满足三个条件拒绝才成立单元契约预期拒绝、驱动返回允许的结构化拒绝码、桌面观察器未发现任何副作用。要求投递的单元遇拒绝即失败。即使拒绝是诚实的驱动确实如实报告了不支持只要单元契约要求投递该单元就失败。必备能力不得提前返回通过。必需的规范 fixture 或桌面能力不能变成通过式提前返回passing early return可选测试必须在执行前显式声明为可选。已知缺口不使用#[should_panic]凑绿。已知缺口不得用#[should_panic]假装覆盖它们应在命名可选车道中运行并链接到 issue直到修复。Shell/PowerShell 运行器只搭环境、只收证据。它们不得从 Cargo 输出推断行为结果。每次运行必须记录被测源码构建。macOS 可以经已安装的 app bundle 代理 TCC但该 bundle 必须来自同一源码修订版。其中第 6 条直接映射到文档删除门禁中的No#[should_panic]known-gap E2E test remains第 1 条则是外部预言机原则的源头。三、目标测试模型一份类型化用例目录 一份结果记录3.1 类型化用例目录Typed Case Catalog收敛方案的核心是用 Rust 结构体声明每一个行为单元web 与 native harness 测试共用同一结构。规划文档给出的原型如下struct CaseSpec { id: static str, platform: Platform, display_server: DisplayServer, harness: Harness, action: Action, targeting: Targeting, delivery: Delivery, scope: Scope, expectation: ContractExpectation, oracles: static [OracleKind], route: DriverRoute, } enum ContractExpectation { Deliver, Refuse { allowed_codes: static [RefusalCode] }, }该原型已在cua-driver-testkit中落地为可序列化的正式实现见 e2e.rs。落地版CaseSpec字段包括cell_id、platform、display_server、harness、toolkit、action、targeting、delivery、scope、driver_route、expected_behavior、oracles并通过两个构造器表达契约CaseSpec::delivered(...)生成ContractExpectation::Deliver的单元expecting_refusal(allowed_codes)链式方法将契约改为Refuse { allowed_codes }。同时validate()方法在声明期即做防御性校验cell_id必须是产物安全的 ASCII 字符字母数字及-/_/.每个单元必须声明至少一个外部预言机oracles非空且只有后台投递Delivery::Background允许声明拒绝契约——这从类型层面封死了前台动作偷偷转成拒绝的作弊路径。几个关键类型的语义如下RefusalCode是枚举而非字符串前缀匹配。规划文档列出的初始 Windows 集合为BackgroundUnavailable、BackgroundOccluded、BackgroundUipiBlockedLinux 当时只声明BackgroundUnavailable一个单元列出其受控设置下允许的确切码。在源码实现中该枚举已扩展为 18 个成员除后台三码外还包括WindowMinimized与一整套浏览器路由码BrowserRouteUnavailable、BrowserConsentRequired、BrowserTabNotFound等并通过from_driver_code()从驱动字符串精确映射见 e2e.rs。Targeting使用Ax、Px、Page或NotApplicable结果 schema 中用targeting取代旧的capture_mode字段——捕获capture是独立的读契约与动作定位维度无关。DriverRoute命名覆盖所依据的实现路径例如 UIA Invoke、PostMessage、坐标注入、CGEvent、AT-SPI action、libei 或 CDP。它是测试元数据不是请求参数。目录本身是机器可读的清单贡献者文档与覆盖表都从它生成或与它核对不存在第二份矩阵文件需要同步。3.2 覆盖选择Coverage Selection规划明确不自动恢复完整的笛卡尔积而是按驱动路由挑选单元每个受支持动作在工具暴露两种投递模式时都要有前台与后台覆盖该动作使用的每条不同定位路径至少有一个单元每条不同的 OS 后端路由至少有一个单元渲染器或工具包重复仅在改变路由或确实产生过兼容性缺陷时才保留每个被省略的组合必须命名一个equivalent_to单元或给出契约不支持的理由。当前共享目录在每个共享 harness 应用上声明 40 个单元即每个平台 Electron Tauri 共 80 个共享单元当某个组合触及不同驱动路由时新增单元仅当另一个单元以同等或更强的预言机证明同一路由时才移除单元。在 test-matrix.md 中可看到落地后的矩阵维度OSwindows/macos/linux、窗口系统Win32/UIA、AppKit/AX、X11/AT-SPI、Wayland/AT-SPI、WebView/CDP、harnessElectron、Tauri、WPF、WinUI3、WebView2、AppKit、SwiftUI、WKWebView、GTK3、定位ax/px/page/not_applicable、投递background/foreground/N/A、范围window/desktop/N/A、预言机应用状态、可访问性状态、焦点状态、像素状态、协议状态等。3.3 结果记录Result Record收敛方案统一使用一个 schema 版本且各字段相互独立字段含义cell_id稳定用例 idplatform、display_serverOS 与 Win32/Quartz/X11/Wayland 环境harness、toolkitElectron、Tauri、WPF、WinUI3、WebView2、AppKit、SwiftUI、GTK3action、targeting、delivery、scope契约维度driver_route单元覆盖的后端路径expected_behaviorDELIVER或REFUSEtest_statusPASS、FAIL、SKIP或ENVIRONMENT_ERRORobserved_behaviorDELIVERED、REFUSED、NO_EFFECT、ERROR或NOT_RUNrefusal_code当观测行为为REFUSED时的结构化码oracles应用状态与附加的桌面观测known_issue可选的 issue id它永远不会把失败改成通过evidence视频、轨迹、截图、结构化状态与日志路径这套字段消除了原先含义模糊的EXPECTED_REFUSAL状态。拒绝契约只有在expected_behaviorREFUSE、observed_behaviorREFUSED、拒绝码在允许集合内、且所有无副作用预言机全部通过时才算通过报告对投递通过与拒绝通过分别计数。落地实现中的TestStatus、ObservedBehavior、Evidence含video/trajectory/screenshot/log等枚举与结构体同样位于 e2e.rs。四、跨切面桌面观察器DesktopObserver后台投递的验证难点在于焦点断言只能证明没有偷焦点却证明不了点击真的改变了目标应用状态。因此收敛方案引入一个 testkit 接口在操作前后分别快照桌面状态DesktopObservation foreground window // 前台窗口 target z-order and minimized state // 目标 z 序与最小化状态 focus-change journal // 焦点变化日志 real cursor position // 真实光标位置 optional leaked-input journal // 可选的泄漏输入日志该接口在源码中由cua-driver-testkit的 observer.rs 实现ObserverBackendtrait 提供capabilities()、snapshot(target)、start_journal()、drain_journal()TargetZ枚举区分BackgroundOccluded/BackgroundVisible/Foreground/Minimized/NotFound并带 z 序排序权重ObservationDelta汇总前后快照与日志输出 passed/unsupported/violations由测试判定不变式是否被破坏见 observer.rs。Windows、macOS、Linux 各有 native 后端。观察器必须附加到以下单元每个后台投递单元拒绝refusal单元启动/最小化单元承诺不改变焦点的截图与捕获单元光标证据单元。判定规则是对称的后台投递成功要求目标状态改变 桌面不变式未变拒绝成立要求目标无变化 桌面不变式未变。仅凭焦点通过永远不能证明输入已投递。规划还配套了一个遮挡哨兵occluding sentinel机制一个全屏遮挡目标的 Electron 哨兵负责记录焦点与泄漏输入日志跨目标框架共享Windows、macOS、X11 还要求哨兵实时焦点日志报告焦点丢失。预检会故意向哨兵发送输入、故意提升后台目标只有当泄漏输入与瞬时焦点丢失被观察到、哨兵被恢复并重新完全遮挡目标后车道才继续——这个阳性对照positive control防止损坏的守卫让所有后台行看起来都是绿的。Wayland 因 Electron/Ozone 对外部 surface 焦点切换不可靠地发出 DOMblur改用合成器支撑的 native 焦点观察器但哨兵心跳与泄漏输入日志仍然强制。五、进程与证据生命周期收敛方案对进程边界做出明确规定每个车道一个 Rust 源码构建每个车道一个 driver daemon 或 MCP 进程当 fixture 具备已验证的重置操作时每个 harness 组一个 harness 进程每个单元一个录制会话和一条结果记录崩溃、重置失败或窗口身份变化后必须重启 harness。每个 fixture 重置必须返回一个代数令牌generation token下一个单元在行动前验证新令牌与干净的标记状态在 harness 提供此重置契约之前保持每单元一进程的隔离。视频对每个规范 E2E 单元都是必需的在车道预检中只验证一次视频捕获能力录制器失败会在用例目录运行前中止整个车道而不是让每个单元都复现同一次权限失败。六、环境预检Environment Preflight每个 OS 运行器执行一次预检并产出一条环境记录EnvironmentRecord含platform、display_server、compositor、input_backends、source_sha、status、duration_ms、message见 e2e.rs。通用检查项源码修订与驱动版本匹配必需 fixture 二进制存在显示/用户会话是交互式的驱动能列出并检查预检 fixture可访问性与捕获权限可用短视频能启动、停止并通过ffprobe产物目录可写。各平台专属预检要求平台必需预检Windows非 Session-0 交互桌面、输入桌面、前台哨兵、FFmpeg、UIA 可见性macOSApp-bundle daemon 身份、实时 socket、辅助功能Accessibility、屏幕录制Screen Recording、fixture 窗口可见性Linux X11X server、DBus、AT-SPI、窗口管理器、捕获、输入后端Linux Wayland合成器、DBus、AT-SPI、portal/捕获路径、libei 或声明的拒绝路径规范调用canonical invocations开启严格模式缺失必需能力产生ENVIRONMENT_ERROR永远不会以通过形式从测试返回。在 test-harnesses-guide.md 中可以看到落地后的运行器还设置了CUA_E2E_FORBID_SKIPS1未过滤的共享运行额外设置CUA_E2E_EXPECTED_MIN_CELLSWindows/Linux 为 80macOS 为 120确保被过滤、缩短或意外清空的目录不可能报绿。七、文件所有权与处置收敛方案为每个既有测试文件指定了最终归属或处置动作核心原则是每个行为只有一个清晰的所有者当前文件最终所有者或动作cross_platform_behavior_test.rs共享 Electron/Tauri 用例目录 外部 fixture 状态与桌面副作用预言机harness_wpf_test.rs使用公共用例/结果运行器的 WPF 专属行harness_winui3_test.rsWinUI3 专属行只保留工具包差异行为harness_web_test.rsWebView2 与 Page/CDP 行为禁止把 Page 定位混入 AX/PX 标签harness_appkit_test.rs规范 AppKit 行含前后台 AX 滚动与精确的 PX 后台拖拽拒绝harness_swiftui_test.rs规范 SwiftUI 树/捕获、后台动作与 popover 触发行harness_gtk3_test.rs面向 X11 与 Wayland 的最小 GTK3/AT-SPI 行遗留 Windows UX guard 目标在 typed 启动/光标/共享/捕获/桌面范围所有者通过替换审计后删除modality_input_e2e_test.rs、modality_background_test.rs、modality_focus_test.rs删除断言迁移至共享/typed 所有者capture_contract_test.rs树/图像包含行为的唯一所有者规范前置条件失败而非跳过desktop_scope_os_test.rs各平台窗口/桌面范围契约installed_app_launch_macos_test.rs、installed_app_textedit_macos_test.rs规范登录 macOS 车道的支持型 Calculator/TextEdit 行harness_libreoffice_test.rs可选已安装应用车道不参与规范运行与计数protocol_*、schema、transport 测试单元/协议门禁无桌面视频、无行为矩阵行tests/fixtures/shared/scenarios.json仅在选择器与标记引用审计后裁剪这些目标文件在仓库中均已落实packages/cua-driver/rust/crates/cua-driver/tests/下可见cross_platform_behavior_test.rs、harness_wpf_test.rs、harness_winui3_test.rs、harness_web_test.rs、harness_appkit_test.rs、harness_swiftui_test.rs、harness_gtk3_test.rs、capture_contract_test.rs、desktop_scope_*_test.rs、installed_app_*_macos_test.rs、protocol_*_test.rs等文件modality 系列与遗留 guard 目标已不存在。八、CI 形态贡献者调用保持无选择器selector-free车道选择属于私有 CI 管道与诊断状态。Pull Request 门禁按受影响的 OS 路径运行单元/协议任务共享核心或 schema 变更触发 Linux 与 Windows 单元任务平台专属变更只触发该平台单元任务E2E 由维护者调度未来可成为可选合并前门禁。维护者 E2EWindowsGitHub-hosted 运行器在预检证明交互式桌面时为规范来源Azure RDP 运行器只是可选的环境一致性回放不是第二个行为真相来源LinuxGitHub-hosted 运行器在 Xvfb 下运行 X11 并使用托管包Nix 源码门禁独立纯 Wayland 维护者车道使用 Nix dev shellLinux 无 GIF 要求macOS在已登录、TCC 授权的宿主上经规范 macOS 运行器运行未来自托管运行器必须使用相同预检。CI 可以把完整矩阵扇出为 shared、native、capture/scope 任务——这些是执行分区不是替代的公共测试套件。九、报告与证据Rust 为每个已声明单元产出一条记录由共享 Rust reporter 统一处理拒绝重复或缺失的 cell id对照用例契约校验结果校验必需视频证据存在且非空渲染行为表与已声明覆盖表有已声明单元未产出结果时失败。规划明确不得解析test ... ok行来生成行为行Cargo/JUnit 输出仍可为单元测试提供失败注解。每个内部车道上传一份产物归档每个行为单元一个稳定证据子目录GitHub summary 的每一行都将其精确视频路径文本链接到所属车道归档trajectory.json路径保留在results.jsonl与归档中——因为 GitHub 无法对归档内文件做深链接用精确路径保持行无歧义同时避免按单元数倍增产物上传。证据目录结构落地版见 test-harnesses-guide.mdartifacts/cua-driver/os/ |-- recordings/cell-label-pidpid-sequence/recording.mp4 |-- recordings/cell-label-pidpid-sequence/trajectory.json |-- recordings/cell-label-pidpid-sequence/turn-*/before_state.json |-- recordings/cell-label-pidpid-sequence/turn-*/before.png |-- recordings/cell-label-pidpid-sequence/turn-*/after_state.json |-- recordings/cell-label-pidpid-sequence/turn-*/after.png |-- cases.jsonl |-- environment.jsonl |-- results.jsonl |-- summary.md -- rust-target.log规范 GUI 单元要求可解析的前后状态与每个目标 turn 非空的前后目标窗口图像唯一的窄例外是成功恢复最小化窗口的 Windowsbring_to_front场景。trajectory.json必须以behavior_video.status finalized结尾。十、六个实现切片收敛方案将落地过程拆为六个递进切片每片都有明确的出口标准切片 1契约与预检——定稿CaseSpec、结果枚举、拒绝码枚举与单一 schema 版本为 reporter 增加重复/缺失/矛盾记录校验为三平台运行器增加严格环境预检shell 运行器停止虚构行为行。出口会话/fixture/权限/录制器缺失只作为环境错误失败一次合成 CaseSpec 集能渲染合法报告。切片 2共享矩阵完整性——每个共享单元映射显式驱动路由补齐缺失路由单元并记录每个省略等价项给后台与拒绝单元附加桌面观察器保留 editor-save 与全部既有外部标记在完成断言映射后移除三个遗留共享测试。出口无假拖拽通过、无任意错误被当作拒绝、无共享遗留测试每个共享单元一份结果/证据包。切片 3Windows 收敛——把 guard、modality-input、modality-background 断言迁移至共享/WPF/WinUI3/捕获/启动/桌面范围所有者每个当前失败动作保留为失败的必需投递单元或链接 issue 的可选单元不得转成绿色拒绝将 Windows 桌面范围纳入规范运行仅在逐单元对齐后删除三个过渡文件。出口Windows 无 guard/modality 家族每个后台单元同时具备目标状态与桌面副作用证据。切片 4macOS 与 Linux 收敛——AppKit、SwiftUI、GTK3 测试采用公共用例/结果运行器规范早期返回跳过改为预检失败Linux schema 检查与真实桌面行为分离重命名捕获与桌面范围所有权文件AppKit 滚动与真实应用检查移入显式可选 issue 车道。出口native 单元与共享单元产出相同记录X11 与 Wayland 是独立维度macOS 失败能区分 TCC 与驱动行为。切片 5Flake 与 fixture 清理——固定坐标替换为发现式几何CDP 端口按进程分配sleep 替换为外部标记的 deadline 轮询增加 fixture 代数令牌重置仅在证明状态干净后复用 harness 进程裁剪无活引用的 fixture 控件与标记。出口无规范单元依赖 VM 特定坐标、固定共享端口或无解释的 sleep。切片 6CI 验证与删除——install-local与 TCC 预检后保持完整 macOS 矩阵绿以通过的 GitHub-hosted Windows 矩阵为规范结果RDP 运行器仅用于环境一致性调查以通过的 Linux X11 与 Nix 源码运行为受支持的 Linux 门禁在 issue #1922 关闭前以实验性 issue 车道运行纯 Wayland每次删除过渡文件前对比新旧单元从生成目录更新贡献者文档与 PR 描述。出口每个已声明单元要么按契约投递/拒绝要么带着已链接的未解决 bug 失败环境失败独立统计。十一、删除门禁与完成定义删除门禁只有当满足以下全部条件时测试或 fixture 路径才可被删除每个断言都映射到 CaseSpec 或单元/可选所有者替代预言机同等或更强在每个受影响 OS 上对比过新旧结果必需投递的失败仍然可见拒绝单元使用显式允许码与桌面副作用证明运行器、文档与产物标签在同一变更中停止引用旧目标reporter 找不到缺失的已声明单元。完成定义Definition of DoneRust 拥有一份类型化行为目录与一份结果 schema必需 GUI 前置条件不能通过提前返回测试状态与观测驱动行为是独立字段每个受支持动作按不同驱动路由具备前台/后台覆盖并给出省略理由每个已投递动作都有外部目标状态预言机每个后台或拒绝单元都有桌面副作用证据无永久 guard/modality/delivery 测试家族无#[should_panic]已知缺口 E2E 测试无孤儿目标被计为覆盖共享与 native harness 产出相同结果/证据形态单元/协议测试保持桌面无关且无视频Windows、macOS 与受支持的 Linux X11 完整运行产出分类结果与逐单元证据链接实验性 Wayland 与环境失败显式停止或失败不产生虚假行为通过。十二、落地状态与当前工作流规划文档记录该方案于2026-07-12达到所有权与报告目标并留下四组规范执行记录Windows run29211506624在6d7f02e4通过 114/114 行已登录 macOS 矩阵在448d052f通过 133/133 行稳定已安装应用 TCC 身份Linux X11 run29213365684与 Sway run29213349962各在72083bb4通过 108/108 行同为 71 次投递与 37 次精确拒绝可选嵌套cua-compositor车道仍为实验性报告 typed 失败而非声称标准 Wayland 支持。其余能力细节各 OS 的投递/拒绝/未证实动作台账维护在 action-support.md落地后的执行入口与仓库地图见 test-harnesses-guide.mdLinux 为scripts/ci/linux/run-rust-e2e.shWindows 为.\scripts\ci\windows\run-rust-e2e.ps1 -RequireGuimacOS 为packages/cua-driver/tests/runners/macos-lume/run-all.sh——三者都是无选择器的完整矩阵命令。规划文档本身则如开头所述定格为历史计划供追踪设计演进与评审结论使用。延伸阅读仓库内相关文档与源码test-harnesses-guide.md落地后的贡献者指南测试分层、仓库地图、贡献流程test-matrix.md当前测试矩阵与 CI 入口e2e-ci-reporting.mdE2E CI 报告设计action-support.md各 OS 投递/拒绝/未证实动作台账e2e.rsCaseSpec、RefusalCode、ContractExpectation、结果记录等类型化实现observer.rsDesktopObserver跨平台桌面副作用接口cross_platform_behavior_test.rs共享 Electron/Tauri 行为矩阵测试【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考