如何测试桌面自动化?agent-desktop的E2E框架、真实应用验证与性能基准完全指南

原创2026-10-10 15:23:501,860 阅读
文章标签:GUI 自动化AI 技能CLI

如何测试桌面自动化?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 就永远不算通过。

也就是说,测试必须通过独立的辅助功能观察来验证效果:点击按钮后,要重新读一次状态文本;输入文字后,要独立读回字段值。这套思想贯穿了下面三个测试层次。

agent-desktop 桌面自动化框架架构总览图

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 工作流在测试层的落地。

agent-desktop 桌面自动化终端操作演示,AI Agent 驱动终端执行命令

六大场景脚本: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/ 目录就是为此存在的。

Slack 真实应用的辅助功能快照与骨架概览对比,agent-desktop 桌面自动化观察效果

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 的驱动,而是"第二双眼睛":

性能基准:合成、真实应用、A/B 对比三层

agent-desktop 骨架快照与完整快照 token 消耗对比图,30743 对 383

第一层:合成定位器基准

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 的桌面自动化能力:

  1. 单元测试与静态门禁:cargo test --lib --workspace + cargo clippy --all-targets -- -D warnings(详见 CONTRIBUTING.md)
  2. E2E 套件:AGENT_DESKTOP_E2E_EXCLUSIVE=1 bash tests/e2e/run.sh,在独占桌面 + 辅助功能权限的 macOS 机器上运行,headed 用例会移动真实鼠标,请确保安全
  3. 真实应用评估:按 real-apps/README.md 的协议对 Numbers 等应用做面向模型的可靠性评估,保留每次尝试的原始输出
  4. 性能回归:bash scripts/perf-baseline-compare.sh 生成 HEAD 与基线的对比报告;高权限环境下可追加 electron-live.sh 的真实应用 A/B 测量

这套体系给桌面自动化测试社区提供了一个很好的范本:fixture 保确定性、真实应用保真实性、基准保不退步、一致性测试保跨平台。命令说"成功"不算数,独立观察到了效果才算数——这正是"如何测试桌面自动化"最核心的答案。

登录后查看全文
agent-desktop