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