用途
winui-ui-testing 用于为 Windows 桌面应用编写和运行自动化 UI 测试。它通过 WinApp CLI 0.7+ 提供的 winapp ui UI Automation（UIA）测试框架，生成一个批量测试脚本，一次性运行所有测试，而不是进行一长串交互式调用。
由于底层使用 Windows UI Automation，基于 AutomationId 的工作流适用于任何 Windows 桌面框架，无论应用是打包还是未打包。对于非 WinUI 框架，可跳过 WinUI 特有的绑定/对话框建议。
主要能力
核心动词包括：list-windows、inspect、search、get-property、get-value、wait-for；invoke、click、set-value、focus、scroll-into-view；send-keys、hover、drag、touch、pen；screenshot、record。每个动词的具体选择器和选项应通过其 --help 查看，而不是凭简短参考猜测。
测试脚本支持断言：使用 wait-for --value 验证 TextBox/NumberBox 值、RichEditBox 文本、ComboBox 选择、开关/复选框的 On/Off 以及 TextBlock/标签文本；--contains 匹配子串；--gone 等待元素消失；-p IsEnabled --value True 仅用于特定属性。
脚本会生成结构化结果（test-results.json）和截图证据，并支持在 Windows Sandbox 中运行以将合成输入与用户桌面隔离。
使用方式
-
选择目标：优先使用 Windows Sandbox（若可用）；否则告知用户并选择本地。如果用户明确要求 Windows Sandbox 但不可用，应停止并指向 winui-setup 中的启用步骤。停止的来宾不能证明不可用，
target snapshot可能报告没有运行目标而功能实际已启用。 -
编写宿主机侧批量脚本：创建
ui-tests.ps1，替换示例 AutomationId/期望值为应用的实际需求。脚本使用winapp run . --on sandbox --detach --json启动来宾应用，或省略--on sandbox进行本地执行。运行 JSON 包含 ProcessId、ProcessScope 和 UiTargetArgs（PascalCase）。在 Windows Sandbox 中，UiTargetArgs 为--on sandbox -a <guestPID>，两部分都要保留。 -
运行、读取并视觉验证：运行脚本后读取 test-results.json，并用图像查看工具查看每个宿主机 PNG。UIA 通过无法检测裁剪、重叠、错误主题或内容溢出容器。对于意外的滚动条、省略号、被裁剪的控件、重叠行、不平衡的空白、错误的光/暗/高对比度主题或缺失的焦点/悬停/错误状态，应判定视觉审查失败。
适用场景
- 为 Windows 桌面应用（任意框架，打包或未打包）编写自动化 UI 测试。
- 验证按钮、导航项、文本框、下拉框、开关、复选框等控件的交互和状态。
- 测试文件选择器、浮出控件、ContentDialog、上下文菜单、键盘快捷键、悬停、拖拽、触摸和笔输入。
- 在 Windows Sandbox 中隔离运行合成输入测试。
- 进行可访问性审计，检查应用控件是否具有 AutomationId。
限制
- 真实输入和捕获需要解锁的宿主机以及已连接、未最小化的 Sandbox 客户端。树检查可能可用而输入不可用；可读的树不是输入就绪检查。
- 持久来宾是共享的，不是相互不信任工作流之间的隔离。没有支持的
--unique-identity选项。相互不信任的工作应使用独立机器。 - 来宾
--debug-output仅支持打包应用。 - 项目构建/发布在宿主机执行；部署、应用启动和
ui --on sandbox在来宾执行。批量脚本应在宿主机运行，而不是在 target exec 内（会双重路由）。 - 不要在没有任务许可的情况下启用 Windows 功能或启动应用。
- 系统快捷键需要 CLI 的显式权限标志；不要将其用作桌面就绪错误的变通方法。
- 修复并重跑最多两轮；之后报告剩余失败。没有结构化结果和视觉审查，不得宣布完成。
- 前置条件和启用方式参见 winui-setup。