CUA Driver 跨平台测试矩阵全解析Rust 驱动层的 Harness E2E 测试体系与桌面行为验收标准【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文以packages/cua-driver/docs/test-matrix.md为核心骨架系统讲解 CUA Drivercua-driver这一桌面 AI Agent 运行时中覆盖 Windows / macOS / Linux 三大平台的 Rust 测试矩阵从单元与确定性协议测试到以 Electron、Tauri、WPF、WinUI3、AppKit、SwiftUI、GTK3 等原生 Harness 构建的端到端E2E行为验收体系。读完本文你将掌握该仓库如何用矩阵维度 类型化用例 外部 Oracle 证据工件的方式客观、可复现地验收桌面动作点击、键盘、滚动、拖拽、编辑器等在前后台两种投递模式下的真实行为并理解其拒绝Refusal、跳过Skip与焦点保持等跨切面约束的定义。CUA Driver 位于 packages/cua-driver是仓库中负责真实桌面交互的 Rust 驱动层。其测试矩阵文档是理解整套测试基建的总纲而仓库内rust/crates/cua-driver/tests/下的 40 个测试文件、tests/fixtures/下的各类 Harness 应用与tests/runners/下的各平台运行器共同构成了这份矩阵的实体。一、测试矩阵的整体架构两类测试一条边界packages/cua-driver/docs/test-matrix.md将 Rust 测试套件划分为两个顶层类别单元与确定性协议测试Unit and deterministic protocol tests不依赖仓库本地应用或交互式桌面环境仅验证驱动自身逻辑。Harness E2E 测试Harness E2E tests构建并启动仓库本地应用通过 Rust 驱动驱动它再由外部应用或桌面 Oracle 验证结果。文档明确指出一个测试之所以是 E2E是因为它跨越了驱动、操作系统、窗口系统和应用四层边界crosses the driver, OS, window system, and application boundary。Rust Harness 目录及其外部 Oracle 是测试事实的最终来源source of truth而不是某次驱动调用返回的成功响应。这一定义决定了后续所有章节的评判逻辑判断一次桌面操作是否成功必须以 fixture 拥有的状态变更或外部桌面状态为准而不是以驱动自报的成功为准。二、矩阵维度每个 E2E 结果都必须声明的字段文档为每一个 Harness E2E 结果定义了一组必须标注的维度这是跨平台可比性的基础维度取值OSwindows、macos、linux窗口系统Win32/UIA、AppKit/AX、X11/AT-SPI、Wayland/AT-SPI、WebView/CDPHarnessElectron、Tauri、WPF、WinUI3、WebView2、AppKit、SwiftUI、WKWebView、GTK3Action targetingax、px、page、not_applicableDeliverybackground、foreground、N/AScopewindow、desktop、N/AOracleApp state、accessibility state、focus state、pixel state、protocol stateTest statuspass、fail、skip、environment_errorObserved behaviordelivered、refused、no_effect、error、not_run有两个容易被误读的概念需要特别澄清文档原文强调焦点保持Focus preservation是跨切面的 Oracle而不是独立的矩阵族。当测试一个后台动作时该行除了检查目标应用的外部状态还必须挂接平台焦点观察器platform focus observer用于验证焦点未被窃取。AX 与 PX 描述的是动作如何寻址目标而不是采集模式。get_window_state会同时返回树与截图动作则使用元素索引或坐标。也就是说AX 指通过辅助功能树寻址元素PX 指通过像素坐标寻址二者与是否采集窗口无关。三、单元与确定性协议测试无桌面的快速反馈层这一层不运行仓库本地 GUI 应用用于在 CI 中快速验证驱动内核。文档给出的覆盖清单如下领域位置覆盖范围核心驱动逻辑rust/crates/*/src/**协议值、会话、模式、图像辅助、输入辅助、配置、遥测、CLI 行为MCP 与 CLI 边界rust/crates/cua-driver/tests/protocol_*握手、工具注册、工具调用、媒体、会话与错误生命周期会话与目标迁移核心session、session_tools、action_target及兼容性capture_scope测试外加session_capture_scope_test.rs每个传输一个隐式会话、五分钟空闲策略、进行中与精确一次清理、所有者作用域检查与恢复、每次调用目标校验、遗留 capture-scope 兼容性工具契约门禁schema_consistency_test.rs跨 OS 后端共享工具模式一致性与已评审风险元数据配置传输transport_config_persistence_test.rsCLI 与 MCP 配置持久化Token 与协议面protocol_element_token_test.rs及相关测试JSON-RPC 可见的契约行为权限模式与策略启动permission_policy_startup_test.rs、daemon_required_test.rs、核心authorization、policy、session_manifest测试绑定前失败fail-before-bind的策略加载、托管/用户交集、不可变的 standard/autonomous/unrestricted 启动、危险确认、管理员禁用、默认拒绝清单、规范守护进程分发受保护浏览器授权核心consent、browser::grant、browser::engine、browser::v2_tests精确请求摘要、provider 认证接缝与期限、持久指示器激活、Stop/会话拆除、伪造遗留工件拒绝、精确 PID/窗口清单作用域、变更前使用的 live-origin 决策路径这些测试的实际载体都可以在仓库中直接找到例如 cross_platform_behavior_test.rs、protocol_handshake_test.rs、protocol_tools_call_test.rs、protocol_session_test.rs 等。文档特别说明了两条纪律部分协议测试会拉起驱动进程但它们不启动真实目标应用、也不要求桌面因此仍属确定性测试应与 Harness E2E 分开、按单元门禁上报。普通单元门禁不得运行被#[ignore]标记的 GUI 测试也不得把缺失桌面 fixture 悄悄变成静默跳过。四、Harness E2E共享 Web 应用Electron / Tauri / WKWebViewElectron 与 Tauri 是两个独立的仓库本地应用共同加载同一个共享 Web Harness。该 fixture 暴露的是动作专属控件与外部状态标记而不是一个把动作重复实现一遍的应用任务——这样做的目的是让 Oracle 观察的是真实 UI 状态而非应用内部逻辑的复读。4.1 共享 Harness 的源码位置文档声明的源码来源index.htmlelectron 应用目录tauri 应用目录cross_platform_behavior_test.rs从 index.html 可以看到这套 fixture 的设计每个控件都带有data-cua-id属性与配套的mirror状态回显如counter0、mirror、key_statenone、editor_statusdraft、slider_value0、drag_statusidle、last_actionnone、clicks0同时页面还内置了WEB_HARNESS_MARKER_v1等确定性标记。这套控件 状态镜像 确定性标记的三角结构正是外部 Oracle 得以在不动应用代码的前提下读取动作效果的关键。4.2 共享 Harness 暴露的动作族动作族动作寻址投递指针左键单击、右键单击、双击AX 与 PX后台与前台键盘与文本输入文本、Return、热键、输入后 Return支持处 AX 与 PX后台与前台滚动滚动支持处 AX 与 PX后台与前台子窗口打开子窗口AX 与 PX后台与前台拖拽从拖拽源拖到放置目标PX后台与前台状态控件复选框、单选、组合框、滑块按控件 AX 或 PX每个动作声明模式编辑器输入、保存、已保存状态回读支持处 AX 与 PX每个动作声明模式4.3 40-cell 目录体系与跨平台规模Rust 共享目录为每个 Harness 应用声明40 个带证据的测试单元cellWindows 与 Linux跨 Electron 与 Tauri 共运行80 个共享 cellmacOS额外运行原生 WKWebView 宿主合计120 个共享 cell。每个宿主都覆盖AX/PX × 前台/后台的完整叉积作用于点击、文本、键盘、顺序输入后 Return、滚动、子窗口动作外加 PX 拖拽与 AX 编辑器保存的两种投递模式。4.4 后台动作的严格验收条件这是本文档最有价值的部分之一也是防止假绿的关键闸门后台能力拒绝是合法结果但仅当测试验证了声明的结构化拒绝structured refusal且验证了无焦点/无 z-order 变更/无输入泄漏副作用时才成立后台姿态要求一个前台窗口包含目标几何区域而不仅仅是与之重叠通道预检lane preflight会主动注入故意的焦点与输入违规并要求哨兵sentinel在结果被采信之前把两者都检测出来对契约要求投递的 cell拒绝即失败规范上报拒绝 skip未过滤运行必须执行完整共享目录规模允许诊断性过滤但匹配零个 cell 永远是错误。五、Harness E2EWindows 原生 HarnessWindows 原生 Harness 均为从源码构建的仓库本地应用文档声明的覆盖如下Harness源码测试覆盖WPFharness_wpf_test.rsUIA 控件、文本、按键、指针动作、滚动、拖拽、弹窗、菜单、模态窗口WinUI3harness_winui3_test.rsXAML 控件、文本、复选框/单选、滑块、组合框、弹窗WebView2harness_web_test.rs窗口发现、CDP 页面访问、JavaScript、DOM 点击路径桌面目标desktop_scope_windows_test.rs每次调用的窗口/桌面模态、全屏采集、屏幕绝对点击/滚动、严格拒绝桌面不变量TestkitDesktopObserver加类型化的启动/采集/光标所有者跨切面的焦点、z-order、最小化启动、截图、光标、桌面检查原生控件以 AX/UIA 状态作为 Oracle指针动作在工具契约要求坐标时也使用 PX。当前set_value行声明后台投递并挂接桌面副作用 Oracle。Windows 侧的具体实证基线122 行、99 次投递与 23 次精确拒绝等记录在 action-support.md 的Accepted baselines表中。六、Harness E2EmacOSHarness源码测试覆盖AppKitharness_appkit_test.rsAX 树/采集、AX 值/文本、AX 滚动、PX 点击、已证明投递模式下的前台滑块拖拽后台拖拽为精确拒绝SwiftUIharness_swiftui_test.rsAX 树/采集、后台点击/值设置、前台 popover 触发状态WKWebViewcross_platform_behavior_test.rs运行完整 40-cell 共享 Web 目录的专用原生宿主桌面目标desktop_scope_macos_test.rs每次调用的窗口/桌面模态、屏幕绝对动作投递、严格拒绝已安装应用启动/聚焦installed_app_launch_macos_test.rs规范登录通道下真实 Calculator/TextEdit 的启动与聚焦行为已安装应用文本installed_app_textedit_macos_test.rs规范登录通道下真实 TextEdit 的 AX 后台写入与验证macOS GUI 运行依赖已安装的 ScreenCaptureKit/AX 权限。维护者验收门禁运行在 macOS Lume runner guide 所描述的停止状态的 Lume SIP-off 黄金镜像的一次性克隆中。维护者从消毒后的公共基础镜像macos-tahoe-cua:26.5.2构建私有种子镜像。文档强调仓库本地 Harness 才是规范canonicalCalculator 与 TextEdit 只是支撑性的真实应用检查SwiftUI 的 popover 触发是独立于剩余瞬态面板 AX 发现缺口而被证明的。从 macos-lume README 可以看到这套门禁的完整运维细节公共镜像只含 macOS Tahoe 26.5.2SIP 关闭、CLT 26.6、自动登录、SSH私有种子才持有工具链、签名身份与 TCC 授权每次运行都要通过run-all.sh先重装精确提交再做预检预检会拒绝错误的 OS、用户会话、SIP 状态、脏源码、ad-hoc 签名、过期守护进程与不可用的 TCC 授权并支持--retry-cell精确重试单个共享 Web cell仅限共享 Web 动作 cell重试记录会如实写入retry-record.json。七、Harness E2ELinuxHarness源码测试窗口系统覆盖Electroncross_platform_behavior_test.rsX11 与托管 Sway共享 Web 动作矩阵Tauricross_platform_behavior_test.rsX11 与托管 Sway共享 Web 动作矩阵GTK3harness_gtk3_test.rsX11/AT-SPI以及配置处的 Wayland/AT-SPI原生 GTK 控件与输入桌面目标desktop_scope_linux_test.rsX11/Wayland每次调用的窗口/桌面模态、屏幕绝对动作投递、严格拒绝Nix 提供 Linux 构建与桌面环境。文档特别强调X11 与 Wayland 是两条独立的矩阵维度因为它们的采集与输入契约不同Linux 运行不产生 GIF 输出每个规范 GUI cell 都会保留MP4 与轨迹trajectory连同截图、AX 树、结构化结果与驱动日志一起作为 E2E 证据。八、动作投递矩阵Action Delivery Matrix当前各 OS 的投递/拒绝台账维护在 action-support.md本节定义覆盖策略台账记录实证状态。对每个支持该动作的 OS 与 Harness规范 E2E 套件都应覆盖两种投递模式动作后台前台寻址左键单击必须投递或声明拒绝契约必须AX、PX右键单击必须投递或声明拒绝契约必须AX、PX双击必须投递或声明拒绝契约必须AX、PX拖拽必须投递或声明拒绝契约必须PX辅以 AX 发现滚动必须投递或声明拒绝契约必须支持处 AX、PX输入文本必须投递或声明拒绝契约必须支持处 AX、PX按键必须投递或声明拒绝契约必须支持处 AX、PX热键必须投递或声明拒绝契约必须支持处 AX、PX设置值当前原生行必须不单独声明AX/UIA/AXValue截图N/AN/A窗口或桌面采集Page/CDPN/AN/A页面选择器/JavaScript其中N/A表示该 API 对该操作不存在投递模式。拒绝只有同时满足三个条件才是一次通过的观察Rust 用例预期拒绝、拒绝码精确匹配允许值、桌面副作用 Oracle 全部通过。补充一点来自 action-support.md 的语义澄清AX 与 PX 描述的是目标如何被选中二者并不要求相同的投递后端——PX 目标可能经过命中测试后通过 AX/UIA 投递当这是后台安全路线时。台账中的每个结论都由类型化CaseSpec行与已接受 E2E 证据导出而不是仅凭驱动成功响应。九、CI 与本地入口点文档给出的各门禁及其入口如下门禁环境入口Linux 单元/源码Nix Linux CInix build .#checks.x86_64-linux.cua-driver-build .#checks.x86_64-linux.cua-driver-linux-rust-unitWindows 单元/编译windows-latest包作用域内cargo test --all-targets --no-run --lockedWindows Harness E2E活动的 Windows 用户会话scripts/ci/windows/run-rust-e2e.ps1 -RequireGuiLinux X11 Harness E2ENix X11 会话scripts/ci/linux/run-rust-e2e.shLinux Sway Harness E2E受控 wlroots 会话scripts/ci/linux/run-rust-e2e-wayland.shLinux 嵌套合成器 E2E受控实验会话scripts/ci/linux/run-rust-e2e-inject.shLinux 代表性桌面 E2E现有 GNOME、KDE 或 Xorg 登录scripts/ci/linux/run-rust-e2e-desktop.sh desktopmacOS Harness E2E维护者 Lume SIP-off 工作机已登录会话 继承授权packages/cua-driver/tests/runners/macos-lume/run-all.sh围绕这些入口仓库中实际可查看的运行器脚本还包括 tests/runners/windows/run-all.ps1、tests/runners/windows-sandbox/ 与 tests/runners/macos-lume/ 目录下的run-all.sh、run-rust-e2e.sh。文档强调了一个重要的职责切分工作流选择私有执行通道Rust 源码拥有场景定义、fixture Oracle 与结果记录OS 运行器只负责构建驱动、暂存本地 Harness、建立桌面会话、收集证据并发布共享报告。这套场景与运行分离的架构保证了矩阵定义只有一份权威来源。十、证据与所有权每个 cell 必须产出的工件文档规定每个 Harness E2E cell 都应产出以下工件recordings/cell-label-pidpid-sequence/recording.mp4 recordings/cell-label-pidpid-sequence/trajectory.json results.jsonl rust-target.logGitHub summary 会从对应行链接到该 cell 在通道归档中的精确录制路径目标日志仅是通道级诊断。单元测试需要日志与测试结果输出但不需要桌面视频。这一证据契约在 e2e-ci-reporting.md 中有更细的展开cases.jsonl是已执行目录results.jsonl每个结果都带精确的 cell 标签、状态与证据路径trajectory.json记录行为视频阶段pending、started等并最终定稿 MP4。也就是说录制 轨迹 结构化结果 日志四件套是每个桌面行为 cell 的强制证据缺一不可。十一、维护规则新增动作/模态的跨 OS 清单文档最后给出了明确的协作式维护纪律——当新增一个动作或模态时必须同步更新四处本文档test-matrix.md共享 fixture OracleRust 测试OS 特定的运行器选择。文档点明这是跨 OS 检查清单它防止一个仅 Windows 通过的测试被误当作跨平台覆盖。与之呼应action-support.md 也声明其维护规则只有当类型化行被增删或契约变更、且实证运行支持该变更时才更新台账驱动能在派发前判定的不支持投递应保持为精确拒绝当 OS API 报告成功却无法回读效果时宁可保留可见的 gap也不要在生产代码中发明一个 fixture 专属的拒绝码。十二、总结这套矩阵的设计哲学通读 test-matrix.md 与其配套台账 action-support.md、e2e-ci-reporting.md 及 macOS Lume runner guide可以提炼出这套测试体系的三条核心原则外部 Oracle 优先动作成败由 fixture 状态与桌面副作用判定驱动自报的成功不作数拒绝必须匹配精确的拒绝码且焦点、z-order、光标、输入泄漏等副作用 Oracle 全过才算合法拒绝。维度即可比性每个结果都必须声明 OS、窗口系统、Harness、寻址方式、投递模式、作用域、Oracle 与行为状态使 Windows 的一行结果能与 macOS 或 Wayland 的对应行严格对照。证据与场景分离场景定义、fixture 与结果记录归 Rust 源码所有运行器只负责搭环境、采证据、出报告新增行为必须同步更新文档、fixture、测试与运行器四处杜绝单平台通过冒充跨平台覆盖。对任何需要在真实桌面上驱动 GUI 应用、并希望以可复现方式验收后台不抢焦点、前台精确命中的 Agent 运行时项目而言这套矩阵维度、拒绝契约与证据工件模型都是一份可以直接借鉴的工程蓝本。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考