page-agent Action 回归测试指南：基于真实页面与组件 Demo 验证 DOM 动作函数

page-agent Action 回归测试指南基于真实页面与组件 Demo 验证 DOM 动作函数【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent本文是 page-agent 仓库中 docs/agentic-testing/actions.md 的完整展开版面向希望在真实网页搜索引擎、组件库 Demo、富文本编辑器上系统性回归验证page-agent/page-controller动作函数点击、输入、选择、滚动的开发者。读完本文你将掌握如何构建并加载page-controller的独立 bundle、如何绕过PageController直接调用底层 action 函数以及如何围绕 11 个真实用例Bing、AntD、Element Plus、Quill、MUI、Radix验证输入、选择、菜单、树、日期、滚动、富文本等场景的交互正确性并规范地报告执行结果。测试背景为什么需要 Action 回归测试page-agent 是一个用自然语言控制网页界面的 JavaScript 页内代理。其核心交互能力由page-agent/page-controller包提供该包Designed to be independent of LLM and can be tested in unit tests见 PageController.ts即 DOM 操作与元素交互被刻意设计为与 LLM 无关因而可以被独立、自动化地测试。然而单元测试如 PageController.test.ts只能验证构造、状态查询、executeJavascript等纯逻辑行为无法验证一个关键事实真实的 React、Vue、富文本编辑器等第三方组件是否响应我们合成的 PointerEvent / InputEvent / change 事件。这正是 docs/agentic-testing/README.md 所定义的Agentic interaction testing——面向具备computer use电脑使用与 vision视觉能力的测试执行器如 Codex的浏览器交互测试清单用 computer use 完成环境搭建与操作执行用 vision 验证操作后的真实 UI 状态。actions.md就是这套方法论中的第一份清单在真实页面与组件 Demo上逐条执行动作函数验证动作 → UI 反馈的一致性防止 DOM 事件合成逻辑在第三方框架面前回归失效。环境搭建Setup构建、加载、直接调用按照 actions.md 的 Setup 部分回归测试环境只需三步第一步构建 page-controller 独立产物npm run build -w page-agent/page-controller构建配置见 vite.config.js入口为src/PageController.ts产物名为page-controller格式为 ESMformats: [es]输出到packages/page-controller/dist/lib/且minify: false、sourcemap: true。因此构建后得到的正是清单要求的packages/page-controller/dist/lib/page-controller.js未压缩、带 sourcemap便于在测试失败时直接对照源码定位问题。第二步在测试页面中加载该 bundle通过动态import()加载可以使用 URL 形式或 Blob 形式// URL 形式本地静态服务 await import(/path/to/dist/lib/page-controller.js) // Blob 形式可注入任意页面 const blob new Blob([await (await fetch(/path/to/dist/lib/page-controller.js)).text()], { type: text/javascript, }) await import(URL.createObjectURL(blob))第三步直接调用导出的动作函数这是本清单最关键的约束有三条铁律直接在 DOM 元素上调用导出的 action 函数绝不使用原生输入native input——不调用element.value ...之后直接触发事件也不使用 CDP/Playwright 式的真实键盘输入必须走 page-controller 自己合成的事件序列否则测不到真实回归风险不实例化PageController、不修改 bundle——保持被测对象是最小可验证的纯动作函数。从 actions.ts 的导出列表可以看到被测函数的全貌导出的动作函数签名职责clickElement(element: HTMLElement) Promisevoid按 W3C 事件规范模拟一次完整点击inputTextElement(element: HTMLElement, text: string) Promisevoid向 input / textarea / contenteditable 写入文本selectOptionElement(selectElement: HTMLSelectElement, optionText: string) Promisevoid按文本匹配并选中原生select的选项scrollVertically(scroll_amount: number, element?) Promisestring垂直滚动页面或指定容器scrollHorizontally(scroll_amount: number, element?) Promisestring水平滚动页面或指定容器getElementByIndex(selectorMap, index) HTMLElement按索引从 selectorMap 取出元素内部辅助scrollIntoViewIfNeeded(element: Element) Promisevoid滚动使元素进入视口内部辅助辅助的事件分发工具utils/index.ts通过自定义事件驱动页内遮罩指针movePointerToElement派发PageAgent::MovePointerTo、clickPointer派发PageAgent::ClickPointer并通过enablePassThrough/disablePassThrough临时让遮罩穿透以便命中测试。理解这一点有助于排查点击没生效类问题——如果页面中同时存在 page-agent 的交互遮罩maskaction 的命中测试依赖这套自定义事件协作。测试用例总览11 个真实场景回归清单actions.md 的 Cases 表格是本文的核心主体完整继承如下ID页面 / Demo动作预期结果bing-suggestBing输入weather tomorrow出现搜索建议输入框保持焦点bing-submitBing输入weather tomorrow点击搜索结果页展示相同的查询词antd-selectAntD Select可搜索筛选、选择、重新打开匹配的选项被选中值被保留el-selectElement Plus Select可清空 / 禁用选择、清空、重新选择值更新禁用选项仍不可用el-menuElement Plus Menu侧边栏点击标题/图标、选择子项、折叠子菜单只切换一次子项可独立选中antd-treeAntD TreeBasic展开、选中、勾选子节点对应状态全部更新el-dateElement Plus DatePickerDate Range选择范围、重新打开、清空日期保留清空同时移除两端quillQuill 富文本编辑器替换、清空、重输、失焦、再次编辑无重复内容、无旧内容回退el-scrollElement Plus Scrollbar垂直 / 水平双向滚动目标容器滚动发生在正确的区域和方向mui-inputMUI Autocomplete受控状态输入、选择、清空显示的 inputValue / value 保持一致radix-selectRadix Select选择、重新打开、选择另一项值更新焦点回到触发器这 11 个用例覆盖了 page-agent 动作系统面临的最大真实风险面主流 React 组件库AntD、MUI、Radix、主流 Vue 组件库Element Plus、富文本编辑器Quill与原生网页Bing——它们分别对合成事件、受控组件状态、焦点管理、滚动容器有不同的敏感性。动作实现原理每个用例在测什么回归清单的价值在于知其然更知其所以然。结合 actions.ts 的实现可以把 11 个用例按被测动作归类逐个说明其验证重点。点击动作clickElement的完整 W3C 事件序列clickElementactions.ts是大多数用例的底层依赖。它严格按照 W3C Pointer Events UI Events 规范顺序合成事件pointerover → pointerenter → mouseover → mouseenter → pointerdown → mousedown → [focus] → pointerup → mouseup → click实现要点与对应风险先滚动到可视区域调用scrollIntoViewIfNeeded若元素在 iframe 内还会先滚动 iframe 自身命中测试hit-test计算元素中心坐标(rect.left width/2, rect.top height/2)随后临时开启遮罩穿透enablePassThrough、用document.elementFromPoint(x, y)找到该坐标下最深的元素再关闭穿透。源码注释明确说明匹配真实浏览器行为——事件应派发到最内层元素actions.ts焦点管理与浏览器行为一致对原始元素最近的可聚焦祖先调用element.focus({ preventScroll: true })而非命中测试目标激活行为最后通过target.click()触发导航、表单提交等激活行为事件从命中目标向上冒泡到可交互祖先。因此bing-submit用例验证的是合成点击能否触发真实搜索导航el-menu验证合成点击能否让 Element Plus 的子菜单恰好展开一次多点一次、少点一次都会导致子菜单状态错误antd-tree验证点击展开箭头、选中节点、勾选 checkbox 三种点击在 AntD 树组件上全部生效。输入动作inputTextElement的双轨策略inputTextElementactions.ts支持三类元素input、textarea、contenteditable。普通输入框走原生 value settergetNativeValueSetter(element).call(element, text) element.dispatchEvent(new Event(input, { bubbles: true }))关键在getNativeValueSetterutils/index.ts——它从元素自身原型上取回value的 setter而非直接用element.value text这正是 React 受控组件能感知到输入的原因。bing-suggest用例即验证这一路径输入后 Bing 出现搜索建议、且输入框保持焦点焦点保持说明没有因合成事件把焦点搞丢。contenteditable 走 Plan A → Plan B 双轨源码注释已详细说明见 actions.tsPlan A合成事件先派发beforeinputinputType: deleteContent清空 /insertText写入写入innerText再派发input。适用于 React contenteditable 和 Quill验证检查innerText是否与目标文本一致若 Plan A 实际未生效则自动降级Plan BexecCommandfocus→ 选中全部内容 →execCommand(delete)→execCommand(insertText, text)接入浏览器原生撤销栈适用于 Slate.js 等忽略合成事件的编辑器收尾派发change事件并blur()触发校验逻辑。quill用例的替换、清空、重输、失焦、再次编辑无重复、无旧内容回退正是对 Plan A/B 双轨与内容幂等性的全面压力测试——Quill 对innerText写入和事件序列非常敏感曾经是重点修复对象见后文 References 中的 PR #179。mui-input用例则验证受控组件场景下inputTextElement与点击选择后inputValue/value保持一致。选择动作selectOptionElement与组件下拉的本质区别selectOptionElementactions.ts针对原生select按option.textContent.trim() optionText.trim()匹配选项设置value后派发change事件。但清单中的antd-select、el-select、radix-select都是非原生自定义下拉其本质是点击触发器clickElement→ 打开浮层 → 点击目标选项clickElement→ 重新打开验证值保持。这三个用例分别验证antd-select可搜索筛选输入框的合成输入、选项点击、重新打开后选中值保留el-select可清空/禁用选择、点击清空图标、重新选择且禁用项不能被选中——禁用状态若被合成点击绕过即回归radix-select选择后值更新、焦点回到触发器——Radix 对焦点管理有严格要求失焦行为错误会让浮层立即关闭。滚动动作scrollVertically/scrollHorizontally的容器定位el-scroll用例直接针对 scrollVertically 与 scrollHorizontally。两者的策略一致指定元素时从目标元素沿祖先链向上最多查找 10 层通过overflowY/overflowX的auto|scroll|overlay与scrollHeight clientHeight判定可滚动容器将滚动量除以 3 执行并校验实际滚动位移0.5px 才算成功随后返回结构化结果字符串如Scrolled container (DIV) by 150px未指定元素时先尝试从document.activeElement向上找足够大高度 ≥ 视口一半的可滚动容器失败则降级为全局*搜索或页面级滚动并对已到顶部/底部/左右边缘返回带 ⚠️ 的提示。用例要求垂直 / 水平双向滚动目标容器且滚动发生在正确的区域和方向正是为了验证容器查找逻辑不会把滚动错误地施加到页面级滚动条或错误的父容器上。执行方法与结果报告README.md 对执行流程给出了明确的规范与actions.md配套使用执行Execution使用 computer use 完成环境搭建打开页面、加载 bundle所有交互都必须通过清单规定的代码路径即上面导出的动作函数执行用 vision 验证操作后的 UI 状态——因为合成事件是否被框架接受最终只能由真实渲染结果裁决结果Results每个用例报告必须包含revision版本 本地改动、browser浏览器、case ID、target目标元素、status状态与 evidence证据其中状态枚举为PASS/FAIL/BLOCKED/NOT RUN四档对比回归语义将失败结果与上一 revision对比——这正是回归清单的核心判断某个 action 的失败是新引入的回归还是历史已知问题。回归历史这些用例从哪来清单末尾的 References 记录了这些用例对应的真实修复历史原文档以链接形式给出此处以编号引用可对照仓库提交历史核验el-menuPR #378 —— 子菜单展开状态相关修复对应子菜单只切换一次的预期el-dateIssue #336 —— Date Range 日期选择问题对应日期保留、清空同时移除两端的预期quillPR #179 —— 富文本输入去重与旧内容回退问题对应无重复、无旧内容的预期el-scrollPR #390 —— 滚动容器定位相关修复对应正确区域和方向的预期。这些引用说明清单并非凭空设计而是对历史上真实出现过的合成事件兼容性缺陷的固化回归用例——每一条预期结果背后都对应过一次实际的 bug 修复。扩展阅读深入关联源码如果你希望为清单新增用例或想进一步理解动作函数与上层PageController的关系建议顺藤摸瓜阅读以下仓库路径docs/agentic-testing/README.mdAgentic testing 方法论总纲定义执行与结果规范packages/page-controller/src/actions.ts全部被测动作函数的实现本体含 W3C 事件序列、contenteditable 双轨策略、滚动容器查找的详细注释packages/page-controller/src/PageController.ts动作函数的上层封装按索引点击/输入/选择/滚动、executeJavascript、mask 生命周期清单刻意跳过它以保证测试最小化packages/page-controller/src/utils/index.ts类型守卫、原生 value setter、遮罩指针事件等基础工具packages/page-controller/src/PageController.test.ts纯逻辑单元测试与清单的真实页面回归互补packages/page-controller/vite.config.js产物构建配置理解dist/lib/page-controller.js从何而来。需要注意的是本清单的结论与命令均以当前仓库为准构建产物路径依赖 vite.config.js 的outDir: dist/lib与fileName: page-controller配置执行环境需要浏览器页面内注入 bundle 而非 Node视觉验证依赖执行器具备 vision 能力。若仓库后续调整构建配置或动作实现应以更新后的actions.ts与构建产物为准。【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考