cua-driver-fixtures 权威 HTML 测试夹具指南：为 CUA Driver 手势验证构建单一事实源

cua-driver-fixtures 权威 HTML 测试夹具指南为 CUA Driver 手势验证构建单一事实源【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua本篇指南围绕当前仓库cua中的libs/cua-driver-fixtures目录展开深入讲解这套被 cua-driver 测试框架引用的单一事实源single source of truthHTML 测试页面四个夹具分别覆盖什么交互面、每个页面暴露了哪些稳定的元素 ID 与全局访问器、驱动程序如何通过相对符号链接复用它们以及gesture_panels.html针对 Windows 压力测试暴露的四类手势盲区所设计的验证面板。读完本文你将掌握如何直接打开、驱动并断言这套夹具理解 PostMessage 热键注入与 SendInput 在修饰键状态传播上的差异以及 Chromium 目标浏览器在 Windows 上做 DOM 级验证时的三个环境前置条件并能为新交互面正确地扩展这套夹具体系。一、为什么需要一套规范化的 HTML 测试夹具cua-driver是仓库中负责跨平台桌面自动化输入鼠标、键盘、滚轮、热键等的驱动程序其集成测试需要与真实浏览器页面交互验证点击、输入、拖拽、滚动等手势是否真正到达页面层。如果每个测试各写各的 HTML 页面必然出现两类问题漂移drift同一交互在不同测试页里行为不一致断言口径无法统一重复测试树里复制多份几乎相同的页面改动一处需要同步多处。libs/cua-driver-fixtures/README.md给出的解决方案是把所有页面收敛到单一目录作为canonical权威副本驱动测试通过相对符号链接引用它们从而构造上杜绝漂移——对夹具的任何修改一次提交即可传播到所有驱动测试。该目录由 4 个纯 vanilla HTML 文件组成无外部依赖、无构建步骤文件用途interactive.html31 行的极简点击 输入镜像测试台。稳定 ID#counter、#clicker、#textbox、#typed。通过file://打开供后台聚焦类测试使用form_all_inputs.html覆盖全部 HTML5 输入类型的表单text、password、email、number、tel、textarea、select、checkbox、radio、range、date、color。提交处理器把结果写入window._submitted并提供getFieldValues()实时读取供拖拽滑块、表单填充类测试使用test_page.html更丰富的 Safari/Chrome/Electron 测试台——按钮计数器、文本输入、复选框、下拉框、文本域、链接、Canvas。通过本地html_serverHTTP 夹具服务供 Chrome/Safari/Electron 测试使用gesture_panels.html新增页面沿用test_page.html的 ID 约定为 v2 测试台未覆盖的四类手势热键修饰键状态、像素级坐标定位、拖拽事件序列、滚动位置提供独立面板二、四个夹具逐一拆解稳定 ID、断言入口与真实代码2.1interactive.html31 行的最小点击/输入验证台这个页面只有按钮点击计数和一个输入即镜像的文本框逻辑全部内联在script中div idcounterclicks: 0/div button idclicker onclickbump()Click Me/button input idtextbox typetext placeholderType here... oninputmirror() div idtypedtyped: /div script var n 0; function bump() { n; document.getElementById(counter).textContent clicks: n; } function mirror() { document.getElementById(typed).textContent typed: document.getElementById(textbox).value; } /script完整内容见 interactive.html它的设计要点是断言极简点击#clicker后断言#counter文本变成clicks: N向#textbox键入后断言#typed前缀为typed:。由于通过file://直接打开即可运行非常适合验证输入事件是否到达页面这一类后台聚焦场景README 中注明其被test_background_focus.py使用。2.2form_all_inputs.html全覆盖 HTML5 表单的提交与实时读取这是表单类测试的主力页面form idtest-form内包含 11 类输入控件每个控件都有稳定的id与name文本类#f-texttext、#f-passwordpassword、#f-emailemail、#f-numbernumbermin0 max999、#f-teltel富控件#f-textareatextarea、#f-selectselect红/绿/蓝/黄四选项、#f-checkboxcheckbox、radio_field单选组apple/banana/cherry、#f-rangerange 滑块 0–100默认 50、#f-datedate、#f-colorcolor默认#4488ff页面提供两条互相独立的断言通道提交通道onsubmithandleSubmit(event)点击#submit-btn后把所有字段序列化为 JSON 写入window._submitted同时把格式化结果渲染进#result实时通道getFieldValues()函数无需提交即可返回全部字段当前值并附带submitted: true/false标记function getFieldValues() { return JSON.stringify({ text: document.getElementById(f-text).value, // ... 每个字段一行 range: document.getElementById(f-range).value, date: document.getElementById(f-date).value, color: document.getElementById(f-color).value, submitted: typeof window._submitted ! undefined, }); }完整实现见 form_all_inputs.html这种提交态 实时态双通道设计让测试可以分两步验证先逐字段填充并轮询getFieldValues()确认各控件状态再触发提交断言window._submitted的完整数据快照。README 标注它被test_drag_slider_delivery.py、test_hermes_form_fill*.py等使用。2.3test_page.htmlSafari/Chrome/Electron 的通用交互面这个页面把常用交互控件组织成 7 个 section每个都有对应的状态回显便于测试断言Section稳定 ID断言方式Button#clicker/#btn-counter点击后计数文本递增Text Input#textbox/#text-mirror键入内容实时镜像Checkbox#checkbox/#checkbox-label文本在 checked/unchecked 间切换Select#dropdown/#select-label显示当前选中项文本Textarea#textarea/#textarea-mirror多行内容实时镜像Link#testlink/#link-status点击后状态变为 clickedCanvas#mycanvas/#canvas-status点击绘制红点状态显示落点坐标(x,y)其中 Canvas section 是坐标类断言的好例子mousedown事件通过getBoundingClientRect()换算页面内坐标绘制红点并把坐标写入状态文本与canvas.datasetcanvas.addEventListener(mousedown, function(e) { var rect canvas.getBoundingClientRect(); var x Math.round(e.clientX - rect.left); var y Math.round(e.clientY - rect.top); // ... 绘制红点更新 #canvas-status });完整实现见 test_page.html与interactive.html不同README 明确该页面通过本地html_serverHTTP 夹具提供供test_chrome.py、test_safari.py、test_electron.py使用——这也解释了为什么驱动侧相关工具对test_page.html的定位既支持file://路径也支持 HTTP 地址可参见 platform-windows 工具实现 中对file:///C:/test_page.html的处理。三、符号链接复用机制如何做到单次提交、全树生效README 用一个目录树示例说明了 canonical 副本与驱动测试之间的绑定方式驱动测试路径保持为相对符号链接指向本目录。libs/cua-driver/rust/tests/integration/ ├── fixtures/ │ └── interactive.html → ../../../../cua-driver-fixtures/interactive.html └── v2/assets/ └── test_page.html → ../../../../../cua-driver-fixtures/test_page.html这样做的直接收益是现有测试代码如os.path.join(_THIS_DIR, fixtures, interactive.html)、f{html_server}/test_page.html这类路径拼接无需改动即可继续工作对夹具的任何编辑一次提交即可传播到所有驱动测试由于驱动测试树里只有链接没有副本漂移在构造上不可能发生。仓库规则随之明确不要在 driver 树下复制夹具一律使用符号链接。四、gesture_panels.html为 Windows 压力测试暴露的四个手势盲区设计test_page.html对 Safari/Chrome/Electron 的常规交互覆盖良好但 2026 年 5 月 Windows cua-driver 压力测试暴露出它没有探测的四类手势。gesture_panels.html正是为此新增的补充页面完整实现见 gesture_panels.html。4.1 热键 修饰键状态传播#hotkey-focus#hotkey-status核心问题PostMessage 热键路径与 SendInput 热键路径在修饰键状态上行为不同。基于 PostMessage 的热键路径只注入击键事件不更新操作系统级修饰键状态因此即使成功路由了ctrls页面收到的KeyboardEvent.ctrlKey仍然为falseSendInput 会同步更新GetKeyState同一事件读到的ctrlKey为true。页面面板把key/code/ctrl/alt/shift/meta六个字段直接打印到状态行一次断言即可区分两条路由路径input typetext idhotkey-focus placeholderFocus here, then send a hotkey... div idhotkey-status classstatushotkey: (no key seen)/div测试流程为聚焦该输入框 → 发送hotkey [ctrl,s]→ 状态行应报告ctrltrue keys若只报告ctrlfalse说明走的是不更新修饰键状态的 PostMessage 路径。4.2 像素级坐标定位#coord-area#coord-status已知目标位于盒子内视口坐标(60, 60)由#coord-target的left: 60px; top: 60px定义。点击后页面计算落点与目标中心的欧氏距离并显示var dx x - 60, dy y - 60; var dist Math.sqrt(dx*dx dy*dy).toFixed(1); document.getElementById(coord-status).textContent coord: ( x , y ) dist dist px;断言dist 2像素即是一次干净的坐标路由点击精度测试——只有驱动把屏幕坐标换算并路由到页面正确位置才能通过。4.3 拖拽事件序列#drag-source#drag-target#drag-status页面按顺序记录每个 HTML5 拖拽事件而不是只验证光标移动过。测试必须看到完整链条dragstart → dragover → drop到达页面才算驱动成功完成了拖拽手势tgt.addEventListener(drop, function(e) { e.preventDefault(); dragEvents.push(drop); // ... 状态行打印完整事件链 dataTransfer payload window._lastDrag { events: dragEvents.slice(), payload: payload }; });状态行会同时显示事件链和dataTransfer携带的payloadDRAG ME因此还能验证数据负载是否正确传递。4.4 滚动位置#scroll-area#scroll-status一个overflow-y: scroll的容器内部内容高 1200pxscroll事件实时把scrollTop打印到状态行document.getElementById(scroll-area).addEventListener(scroll, function(e) { var st e.currentTarget.scrollTop; document.getElementById(scroll-status).textContent scroll: st; });测试可以断言路由滚动手势后scrollTop的方向与数值是否符合预期。4.5 统一的程序化访问入口window.getGesturePanelState()与test_page.html每个 section 只暴露 DOM 状态不同gesture_panels.html在页面底部聚合了一个全局访问器返回四个面板状态的 JSON 快照window.getGesturePanelState function() { return JSON.stringify({ hotkey: window._lastHotkey || null, coord: window._lastCoord || null, drag: window._lastDrag || null, scroll: typeof window._lastScroll number ? window._lastScroll : null, }); };对应地四个面板各自维护window._lastHotkey、window._lastCoord、window._lastDrag、window._lastScroll内部状态。测试有两种读取方式JS 通道通过page工具、action: execute_javascript轮询getGesturePanelState()需要 Chromium 以--remote-debugging-port启动可访问性/视觉通道直接读取可见状态 div 的文本经由 UIA 或 OCR。五、Windows 上 Chromium 目标浏览器的三个环境前置条件README 特别提醒在 Windows 上驱动 Chromium 系浏览器Edge / Chrome / Electron做 DOM 级验证时集成测试需要了解以下环境限制。这些属于驱动目标的环境要求不影响 canonical 夹具本身只影响如何驱动它们GPU 合成内容会使 PrintWindow 截图为空白。cua-driver screenshot只能捕获浏览器 chrome 加白色 body。变通方案用--remote-debugging-portport启动目标浏览器改用page工具action: execute_javascript同时完成输入与验证。Chromium 默认关闭完整可访问性a11y树除非检测到 AT 级客户端。UIA 直接读取渲染后的 DOM 会得到空结果直到页面被标记为 accessibility-active。变通方案启用 Chromium 的--force-renderer-accessibility标志或改用--remote-debugging-port通道。hotkey的 SendInput 注入要求守护进程运行在 UIAccess 完整性级别。否则SetForegroundWindow会被拒绝注入事件落到错误窗口——典型报错为SendInput inserted only 0 of 4 events。变通方案通过携带 manifest 的cua-driver-uia.exeworker 运行cua-driver。六、如何扩展这套夹具体系README 给出新增夹具的四步流程核心原则是只加链接、绝不复制把新 HTML 文件直接放进libs/cua-driver-fixtures/目录在上文的文件表格中登记用途 稳定 ID 使用方在需要的驱动测试路径下添加相对符号链接在同一个 PR里提交新文件 符号链接。禁止在 driver 树里创建副本。这一约定让夹具、测试与驱动代码保持同一提交节奏从流程上保证改夹具必改引用、改引用必同提交。七、小结libs/cua-driver-fixtures以四个零依赖的 vanilla HTML 文件为 cua-driver 的集成测试提供了统一、可链接、可扩展的验证面interactive.html承担极简点击/键入验证form_all_inputs.html覆盖完整 HTML5 表单test_page.html覆盖多浏览器常规交互gesture_panels.html针对热键修饰键状态、像素级坐标、拖拽事件链与滚动位置四类手势盲区提供专门面板。通过单一事实源 相对符号链接的工程约束配合window.*全局状态与getGesturePanelState()聚合访问器测试可以稳定地断言手势是否真正到达页面层——这正是跨平台桌面自动化驱动测试中最关键、也最容易忽视的一环。若需深入驱动侧实现可继续阅读 cua-driver 集成测试文档 与 platform-windows 工具层。【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考