Playwright locator 与自动等待
locator 是惰性解析的定位句柄：创建时不查页面，每次动作前重新解析当前 DOM，因此页面变化后不会持有过期引用。get_by_role、get_by_label、get_by_text 等语义定位把「元素是什么」写进用例，动作与断言执行前自动等待元素可交互；断言用 web-first 断言（expect(locator).to_be_visible()）反复轮询，直到通过或超时。定位方式选得对，用例的稳定性与可读性会同时上一个台阶。
基本信息
| 语义定位 | get_by_role、get_by_label、get_by_placeholder、get_by_text、get_by_test_id |
|---|---|
| 收窄手段 | filter(has_text=...)、locator('...').first / .nth(n) |
| 严格模式 | 默认开启：定位解析到多个元素时动作直接报错 |
| 断言机制 | web-first 断言自动轮询直至通过或超时 |
| 相对定位 | get_by_role('row').get_by_role('button') 在容器内继续查找 |
| 工程约定 | data-testid 作为与实现解耦的稳定锚点 |
定位与断言
定位与断言
# 语义定位：按角色与可访问名称找按钮，样式重构不影响
page.get_by_role("button", name="提交").click()
# 链式收窄：先在列表行内定位，再找行内的删除按钮
row = page.get_by_role("row", name="订单 1024")
row.get_by_role("button", name="删除").click()
# 严格模式下多个匹配会报错：用 first/nth/filter 收窄到唯一元素
page.get_by_text("详情").first.click()
# web-first 断言：自动轮询直到可见或超时
expect(page.get_by_text("已保存")).to_be_visible()典型使用场景
- 替换脆弱 CSS：用语义定位改写按 class 层级的定位写法。
- 列表与表格：按行过滤后再定位行内按钮或单元格。
- 弹层交互：对对话框、下拉框元素做可见性与内容断言。
- iframe 场景：frame_locator 进入框架内继续用同一套定位方式。
- 定位调优：用 codegen 录制观察建议定位，再手工改为语义版本。
- 稳定性治理：把频繁失效的定位逐个换成 role 或 testid 锚点。
定位方式优先级
| 方式 | 示例 | 稳定性 |
|---|---|---|
| 角色+名称 | get_by_role('button', name='提交') | 最高：贴近可访问性语义 |
| 标签与占位符 | get_by_label('邮箱') | 高：表单场景首选 |
| testid | get_by_test_id('submit') | 高：与实现解耦，需工程约定 |
| 文本 | get_by_text('已保存') | 中：文案变化即失效 |
| CSS | locator('.item .btn') | 低：与样式结构耦合 |
| XPath | locator('//div[3]/span') | 最低：结构一变全废 |
locator 在页面变化后重新解析，避免旧式 element handle 持有过期引用的坑；这也是它与 page.$ 系列的本质区别。
严格模式是保护而不是障碍：解析到多个元素时报错，逼你写出指向唯一元素的定位，防止误点第一个匹配造成假通过。
nth 下标从 0 开始且对列表顺序敏感：顺序一变用例就错位，优先用 filter 按内容定位。
文案频繁调整的产品里少用 get_by_text 做主定位：role 加 name 或 testid 更稳，文本只留给断言使用。