qwen-code 仓库 cua-driver 冒烟测试指南：用 CLI 全量探针守护跨平台工具覆盖

qwen-code 仓库 cua-driver 冒烟测试指南用 CLI 全量探针守护跨平台工具覆盖【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文以 packages/cua-driver/tests/fixtures/smoke/README.md 为骨架介绍 qwen-code 仓库中 cua-driver跨平台 computer-use 自动化驱动Rust 实现的 CLI 冒烟测试体系它如何通过qwen-cua-driver call tool json这一条独立于 MCP stdio 的代码路径在约 30 秒内对全部注册工具做一轮 PASS / FAIL / SKIP 的宽泛探测并以基线结果文件 diff 的方式捕捉工具覆盖回退。读完本文你将掌握冒烟脚本的运行原理、工具分组与判定规则、基线比对流程、macOS 前置条件以及它和 Rust 集成测试之间的分工边界。一、冒烟测试在 cua-driver 测试体系中的定位cua-driver 是 qwen-code 仓库中负责让 Agent 操作真实桌面的驱动层Rust 工作区位于 packages/cua-driver/rust平台实现按 macOS / Windows / Linux 拆分如 platform-macos、platform-windows。验证如此庞大的工具面仓库采用了互补的两套测试维度Rust 集成测试CLI 冒烟测试入口packages/cua-driver/rust/crates/cua-driver/tests/下的*_test.rspackages/cua-driver/tests/fixtures/smoke/macos.sh驱动方式通过 MCP stdio 循环驱动 qwen-cua-driver通过 CLIqwen-cua-driver call tool json驱动覆盖代码路径MCP 协议层 工具实现CLI 参数解析器 工具解析/注册表断言粒度具体 UIA / AX 状态变化精确行为断言每个工具一次宽泛的 PASS / FAIL / SKIP耗时量级分钟级harness E2E 需--ignored显式运行约 30 秒一轮全量扫原 README 中明确点出集成测试drive qwen-cua-driver through the MCP stdio loop and assert on specific UIA / AX state changes而冒烟测试drive qwen-cua-driver through the CLI (qwen-cua-driver call tool json) — different code path (CLI argument parser tool resolution)。也就是说同一批工具存在两条可达路径冒烟测试的价值正是覆盖 MCP 之外的 CLI 入口——这是集成测试碰不到的解析层代码。集成测试的覆盖地图可参考 packages/cua-driver/rust/crates/cua-driver/tests/README.mdprotocol_*_test.rs、schema_*_test.rs默认运行harness_toolkit_test.rs与desktop_scope_os_test.rs因需要已构建的 harness 应用与交互式桌面而标记为#[ignore]。冒烟脚本则刻意不依赖 harness 之外的真实应用除 TextEdit 一处小例外在本地工作站即可快速执行。二、目录结构与脚本一览冒烟测试位于 packages/cua-driver/tests/fixtures/smoke当前结构如下tests/fixtures/smoke/ ├── README.md # 本文所依据的说明文档 ├── macos.sh # macOS 每工具冒烟测试入口 └── results/ # 基线结果文件目录如 results/macos.txt整个 fixtures 层的布局与维护规则见 packages/cua-driver/tests/fixtures/README.md测试夹具采用源码优先source-first策略构建脚本把本地产物暂存到packages/cua-driver/rust/test-apps/harness-name/二进制不入库。shared/scenarios.json是 AutomationId / AX 标识 / 期望窗口标题的唯一事实来源。原 README 中的表格目前只列了macos.sh一行Host OS 为 macOSSpawns the AppKit harness, calls every tool once。从脚本头注释可以确认它自称是scripts/linux-smoke.sh的镜像same shape, classified the same way说明设计上 Linux 也有同构的冒烟入口当前仓库只检入了 macOS 版本因此在 macOS 之外平台运行冒烟需要按同样的判定规则自行构建入口脚本。三、macOS 冒烟脚本运行流程拆解冒烟脚本 packages/cua-driver/tests/fixtures/smoke/macos.sh 是一段约 220 行的 bash整个流程可拆成五个阶段3.1 前置检查与二进制定位脚本先解析仓库根目录相对自身位置上溯四层得到ROOT再按优先级选择驱动二进制DRIVER$ROOT/packages/cua-driver/rust/target/release/qwen-cua-driver [[ -x $DRIVER ]] || DRIVER$ROOT/packages/cua-driver/rust/target/debug/qwen-cua-driver随后定位 harness 应用与其可执行文件HARNESS_APP$ROOT/packages/cua-driver/rust/test-apps/harness-appkit/CuaTestHarness.AppKit.app HARNESS_EXE$HARNESS_APP/Contents/MacOS/CuaTestHarness.AppKit两个硬性前置条件缺一不可缺失时脚本直接报错退出exit 1驱动二进制缺失 → 提示运行cd packages/cua-driver/rust cargo build --release -p cua-driverAppKit harness 未构建 → 提示运行packages/cua-driver/tests/fixtures/build/macos.sh。3.2 启动受害者应用并解析窗口脚本把 AppKit harness 作为被操控的目标应用victim后台拉起等待 1.5 秒后调用list_windows获取窗口列表再用 python3 过滤出 pid 匹配且标题含 AppKit 的窗口得到真实的window_idWIN_JSON$($DRIVER call list_windows {\pid\:$HARNESS_PID} 2/dev/null) WIN_ID$(printf %s $WIN_JSON | python3 -c ...)窗口 id 解析失败不会终止脚本而是让依赖它的工具统一判为 SKIP详见 3.4。3.3 六组工具依次探测脚本将全部工具按语义分成六组依次执行no-arg / 信息类check_permissions、get_screen_size、get_cursor_position、get_config、get_recording_state、list_apps、list_windows外加带 session 参数的get_agent_cursor_statesetter 类set_config{max_image_dimension:1024}、set_agent_cursor_enabled、set_agent_cursor_themetheme_id: cua.default、set_agent_cursor_motion、stop_recording应用生命周期launch_app启动 TextEdit→ 取 pid →kill_app若 TextEdit 没起来则记录kill_app FAIL按窗口状态get_window_statecapture_mode:tree、get_accessibility_tree、zoom坐标区域 0,0–200,200输入合成move_cursor、click、double_click、right_click、drag、scroll、type_text、press_key、hotkey、bring_to_front无窗口 id 时整组 SKIP别名/特殊工具type_text_chars、page、replay_trajectory三个按设计记录为 SKIP 并写明原因。每组调用都携带贴合语义的 JSON 参数例如基于坐标的点击族run_tool click {\pid\:$HARNESS_PID,\window_id\:$WIN_ID,\x\:120,\y\:80} run_tool double_click {\pid\:$HARNESS_PID,\window_id\:$WIN_ID,\x\:120,\y\:80} run_tool right_click {\pid\:$HARNESS_PID,\window_id\:$WIN_ID,\x\:120,\y\:80} run_tool drag {\pid\:$HARNESS_PID,\window_id\:$WIN_ID,\from_x\:120,\from_y\:80,\to_x\:180,\to_y\:120,\delivery_mode\:\foreground\} run_tool hotkey {\pid\:$HARNESS_PID,\window_id\:$WIN_ID,\keys\:[\cmd\,\a\]}这些调用走的是 CGEvent 路径即使 AX 目标定位不精确也能覆盖底层事件注入逻辑。3.4 PASS / FAIL / SKIP 判定规则核心判定逻辑集中在run_tool()函数规则如下若输出匹配unsupported_on_platform/is Windows-only/is Linux-only/is macOS-only之一 → 判SKIP原因是intentional cross-platform stub on macOS。这表示工具被正确调用了但该工具在 macOS 上按设计就是占位实现退出码为 0 且输出不以❌或Error:开头 →PASS退出码为 0 但输出是❌/Error:开头 →FAIL标注 exit0❌退出码非 0 →FAIL标注实际 exit code。所有结果以TOOL|VERDICT|REASON行格式累积到临时文件最后用awk保留每个工具的最后一条记录later wins再按工具名排序输出汇总表TOOL VERDICT DETAIL ---------------------------------------------------------------- bring_to_front PASS ... check_permissions PASS ... ... Tools probed: 30 PASS28 FAIL0 SKIP2脚本退出码为[[ $fail -eq 0 ]]即存在任意 FAIL 时返回非零便于 CI 直接以退出码判定。3.5 一个值得注意的 bash 陷阱脚本注释专门记录了run_tool中参数缺省值的一个坑不要写${2:-{}}——bash 会把它解析成${2:-{}加字面量}最终得到{而非{}破坏下游 JSON 解析。正确写法是先判断再赋值local args if [[ -z ${2-} ]]; then args{}; else args$2; fi这是从scripts/linux-smoke.sh踩坑后同步过来的经验说明冒烟脚本在跨平台移植时对细节要求很高。四、基线比对用 diff 捕捉工具覆盖回退原 README 给出的核心使用方式是基线比对——每个脚本把当前驱动版本的探测结果检查进results/目录通过 diff 发现工具覆盖的回归./macos.sh /tmp/run.txt diff results/macos.txt /tmp/run.txt工作流是在某个已知良好的驱动版本上运行./macos.sh把输出落盘为results/macos.txt对应 macOS修改工具注册表、参数解析或平台实现后重跑同一命令diff比较新输出与基线新增/消失的工具行、PASS 变 FAIL、FAIL 变 PASS 都一目了然。配合 3.4 的汇总统计Tools probed: N PASSx FAILy SKIPz可以把工具面是否回退压缩成一个数字加一份 diff非常适合放进 CI 冒烟阶段。需要注意基线文件与驱动版本是绑定的——升级驱动版本后应重新生成基线而不是盲目对比旧基线。五、macOS 前置条件Prereqs原 README 列出了三项 macOS 前置条件逐条展开如下AppKit harness 已构建packages/cua-driver/tests/fixtures/build/macos.sh必须已把产物生成到packages/cua-driver/rust/test-apps/harness-appkit/。harness 的源码在 packages/cua-driver/tests/fixtures/apps/macos/appkit/main.swift是单文件 Swift AppKit 应用窗口标题固定为CuaTestHarness AppKit内置 counter、text_body、text_input、click_target、slider、context_menu、scroll_target、ns_menubar、exit 等可被 AX 寻址的控件AX 标识与shared/scenarios.json中的appkit段一一对应驱动二进制已构建packages/cua-driver/rust/target/release/qwen-cua-driver脚本也会回退到 debug 构建。构建命令为cd packages/cua-driver/rust cargo build --release -p cua-driverTCC 辅助功能授权qwen-cua-driver 二进制需要被授予 macOS 的 Accessibility辅助功能权限。脚本注释特别警告没有该权限时 AX 类工具会返回空树但因为调用本身干净退出exit 0会被误判为PASS——输出中会标注这一情况解读结果时需留意。此外运行环境需要 bash 3.2 兼容的写法macOS 自带 bash 3.2不支持关联数组脚本因此用新行分隔的 TOOL|VERDICT|REASON累积再排序去重以及可用的python3用于解析list_windows返回的 JSON。六、冒烟测试的 SKIP 语义与集成测试的衔接冒烟脚本中的 SKIP 并非没测而是按设计不在这里测。脚本在最后几组集中声明了三类 SKIP并在 REASON 中写明原因工具判定原因type_text_charsSKIP已废弃别名由 mcp-server 的 invoke 层解析到type_text不在工具注册表中与 Windows 侧 parity 修复后的行为一致pageSKIP需要带--remote-debugging-port的 Chromiumreplay_trajectorySKIP需要一份已录制好的 trajectory 文件set_valueSKIP需要element_index没有快照拿不到改由harness_appkit_text_input集成测试覆盖这种冒烟只覆盖无额外夹具依赖的工具重夹具场景交给集成测试的分工是测试矩阵的成本分层设计。深入的交互式场景如set_value的文本输入、Electron/Tauri 动作矩阵由 harness_appkit_test.rs 等#[ignore]集成测试和 cross_platform_behavior_test.rs 承担运行方式见 packages/cua-driver/rust/crates/cua-driver/tests/README.mdcargo test -p cua-driver --test harness_appkit_test -- --ignored --nocapture七、从源码看 CLI 冒烟路径覆盖了什么冒烟脚本使用的qwen-cua-driver call tool json子命令由 packages/cua-driver/rust/crates/cua-driver/src/cli.rs 实现。从源码可见其入口语义文件头注释即列出完整子命令表qwen-cua-driver → mcp server默认 qwen-cua-driver list-tools → 打印全部工具名 描述 qwen-cua-driver describe tool → 打印工具 schema qwen-cua-driver call tool [json-args] → 调用工具打印结果 qwen-cua-driver tool [json-args] → call 的简写形式也就是说冒烟测试实际验证的代码路径是call位置参数解析含VALUE_FLAGS跳过逻辑→ 工具名映射 → JSON 参数serde_json解析 → 工具注册表解析与分发 → 平台工具实现。这与集成测试经由 MCP JSON-RPC 的路径在解析层完全分叉正是原 README 强调different code path的用意。脚本中还展示了两个与 CLI 解析强相关的细节简写调用run_tool list_windows {\pid\:$HARNESS_PID}走的就是首个位置参数即工具名的隐式 call 分支与显式call分支共用同一套 JSON 解析错误处理stdin 兜底cli.rs 中call在没有位置参数 JSON 时回退到read_stdin_json()而 PowerShell 5.1 会剥离多字段 JSON 的引号导致解析失败报错信息会引导用户改用管道传 JSON——这是冒烟脚本用 bash 而非 PowerShell 编写的原因之一。八、运行与解读速查综合原 README 与脚本实现macOS 上完整跑一轮冒烟测试的步骤为# 1. 构建驱动release 优先debug 也可 cd packages/cua-driver/rust cargo build --release -p cua-driver # 2. 构建 AppKit harness packages/cua-driver/tests/fixtures/build/macos.sh # 3. 授予 qwen-cua-driver 辅助功能TCC Accessibility权限 # 在「系统设置 → 隐私与安全性 → 辅助功能」中勾选 # 4. 运行冒烟测试并与基线比对 ./macos.sh /tmp/run.txt diff results/macos.txt /tmp/run.txt结果解读原则PASS 工具干净退出exit 0输出无❌FAIL 报错或非零退出需要结合 REASON 中的首行输出定位SKIP 有意不探测跨平台占位、被集成测试覆盖、缺少外部夹具不代表功能异常无 TCC 权限时 AX 工具的 PASS 是假绿解读前先确认权限已授予脚本退出码直接反映FAIL数量[[ $fail -eq 0 ]]可无缝接入 CI 判断。九、维护与扩展提示从 packages/cua-driver/tests/fixtures/README.md 的维护规则可以提炼出与冒烟测试相关的约束新增共享控件 id 时先写进shared/scenarios.json再在测试中断言平台特有行为留在对应平台的 Rust 测试或应用源码里不要塞进共享 fixture行为证据通过 Rust testkit 与规范 OS runner 记录不要再叠加第二套 Python 或 shell 断言层——冒烟脚本是宽泛探测 基线 diff的定位精确行为断言留给集成测试新增工具时应同步在冒烟脚本中补充对应分组的run_tool调用并更新results/基线否则新工具会游离在 CLI 路径的覆盖之外。结语cua-driver 的 CLI 冒烟测试用约 30 秒的成本换来了对整个工具面在 CLI 解析路径上的持续守护它不追求精确行为断言那是 Rust 集成测试的职责而是以 PASS / FAIL / SKIP 三分法加基线 diff快速捕捉工具消失、解析损坏、平台 stub 回归这类覆盖级问题。对 qwen-code 这类跨 Windows / macOS / Linux 的桌面自动化驱动而言这样一个轻量、可本地运行、可进 CI 的探针层是 MCP 集成测试之外不可或缺的补充。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考