SuperAPI AI 工具集

selector-drift-recovery

测试与质量

查看项目

更新于 10-15 15:50

技能介绍

用途:在 UI 重构、改版、依赖升级或 CSS 迁移后,批量离线重建失效的测试选择器。它是 test-reliability 的批量离线对应物:后者在运行时按阈值修复单个选择器,本技能则针对新 DOM 批量重新生成选择器并汇总成 PR。若只是单个测试坏掉,应改用 test-reliability;若流程或语义被重写,应改用 playwright-automation;若是框架切换(Selenium 转 Playwright),应使用 test-migration。

主要能力:以 aria 快照(await page.locator('body').ariaSnapshot())对比重构前后的 DOM 角色树,忽略 class 改名、包裹 div 等表层变化;从 JSON reporter 提取失败信息(文件、行号、旧定位器、错误类型)并推断意图与页面路由;按稳定性 0-5 分生成替换候选,优先 getByRole + 可访问名称,其次 getByLabel、getByTestId,再是区域作用域消歧;仅自动应用分数 ≥3 的候选;生成带逐项证据(分数、截图)的 PR 文本。

使用方式:分六阶段,每阶段设门禁。阶段 1 快照旧 DOM(来源优先为最近绿色 CI 的 trace 工件,可用 npx playwright show-trace traces/checkout.zip 打开;或 pre-refactor 提交的 Storybook、旧版 staging 构建、组件 git 历史),输出到 .drift-recovery/old/*.aria.yml。阶段 2 快照新 DOM,需先 await page.waitForLoadState('networkidle') 等待 hydration,输出到 .drift-recovery/new/。阶段 3 用 JSON reporter 运行找出失效选择器并补全意图与路由。阶段 4 生成候选并按 0-5 评分。阶段 5 按 (file, line) 行级替换(不要做全文替换),跑全量受影响套件并逐条保留或回滚。阶段 6 提交 PR,标题形如 chore(tests): selector recovery after <refactor description>,附触发背景、汇总、逐文件变更表与被标记项。

适用场景:一次事件导致同一页面或目录出现约 10 个以上失效选择器;已有重构前后的 DOM 快照可配对;选择器原以 CSS 类或 XPath 为主需升级策略时。

限制与注意:必须同时具备新旧 DOM 快照,缺少旧 DOM 参考则退化为“重写测试”;不得自动应用 0-2 分候选,多元素匹配未消歧不得算作 3 分;分页对象(POM)包裹的定位器行号会指向 helper 而非测试,需从 trace 或源码核对;已删除功能的测试应剔除而非重建;PR 不得在 CI 中自动合并,必须人工审阅;避免使用 Playwright 布局选择器 :near()、:right-of()、:left-of()、:above()、:below()。验证步骤包括运行 node references/score-candidates.mjs .drift-recovery/candidates.json 确认无低于分数下限的已应用候选,以及 PLAYWRIGHT_TEST_BASE_URL=$PREVIEW_URL npx playwright test --reporter=json | jq '.stats.unexpected' 结果为 0。