# 浏览器 RPA 元素拾取与定位标准

> 先读 [`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md)。本文只定义浏览器端的拾取、定位、验证和常见陷阱；账号、Profile、HITL 和录屏仍以 [`RPA.md`](RPA.md) 为准。

## 目录

1. 拾取工具
2. 拾取步骤
3. 定位优先级
4. 特殊上下文
5. 验证标准
6. 禁止模式
7. example 路由

## 1. 拾取工具

优先使用 Playwright Inspector / Codegen 的 **Pick Locator**，辅以 Chrome/Edge DevTools：

- Pick Locator：点选页面元素，获取 role/label/text/testid 等候选定位器。
- DevTools Elements：确认真实 DOM、属性、父容器、iframe 和 Shadow DOM。
- Playwright trace/screenshot：复核动作发生时的页面状态。

检查器只负责给出候选。复制到生产代码前必须人工确认作用域、唯一性和稳定性。

## 2. 拾取步骤

1. 使用真实 `profile_dir` 和有头浏览器打开目标页面。
2. 手工进入发生动作的准确页面、标签页和弹窗状态。
3. 用 Pick Locator 点选元素，先记录建议 locator。
4. 在 DevTools 中确认：
   - accessible role/name
   - label、placeholder、可见文本
   - 稳定 id/name
   - `data-testid`（仅目标系统已提供或自有系统可维护时）
   - 所在 iframe、dialog、表格行或卡片
5. 先定位业务容器，再在容器内定位动作元素。
6. 运行 `count()`；关键动作期望 `1`。
7. 验证 `visible`、`enabled`、必要时 `editable/checked`。
8. 执行动作并断言 URL、业务容器、成功提示、单号或状态变化。
9. 刷新页面、关闭重开浏览器后复测。

## 3. 定位优先级

从高到低：

1. `get_by_role(role, name=...)`
2. `get_by_label(...)`
3. 自有系统的稳定 `get_by_test_id(...)`
4. `get_by_placeholder(...)`、`get_by_alt_text(...)`、`get_by_title(...)`
5. 稳定业务文本，优先用于非交互元素或父容器
6. 稳定 `id` / `name` / 短 CSS
7. 容器 + `filter(has_text=...)` / `has=...`
8. 短 XPath
9. 已验证的顺序定位

示例：

```python
dialog = page.get_by_role("dialog", name="订单确认")
submit = dialog.get_by_role("button", name="确认提交")
if await submit.count() != 1:
    raise RuntimeError("ERROR:ELEMENT_AMBIGUOUS submit_button")
await submit.wait_for(state="visible")
await submit.click()
await page.get_by_text("提交成功", exact=True).wait_for(state="visible")
```

### 列表与重复按钮

不要直接选择全页第一个“添加”：

```python
row = page.get_by_role("row").filter(has_text="客户A")
button = row.get_by_role("button", name="添加")
```

如果业务键不唯一，先停止并要求补充输入，不要用 `.first` 猜。

## 4. 特殊上下文

### iframe

先确认元素属于哪个 iframe，再使用 `frame_locator`。不得因为主页面找不到就改用坐标。

### 新标签页和弹窗

点击前注册 popup/new page 等待；取得新 Page 后再定位。关闭弹窗不等于业务成功。

### Shadow DOM

Playwright CSS locator 默认可穿透 open Shadow DOM；XPath 不穿透。closed Shadow DOM 无法正常读取时，评估目标应用是否提供可访问性属性，不能注入破解。

### 动态列表

等待列表完成加载后再读取；`locator.all()` 不会等待动态列表稳定。滚动或刷新后重新获取 locator。

### Canvas

先确认是否存在可访问性节点或外层业务控件。完全无 DOM 时才进入局部图像方案，并记录分辨率、缩放和识别区域。

## 5. 验证标准

- locator 在真实目标页面匹配数量符合元素清单。
- 不因语言、窗口宽度、列表顺序或一次刷新就指向不同业务对象。
- 动作前检查可见、可用；动作后等待真实业务状态。
- 登录态至少结合两个证据：例如稳定用户菜单 + 登录按钮不存在，不能只看单个哈希 class。
- 真实和仿真站明确区分：仿真可以使用 `fill()` 加速测试；真实生产输入遵守项目拟人节奏。

## 6. 禁止模式

- 用全页所有 `input` 的尺寸和位置猜搜索框。
- 用 `.first` 绕过严格模式。
- 从 DevTools 复制深层 `nth-child` 或绝对 XPath。
- 只等 URL 含 `search` 就判定结果成功。
- 页面结构变化后动态生成 selector 并继续提交。
- 为方便测试给第三方网站注入 testid。

## 7. example 路由

- 真实网站、登录/HITL/滚动：[`../examples/real_browser_rpa/README.md`](../examples/real_browser_rpa/README.md)
- 自有 sandbox、表单和 adapter：[`../examples/simulator_browser_rpa/README.md`](../examples/simulator_browser_rpa/README.md)

复制 example 前先完成目标站元素清单；example 中的任何 URL、selector 和业务字段都不得跨平台照抄。