process-leave-attendance-default/development/RPA_BROWSER.md

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

先读 RPA_ELEMENT_LOCATING.md。本文只定义浏览器端的拾取、定位、验证和常见陷阱；账号、Profile、HITL 和录屏仍以 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. 已验证的顺序定位

示例：

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")

列表与重复按钮

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

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
• 自有 sandbox、表单和 adapter：../examples/simulator_browser_rpa/README.md

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