Locator Replacer — 定位符替换 Skill

适用场景

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

定位符选择策略（六级优先级）

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

完整写法、判断依据与代码示例 → 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 逐级尝试，命中即停：

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