qwen-code cua-driver Windows Rust Runner 实战指南在 RDP/交互式桌面会话中驱动 Windows GUI 测试矩阵【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code本篇指南围绕 qwen-code 仓库中packages/cua-driver的 Windows Rust harness runner 展开讲解如何通过tests/runners/windows/run-all.ps1在 Azure RDP 或交互式 scheduled-task 验证环境中构建仓库内 Windows fixtures、运行 Rust 单元测试与 typed harness 矩阵并正确处理 Session 0、GUI 会话锁定与可选外部应用套件的取舍。读完本文你将掌握该 runner 的完整运行链路、参数语义、fixtures 构建方式以及从桌面状态诊断到 CI 强制的全套 Windows GUI 验证方法论。一、Windows Rust Runner 是什么一句话定位在 qwen-code 的packages/cua-driver测试体系中tests/runners/windows/README.md所描述的是Windows 平台的 Rust harness 运行器runner。它服务于一个明确的前提cua-driver 需要验证的是“真实交互式用户桌面”上的 GUI 行为窗口激活、焦点保持、UIA/AX 树定位、桌面轨迹录制等因此必须在RDP 会话或交互式控制台会话中运行而不能在无头环境里假装完成。该 runner 的核心职责依据 tests/runners/windows/README.md可以归纳为三点构建仓库本地repo-local的 Windows fixtures即 WPF、WinUI3、WebView2、Electron、Tauri 等确定性宿主测试应用运行 Rust 单元测试与 typed harness 矩阵包括protocol_*、schema_*、harness_toolkit_*、desktop_scope_windows_*等分类有意跳过可选外部应用套件例如 LibreOffice因为这类套件依赖环境镜像中额外安装的软件不属于仓库内 fixtures 的可复现范围。二、如何运行两条入口命令与参数语义原文档给出了最核心的用法。在packages/cua-driver目录下、且处于RDP 或控制台console会话中执行# 基础运行构建 fixtures 并跑完整 Rust harness 矩阵 .\tests\runners\windows\run-all.ps1 # 强制校验 GUI 桌面可用把桌面不可用的自跳过升级为硬失败 .\tests\runners\windows\run-all.ps1 -RequireGui-RequireGui开关的深层含义需要结合源码理解。查看 run-all.ps1 的实现可以发现该脚本本体非常薄它是所有平台 runner 的统一“门面”param( [switch]$NoBuild, # 跳过 fixtures 构建复用上一次的构建产物 [switch]$RequireGui # 要求真实可用的 GUI 桌面否则失败 ) Set-StrictMode -Version Latest $ErrorActionPreference Stop $repoRoot Resolve-Path (Join-Path $PSScriptRoot ..\..\..\..\..) $canonicalRunner Join-Path $repoRoot scripts\ci\windows\run-rust-e2e.ps1 if (-not (Test-Path $canonicalRunner)) { throw Canonical Windows E2E runner not found: $canonicalRunner } $canonicalRunner -NoBuild:$NoBuild -RequireGui:$RequireGui exit $LASTEXITCODE关键信息有两点调用链run-all.ps1本身不做测试执行它定位仓库根目录从$PSScriptRoot向上回溯五级并委派给仓库级规范入口scripts/ci/windows/run-rust-e2e.ps1最后以exit $LASTEXITCODE透传退出码保证 CI 能正确捕获失败参数透传-NoBuild与-RequireGui原样透传。-RequireGui的作用在 Rust 侧由环境变量CUA_REQUIRE_GUI承接——在专用 GUI 运行器上设置CUA_REQUIRE_GUI1即可把桌面自跳过self-skip变成硬失败并输出完整的桌面状态诊断见 Rust 集成测试 README。注意虽然run-all.ps1是文档推荐的面向 RDP/console 会话的入口但在当前仓库快照中scripts/ci/windows/run-rust-e2e.ps1并未随库检出仓库只读且不包含该 CI 目录因此实际可查看、可验证的入口即为tests/runners/windows/run-all.ps1本身及其上层测试文档。文章其余部分以仓库内已确认存在的源码与文档为事实依据。三、为什么必须用 RDP / 交互式 scheduled taskSession 0 与桌面可达性Windows Rust Runner 最容易被忽略、也最容易踩坑的是运行环境约束。这不是跑一个普通命令行测试而是要在“有人登录、桌面解锁”的交互式会话中驱动真实 GUI。仓库的 Rust 集成测试 README 明确警告Windows GUI tests require a usable interactive desktop. SSH-launched commands start in Session 0 and cannot drive the users desktop directly; launch GUI tests through an interactive scheduled task (/IT) or equivalent so they run in the logged-on user session.这句话背后的 Windows 会话模型是SSH 启动的命令默认运行在 Session 0服务会话无法直接驱动已登录用户的桌面窗口不显示、UIA 树不可达、截图与鼠标注入都会失败。因此正确的启动方式是通过RDP登录到目标 GUI VM在 RDP 会话内直接运行 runner或通过交互式 scheduled task/IT标志让任务在已登录的用户会话中执行等价于把测试进程放进真实桌面。如果当前输入桌面不是Default或无法打开通常意味着会话被锁定或断开。文档给出的处置手段是见 Rust 集成测试 README重新连接 RDP在一次性 GUI VM 上使用tscon /dest:console将会话切换到控制台或者将 VM 启动到未锁定的控制台会话后再运行被#[ignore]标记的 GUI 测试。此外testkit 的原生DesktopObserver会记录前景窗口、Z 序、光标与泄漏输入状态用于断言“承诺无桌面副作用”的行row。这正是-RequireGui/CUA_REQUIRE_GUI1的用武之地——它把这些桌面自跳过变成硬失败防止 CI 在不可用的桌面上“假绿”。四、Runner 到底跑什么Windows harness 矩阵与测试命名约定进入packages/cua-driver后Rust 侧测试位于 packages/cua-driver/rust/crates/cua-driver/tests/。命名约定决定了哪些测试默认执行、哪些需要 GUI 环境测试前缀默认执行目的protocol_*_test.rs是MCP/CLI 协议与 schema 行为session_capture_scope_test.rs是每会话策略隔离、升级、生命周期与废弃配置键schema_*_test.rs是生成 schema 的一致性harness_toolkit_test.rs否标记#[ignore]特定 toolkit 的 harness 应用desktop_scope_os_test.rs否标记#[ignore]平台窗口/桌面作用域契约也就是说Windows Rust Runner 跑的核心就是这些默认不跑的#[ignore]GUI 测试——通过run-all.ps1这类规范入口在真实桌面上以带--ignored的方式执行。Windows 平台对应的主要是harness_wpf_test.rs、harness_winui3_test.rs、harness_webview_test.rs等 toolkit 专属用例desktop_scope_windows_test.rs平台窗口/桌面作用域契约cross_platform_behavior_test.rs跨平台行为矩阵对 Electron 与 Tauri 运行相同的外部状态场景Windows 上对应 UIA 表面其矩阵行action、AX/PX 定位、前台/后台投递、作用域、driver 路由、外部 oracle、期望行为声明在cases.jsonl观察结果与派生状态记录在results.jsonlRust reporter 校验两者并渲染summary.md。同时仓库级 runner 会设置CUA_E2E_RECORDINGS_ROOT让每个 testkitMcpDriver把完整桌面轨迹录制到独立目录包含recording.mp4、光标采样、action JSON、每轮截图与trajectory.json测试标签清单。Windows 上需要 FFmpegrunner 会用ffprobe校验每个 MP4 后才报告成功另有 Rust 预检在行为用例运行前一次性验证桌面、fixture、AX 树、截图与视频生命周期。五、fixtures 从哪来构建仓库内 Windows 测试应用Runner “构建 repo-local Windows fixtures”的含义详见 tests/fixtures/README.mdfixtures 是**源码优先source-first**的确定性宿主应用构建脚本会把产物 stage 到packages/cua-driver/rust/test-apps/harness-name/二进制不提交进仓库。Windows 侧的 fixture 应用位于 tests/fixtures/apps/windows/Harness源码位置Staged 输出主要测试表面WPFapps/windows/wpfharness-wpfUIA/WPF 控件WinUI3apps/windows/winui3harness-winui3UIA/XAML 控件WebView2apps/windows/webview2harness-webviewChromium web UIAElectronapps/cross-platform/electronharness-electronChromium web AX/UIA/AT-SPITauriapps/cross-platform/tauriharness-taurinative webview AX/UIA/AT-SPI构建命令在packages/cua-driver/tests/fixtures下# 全量构建WPF、WinUI3、WebView2、Electron、Tauri .\build\windows.ps1 # 跳过某个 toolkit .\build\windows.ps1 -Skip winui3Windows 宿主要求.NET 8 SDK、Node.js/npmElectron、RustTauri。共享的shared/scenarios.json是所有 AutomationId、AX 标识符、期望窗口标题与 fixture 名的唯一事实来源webview 类 harness 会加载共享的shared/web/index.html。这意味着 runner 构建出的每个 fixture 都符合同一套共享场景契约测试矩阵无需为各 toolkit 各写一套断言基线。六、为什么跳过 LibreOffice可选外部应用套件的边界原文档特别强调 runner“intentionally skips optional external-app suites such as LibreOffice”。这类套件的定位在 Rust 集成测试 README 中有完整说明它们是针对真实已安装应用的 Rust 源码级覆盖但不属于规范 run-all 路径因为它们依赖仓库内 fixtures 之外的软件或桌面状态harness_libreoffice_test.rsWindows LibreOffice Writer/Calc需要安装 LibreOffice或通过LO_SWRITER_EXE/LO_SCALC_EXE指向可执行文件installed_app_launch_macos_test.rs/installed_app_textedit_macos_test.rsmacOS 专属standalone_browser_behavior_test.rs已安装 Chrome/Edge 的浏览器工具用例需通过跨平台脚本单独跑。从设计上看这是一个可复现性与覆盖面的明确取舍仓库内 fixtures 保证任何干净环境都能复现结果而外部应用套件保留源码级事实来源、但按需在配好软件的环境上运行二者互不污染。这也是run-all.ps1有意只走 repo-local fixtures 的原因。七、与其他平台的呼应Windows Runner 在跨平台体系中的位置Windows Runner 并非孤岛它与 macOS、Linux 运行器构成同一套跨平台验证方法论macOS的规范入口是 tests/runners/macos-lume/run-all.sh它要求已登录用户会话并在委派给scripts/ci/macos/run-rust-e2e.sh前校验已安装 driver 的 Accessibility 与 Screen Recording 授权Linux的仓库级入口是scripts/ci/linux/run-rust-e2e.shWindows即本文主题run-all.ps1→scripts/ci/windows/run-rust-e2e.ps1 -RequireGui。三者共享同一套 fixturesElectron/Tauri 跨平台 各平台原生 toolkit、同一个cases.jsonl/results.jsonl/summary.md报告契约以及同一个CUA_E2E_RECORDINGS_ROOT轨迹录制体系。跨平台矩阵的权威维护点在 docs/test-matrix.md新增 harness、action、寻址模式、投递模式或操作系统相关的窗口系统用例时都要回写该矩阵。此外仓库还保留了Legacy Windows Sandbox路径tests/runners/windows-sandbox/run-tests-in-sandbox.ps1它会构建部分 Windows harness 应用并映射进沙箱。但正如 Rust 集成测试 README 所述当前 Windows GUI 验证路径应使用通过 RDP 或交互式 scheduled task 启动的真实用户桌面会话沙箱路径属于历史遗留。这正是-RequireGui存在的根本原因——GUI 测试必须见到真实桌面。八、实战排查清单让 Windows Runner 一次跑通综合以上源码与文档将常见故障与对策整理如下症状根因对策所有 GUI 用例自跳过会话锁定或断开输入桌面不可用重新连接 RDP一次性 GUI VM 上执行tscon /dest:console或将 VM 启动到未锁定控制台SSH 启动后窗口不可见命令落在 Session 0 服务会话改用 RDP 会话或通过交互式 scheduled task/IT在已登录用户会话中运行CI 上“假绿”桌面不可用时被静默跳过设置CUA_REQUIRE_GUI1配合-RequireGui将自跳过转为硬失败并输出桌面诊断recording.mp4校验失败Windows 侧缺少 FFmpeg在环境镜像中安装 FFmpegrunner 会以ffprobe校验视频fixtures 找不到未构建或构建产物被清理先运行tests/fixtures/build/windows.ps1或保留-NoBuild缺省行为让 runner 自行构建确认已安装 .NET 8 SDK、Node.js/npm、Rust需要复现外部应用行为LibreOffice 等不在 run-all 路径安装对应软件并设置LO_SWRITER_EXE/LO_SCALC_EXE按需运行harness_libreoffice_test.rs九、总结packages/cua-driver/tests/runners/windows/README.md描述的是一个“小入口、大体系”的典型设计run-all.ps1仅数十行负责解析-NoBuild/-RequireGui并委派给仓库级 CI runner真正的复杂度沉淀在 Rust 测试矩阵、source-first fixtures 构建与桌面会话管理之中。理解并善用这个 runner等于掌握了在 Windows 上对 cua-driver 做真实桌面级 GUI 验证的标准姿势——从 RDP/交互式任务的启动约束到CUA_REQUIRE_GUI的失败强制再到 fixtures 的可复现边界每一步都能在仓库源码与文档中找到对应依据。如需深入建议依次阅读 Rust 集成测试 README、fixtures README、test-matrix.md 与 test-harnesses-guide.md它们共同构成了这条 Windows 验证链路的完整地图。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考