locator-replacer

替换占位定位符为真实选择器(六级优先级)。触发:替换定位符、locator、selector、定位失败、元素找不到、DOM 分析。

SKILL.md

GitHub

Locator Replacer — 定位符替换 Skill

适用场景

  • 将页面对象中 text= 占位定位符替换为真实选择器
  • 前端构建后原有选择器失效,需要重新定位
  • 新增页面元素需要选择最佳定位策略

定位符选择策略(六级优先级)

按优先级从高到低,逐级尝试,选中即停。优先使用页面上已有的语义化信息, 避免依赖需要前端额外配合的属性。

级别 策略 抗什么 代价
P0 ARIA role + 可见文本 CSS 重构、构建哈希 文案变更需同步
P1 可见文本 CSS 重构、构建哈希 文案变更需同步、可能不唯一
P2 表单特有属性(name/placeholder/type) 样式与文案变更 仅适用于表单控件
P3 语义化 CSS class / id 文案变更 样式重构即失效
P4 data-testid 几乎全部 需前端配合添加
P5 相对 XPath / CSS 结构 —— 最脆弱,最后手段

完整写法、判断依据与代码示例 → references/priority-levels.md

执行流程

Step 1: 分析目标页面 DOM

使用 agent-browser 打开目标页面,获取交互元素信息(工具选型遵循 agent-behavior P0.4,agent-browser 未安装时降级到 Playwright MCP):

操作步骤:
1. browser_navigate → 访问目标页面(已认证状态)
2. browser_snapshot → 获取页面无障碍树(accessibility tree)
3. browser_evaluate → 执行 JS 提取元素属性:
   - document.querySelectorAll('[data-testid]')  → 已有 testid
   - document.querySelectorAll('[role]')          → ARIA role
   - document.querySelectorAll('button, a, input') → 交互元素

Step 2: 为每个元素选择定位策略

对照页面对象中的每个占位定位符,按 P0→P5 逐级尝试,命中即停:

检查顺序 条件 使用
P0 有 role + name role=button[name='...']
P1 text= 唯一且稳定 text=...(标记"已验证唯一")
P2 表单属性(placeholder/name/type) [placeholder='...']
P3 稳定 CSS class(非哈希) css=.xxx
P4 有 data-testid [data-testid='...']
P5 以上均无 相对 XPath(≤3 层)

Step 3: 更新页面对象

class <PageName>(BasePage):
    # 定位符 — 已替换为真实选择器(<日期>)
    <PRIMARY_ACTION_BTN> = "role=button[name='<按钮文案>']"  # P0: ARIA role
    <SECONDARY_LINK> = "text=<链接文案>"                      # P1: text(已验证唯一)
    PAGE_IDENTIFIER = "role=heading[name='<页面标题>']"       # P0: ARIA role

更新规则:

  • 在定位符行尾注释标注选择级别(# P0: ARIA role / # P1: text / ... / # P4: testid / # P5: XPath)
  • 如果 text= 经验证确实稳定且唯一,注释标记 # P1: text(已验证唯一)
  • 删除原来的 # 定位符 — 后续替换为实际选择器 注释
  • 更新为 # 定位符 — 已替换为真实选择器(日期)

Step 4: 验证

# 在对应角色的回归文件中跑指定用例(运行前向用户确认 --env,见 agent-behavior P0.2)
pytest framework/tests/<role>/test_<role>_flow.py --env=<pre|prod> -v -k "test_<story_name>"

Step 5: 同步更新文档

更新 docs/regression-points.md 中对应 PageObject 的"关键定位符"段。


定位符质量检查清单

替换完成后,逐项确认:

  • 没有使用绝对 XPath(/html/body/...)
  • 没有使用哈希类名(sc-xxx, css-xxx, _module_xxx)
  • 没有使用纯数字索引(div[3],除非列表取第 N 项)
  • 每个定位符行尾标注了选择级别(# P0 ~ # P5)
  • XPath 层级不超过 3 层
  • 主流程测试在真实环境通过

常见问题处理

同一文本重复、元素无稳定属性、构建后批量失效等症状的处理方式 → references/troubleshooting.md