如何测试桌面自动化?agent-desktop的E2E框架、真实应用验证与性能基准完全指南
如何测试桌面自动化?agent-desktop的E2E框架、真实应用验证与性能基准完全指南
agent-desktop 是一个用 Rust 编写的桌面自动化工具,它让 AI Agent 通过操作系统辅助功能(Accessibility)树"看到"并操作任意应用的真实 UI。桌面自动化测试最大的难题在于:命令返回 ok: true 不代表操作真的生效。这篇文章带你拆解 agent-desktop 的三层质量保障体系——E2E 框架、真实应用验证、性能基准,看看它是如何做到"每个效果都可独立验证"的。
核心哲学:永远不信任 ok: true
桌面自动化测试与 Web 自动化最大的不同:你无法在受控的沙箱里跑测试。真实的鼠标在动、真实的窗口在切换、其他进程随时可能干扰。
agent-desktop 的 E2E 套件确立了一条铁律(见 tests/e2e/README.md):
只要 fixture 暴露了可观察的状态、值、进程、窗口或界面过渡,命令返回
ok: true就永远不算通过。
也就是说,测试必须通过独立的辅助功能观察来验证效果:点击按钮后,要重新读一次状态文本;输入文字后,要独立读回字段值。这套思想贯穿了下面三个测试层次。
E2E 框架:AgentDeskFixture 专用测试夹具应用
测试夹具:一个"自带答案"的 SwiftUI 应用
E2E 套件不会在 Finder、Safari 这类不可控应用上打转,而是构建并启动一个专用的 AgentDeskFixture.app(源码见 AgentDeskFixture.swift)。
这个 fixture 应用里预埋了各种"考点":
- 主按钮、延迟启用的按钮、永久禁用的按钮
- 可移除的行(用于验证失效 ref 的失败行为)
- 文本输入框与独立的状态回显区(用于输入验证)
- 重名的双窗口、Sheet、菜单、展开/收起控件
关键设计:fixture 上的每个控件都带一个"可独立观察的状态"。 点击主按钮后,状态栏会从 idle 变成 clicked-1、clicked-2——这既是断言依据,也能检测"延迟的重复点击"(AE2 验收项专门验证"只派发一次")。
一键运行 E2E 套件
AGENT_DESKTOP_E2E_EXCLUSIVE=1 bash tests/e2e/run.sh
run.sh 是全局编排入口,它做了几件"反污染"的事:
| 隔离手段 | 作用 |
|---|---|
EXCLUSIVE=1 独占确认 |
调用方必须声明桌面已独占(停掉用户输入和其他自动化),harness 锁阻止第二个原生测试并行启动 |
| 不可变二进制 + SHA-256 | 从当前 checkout 以 --locked 构建 CLI/FFI/helper,哈希后复制到只读路径,测试只使用这些副本 |
| 隔离 HOME 与临时目录 | 独立的 ref/session 存储,避免污染开发者真实状态 |
| 进程组 + 超时 + 输出上限 | 每个 CLI 子进程独立进程组,带绝对超时和有界 stdout/stderr 捕获 |
| 退出码语义 | 0 全部断言通过;1 行为失败;2 全局前置门槛失败 |
前置门槛检查也很严格:必须是 macOS、辅助功能权限已授予、fixture 可构建。fixture 启动后如果找不到预期的控件、窗口或状态读出,直接判失败——"缺失的前置条件永远不能变成一个成功的 SKIP"。
精确的 ref 命名空间:lib.sh 的失败关闭断言
lib.sh 提供 fail-closed 的断言和 {ref_id, snapshot_id} 成对目标助手。E2E 套件里,find 返回的 ref 与其 snapshot_id 是"不可分割的一对",后续所有 get、is、wait 都必须显式带上这个 snapshot。
套件甚至会故意在 find 和 get 之间插入无关的观察命令,来证明 ref 不依赖"最新快照指针"这种隐式状态——这正是 skills/agent-desktop/references/ 中推荐的 ref 工作流在测试层的落地。
六大场景脚本:E2E 套件测什么?
| 场景脚本 | 覆盖范围 |
|---|---|
| observation.sh | 快照、定位器、命名空间固定、严格双胞胎元素 |
| interaction.sh | 无头/有头动作、exact-once 效果验证 |
| acceptance.sh | AE1–AE7 命名验收契约 |
| reliability.sh | 失效 ref、等待谓词、drill-down、会话 |
| surfaces.sh | Sheet、菜单、拖拽、展开/收起 |
| trace_performance.sh | Trace 工件、敏感信息脱敏、耗时、清理 |
拿 reliability.sh 里的一个经典断言举例:先找到 removable-row 按钮,再点掉它的父容器让它从界面上消失,然后用原来的 ref 去点击——断言必须收到 STALE_REF/ELEMENT_NOT_FOUND 等错误,绝不允许通过一个失效 ref 派发点击。这就是"失效 ref 带着原命名空间失败关闭"的端到端验证。
AE1–AE7:把验收计划变成可执行断言
acceptance.sh 对可靠性计划中的每个例子逐一点名断言:
- AE1:帧为零的可寻址按钮必须报告
visible=false - AE2:CLI 与原生 release-FFI 消费者等待一个 800ms 后才启用的按钮,恰好派发一次,超时为零的立即检查不能产生迟到效果
- AE3:永久禁用按钮 +
--timeout-ms 2000,应返回TIMEOUT、details.kind=actionability_timeout,且last_report接近 2 秒 - AE4:两个同标题窗口获得不同 id,聚焦第二个 id 时聚焦的是那个精确窗口
- AE5:权限提示隔离、非提示 Automation 探测;Automation 被拒时,有头通知操作必须返回
PERM_DENIED(由确定性的 permission-contract.sh 在不改动 TCC 的前提下覆盖) - AE6:一个 batch 先捕获动作前基线,点击后弹出 Sheet,报告
surface_appeared - AE7:同样的禁用动作、不带超时标志,应在未改动的 5 秒默认值附近返回结构化超时
AE2/AE3/AE7 同时在无头和有头策略模式下运行,时间容差"宽到容忍进程启动和调度噪声,窄到能检测出缺失的等待、错误的默认值或无限期的超时"。
真实应用验证:从 fixture 到 Numbers 和 Xcode
fixture 测试提供确定性的回归,但不能证明在真实复杂应用里能完成任务。tests/real-apps/ 目录就是为此存在的。
Numbers 面向模型的可靠性评估
real-apps/README.md 定义了一套极严格的评估协议(当前基线冻结在 acceptance-v1.md):
- 模型必须直接读原始 JSON 并自己选 ref,禁止插入 Python/jq 提取、自定义 ref 挑选器、原始 AX 变异或 AppleScript 来"代打"
- 使用不可变 release 二进制 + 隔离的
AGENT_DESKTOP_HOME+ 一个自己拥有的文档AD Reliability.numbers - 任务包括:骨架遍历发现网格、选中 B2 并替换内容、编辑模式下读回原始 ref、切换 Sheet 并对比
get/is与实际激活状态、改行数再改回、进入公式后保存关闭重开 - 任何一步被阻塞,后续依赖任务记为未完成,绝不允许用脚本补数据然后算作 CLI 成功
配套脚本 numbers-sheets.sh 用同一组 ref 执行 10 次 Sheet 切换,"失败的点击会拍一张诊断截图,但永远不会重试"——重试会掩盖问题。
独立的原始 AX 诊断工具
tests/real-apps/ 下还有一组 Swift/Objective-C 诊断探针,它们不是 Agent Desktop 的驱动,而是"第二双眼睛":
- ax_probe.swift:绕过 Agent Desktop 内部,直接读原生属性/动作/可设置标志
- headless_probe.swift:独立进程监听工作区激活通知、输入计数器和指针采样,验证"无头操作没有偷偷激活应用、没有偷走输入"
- nested_scroll_fixture.m:嵌套滚动回归——
scroll-to前后各拍一张窗口截图,"仅仅返回verified: true不算有效的判定依据" - replace_range_probe.swift 与 replace_contract_fixture.m:文本替换参数传递的差异诊断
性能基准:合成、真实应用、A/B 对比三层
第一层:合成定位器基准
benchmarks/locator-resolution/ 是一个确定性基准,在合成的 Chromium/Electron 辅助功能树上对比"传统全量快照定位路径"与"无句柄的观察树求值器",专门覆盖最坏情况:
- 深层匿名包装器链(wrapper of wrapper of wrapper)
- 重复的 role/name 候选项
- 移动的 bounds、同时存在
AXIdentifier与AXDOMIdentifier - 大体积树
JSON 报告包含 31 次运行的 p50/p95 墙钟延迟、候选节点数、谓词工作量、基数与正确性。它能离线运行(cargo run --example locator_benchmark),所以可以进 CI;而需要辅助功能权限的原生 Slack/Electron 测量则留给高权限的 macOS 集成套件——职责划分非常清晰。
第二层:真实 Electron/Chromium 应用 A/B 基准
electron-live.sh 是可选(opt-in)的活体测量,run.sh 和无权限的 CI 永远不会调用它:
AGENT_DESKTOP_E2E_EXCLUSIVE=1 bash tests/e2e/electron-live.sh --app Slack \
--baseline-binary /path/to/previous/agent-desktop --out /tmp/vscode-ax.json
方法学相当严谨:
- 应用必须已安装、运行中且至少暴露一个窗口;harness 不启动、不聚焦、不点击、不输入、不关闭用户的应用
- 5 次热身对 + 31 次测量的
find --role button --first对 - 提供
--baseline-binary时,基线(A)与当前(B)二进制以平衡的 AB/BA 顺序跑在同一进程代际和窗口清单上,各自独立 HOME - 每对前后都检查应用状态;v3 JSON 模式包含 p50/p95 墙钟与 CPU、配对差值、成功率、AX 遍历统计、SHA-256/版本身份、原始样本
- 报告明确标注自己的局限:单一机器、单一应用状态;测的是观察与 ref 重新解析而非动作投递;没有显式基线就绝不编造
第三层:perf-baseline-compare.sh 汇总报告
scripts/perf-baseline-compare.sh 把三层串起来:构建当前 checkout 与 merge-base 两个 release 二进制 → 跑 fixture A/B(快照、读取、仅 fixture 的动作)→ 跑合成定位器基准 → 可选对真实应用做只读探测(仅 snapshot/find 计时,从不派发任何动作)→ 输出 HTML 报告与原始 JSON。真实应用探测被严格限定为只读,"绝不改变应用生命周期"。
一致性测试:为 Windows 和 Linux 提前铺路
tests/conformance/ 是跨平台一致性的关键设计:macOS 适配器是第一个实现,但测试是对着 PlatformAdapter 语义写的,未来的 Windows UIA 和 Linux AT-SPI 可以直接复用同一套期望。
conformance/README.md 列出了必过门槛与平台矩阵:
| 一致性区域 | 要求行为 |
|---|---|
| 快照 ref | 深度优先、快照作用域、显式 snapshot ID 直接解析 |
| 严格解析 | 身份匹配才能解析;失效 ref 返回 STALE_REF |
| 歧义 | 多个合理候选返回 AMBIGUOUS_TARGET,绝不任意点击 |
| 可操作性 | 派发前检查可见性、稳定性、启用状态、受支持动作、策略、可编辑性 |
| 等待恢复 | wait --element 尊重调用方超时并报告最后一次观察到的谓词状态 |
| FFI 一致性 | FFI ref 动作同样走严格解析与可操作性检查 |
矩阵要求"两个相同按钮产生歧义""ref 在快照后消失""禁用按钮在派发前被拦截"等用例在 macOS AX、Windows UIA、Linux AT-SPI 三列全部为 Required。可复用的命令路径助手在 ref_action_contract.rs,mock 冒烟 harness 已经用它跑通。
上手路径:从零跑通 agent-desktop 测试体系
🚀 按下面顺序,你可以逐层验证 agent-desktop 的桌面自动化能力:
- 单元测试与静态门禁:
cargo test --lib --workspace+cargo clippy --all-targets -- -D warnings(详见 CONTRIBUTING.md) - E2E 套件:
AGENT_DESKTOP_E2E_EXCLUSIVE=1 bash tests/e2e/run.sh,在独占桌面 + 辅助功能权限的 macOS 机器上运行,headed 用例会移动真实鼠标,请确保安全 - 真实应用评估:按 real-apps/README.md 的协议对 Numbers 等应用做面向模型的可靠性评估,保留每次尝试的原始输出
- 性能回归:
bash scripts/perf-baseline-compare.sh生成 HEAD 与基线的对比报告;高权限环境下可追加electron-live.sh的真实应用 A/B 测量
这套体系给桌面自动化测试社区提供了一个很好的范本:fixture 保确定性、真实应用保真实性、基准保不退步、一致性测试保跨平台。命令说"成功"不算数,独立观察到了效果才算数——这正是"如何测试桌面自动化"最核心的答案。



