Playwright 六种定位策略怎么选：稳定性来自哪里、什么时候会碎

2026-08-18

用例昨天还好好的，今天挂在「找不到元素」或者「匹配到了两个」上——这种时候争论「哪种定位器更好」没有意义。真正该问的是：我这条定位器的稳定性押在什么东西不变上？那个东西今天被谁改了？

Playwright 仓库把六种定位方式分别写在两份文档里：推荐的内置定位器在 docs/src/locators.md，CSS 与 XPath 这类在 docs/src/other-locators.md 里单列一份「其它定位器」。这个分文件本身就是一层信息。下面按「稳定性来源」和「失效场景」把六种放在一起看，只比双方都白纸黑字写明的东西。

先把六种的「押注对象」摊开

定位方式	稳定性押在什么不变上	仓库文档给的定位
`getByRole`	元素的 ARIA 角色 + 可访问名称	推荐优先使用
`getByLabel`	表单控件关联的 label 文本	定位表单字段时使用
`getByText`	元素包含的文本	建议用于 `div`、`span`、`p` 等非交互元素
`getByTestId`	你自己在 HTML 里写死的测试属性	显式测试契约，但不面向用户
CSS	DOM 结构与实现细节	写在「其它定位器」，带不推荐提示
XPath	DOM 结构与路径	同上，带不推荐提示

docs/src/locators.md 的 Quick Guide 一节把前几种列为 recommended built-in locators，并写明为了让测试更稳，推荐优先用 getByRole 这类面向用户的属性与显式契约；同一份文档在角色一节补了理由——它最接近用户与辅助技术感知页面的方式。而在 test id 一节写的是另一句话：按 test id 测试是 the most resilient way（原文用词），因为文本或角色变了测试仍然通过——但紧跟一句 not user facing。

这两句话摆在一起，其实已经把选型的张力说清楚了：角色和文本的稳定性来自「用户看到的东西没变」，test id 的稳定性来自「你和开发约定的属性没被删」。前者会因为改文案而断，后者不会；但也正因为后者不面向用户，它不会替你发现文案和角色的回归。文档自己在 test id 一节写了：如果角色或文本对你重要，就考虑用面向用户的定位器。

决策路径：从元素本身倒推

不用记优先级表，按元素性质走一遍就行。

第一问：这是个表单控件，且有配套 label 吗？ 是就用 getByLabel。docs/src/locators.md 的 label 一节直接写明 use this locator when locating form fields。

第二问：这是个交互元素（按钮、链接、输入框）吗？ 是就用 getByRole 并带上可访问名称。文档在角色一节写明，按角色定位时通常还要把 accessible name 一起传进去，让定位器精确指到那一个元素：

await page.getByRole('button', { name: 'Sign in' }).click();

page.get_by_role("button", name="Sign in").click()

第三问：这是纯展示的文本节点吗？ 是就用 getByText。文档在 text 一节写明推荐用它找 div、span、p 这类非交互元素，交互元素回到角色定位。

第四问：角色和文本都定位不到，或者你所在团队采用 test id 方法论？ 用 getByTestId。

第五问：以上都不行？ 文档的原话是 if you absolutely must use CSS or XPath locators，才用 page.locator() 传选择器。这个 absolutely must 是文档自己的措辞，不是我加的修饰。

六种各自会在什么改动下碎

角色：碎在可访问名称上

docs/src/api/params.md 里 locator-get-by-role-option-name 写明，name 匹配的是 accessible name，默认大小写不敏感、按子串匹配，exact 选项控制这个行为。也就是说，按钮文案从「登录」改成「立即登录」，子串匹配可能还活着；改成「进入」就断了。

有两条容易踩的语义写在同一份文件里：

includeHidden 默认只匹配非隐藏元素（按 ARIA 的 tree exclusion 定义）。元素还在 DOM 里但被 ARIA 视为隐藏，角色定位就查不到它。
disabled 这个选项，文档特意标注：与大多数属性不同，disabled 会沿 DOM 层级继承。父容器禁用会影响子元素的判定。

另外文档在角色一节明确写了一句边界：role locators do not replace 可访问性审计与合规测试，它只是给出 ARIA 指引方面的早期反馈。别把它当无障碍测试用。

文本：碎在空白与大小写的规则上

docs/src/locators.md 在 text 一节写明：文本匹配总是会归一化空白——多个空格变一个、换行变空格、忽略首尾空白，即使开了精确匹配也一样归一化。而 exact 的语义在 params.md 里写得很死：case-sensitive and whole-string，用正则时该选项被忽略，且精确匹配仍然会 trim 空白。

所以「精确匹配」并不等于「按原样比对」。你以为对不上是空格问题，实际多半是大小写问题。

标签：碎在「动作走控件、断言走 label」这个不对称上

这条是本篇里最容易咬人的一处，写在 docs/src/other-locators.md 的 label to form control retargeting 一节。文档列出：定位到 label 之后，click 会点 label 并自动聚焦到输入框，fill 会填输入框，inputValue、selectText、setInputFiles、selectOption 也都作用在控件上。

但下一段话锋一转：其它方法作用在 label 自身，例如 toHaveText 断言的是 label 的文本，不是输入框的值。

同一个定位器，动作被转发到控件，断言却停在 label 上。 排查「填进去了但断言拿到的是标题文字」这类现象时，先看是不是撞上了这一条。文档同时给了建议：优先用 getByLabel 按 label 文本定位，而不是依赖这套 retargeting。

测试 id：碎在「属性名配置」和「有人删了它」

默认属性是 data-testid，这是仓库当前文档里的默认值，随版本可能变动。改成别的属性名有两条路，而且不同语言绑定走的不是同一条——这一点在 docs/src/locators.md 的同一节里对照着摆出来了。JS 侧走配置文件：

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  }
});

Python 侧走 Selectors 上的方法：

playwright.selectors.set_test_id_attribute("data-pw")

docs/src/api/class-selectors.md 里 Selectors.setTestIdAttribute 的参数说明还补了一句：要同时匹配多个属性，就传逗号分隔的列表，例如 "data-pw,data-ti"。docs/src/test-api/class-testoptions.md 里 TestOptions.testIdAttribute 的说明与之一致。

这里的失效场景不在页面上，在流程上：test id 的稳定性完全建立在「开发不会顺手删掉这个属性」之上。它不面向用户，所以没人会因为界面看起来正常而注意到它被清掉了。

CSS：碎在 DOM 结构，还有一块已经标了 deprecated

Playwright 对标准 CSS 做了两处扩展，写在 docs/src/other-locators.md：CSS 选择器会穿透 open shadow DOM；另外加了 :visible、:has-text()、:text()、:text-is()、:text-matches()、:has()、:is()、:nth-match() 这些自定义伪类。

:has-text() 有个坑文档专门提示了：必须和其它选择器一起用，否则会匹配到所有包含该文本的元素，包括 <body>。

真正需要标出来的是布局伪类那一块。:right-of()、:left-of()、:above()、:below()、:near() 这组，文档上方挂着一个 warning：Layout selectors are deprecated and may be removed in the future，并写明基于布局的匹配可能产生意外结果——布局变化一个像素就可能匹配到另一个元素。要写新用例，别再往这条路上走。

至于长链 CSS，文档直接标成 bad practice，并给了一段形如 #tsf > div:nth-child(2) > div.A8SBwf > ... 的反面示例。这类定位器的稳定性押在「没人重构过这段 DOM」上，而这个前提在前端项目里基本不成立。

XPath：碎在结构，另外还有一条硬边界

docs/src/other-locators.md 写明 XPath 定位等价于调用 Document.evaluate，并提示：任何以 // 或 .. 开头的选择器字符串会被当作 xpath 处理，'//html/body' 会被自动转换成 'xpath=//html/body'。

硬边界在 Shadow DOM 上。docs/src/locators.md 写明所有定位器默认都能作用于 Shadow DOM 里的元素，例外只有两条：按 XPath 定位不穿透 shadow root；closed 模式的 shadow root 不被支持。也就是说，页面上一旦出现 web component，XPath 这条路直接断在边界上，而角色、文本这些照常工作。

取父元素也有同类提示：文档建议用 Locator.filter 按子元素反查父元素，实在找不到才用 xpath=..，并注明这个办法不那么可靠，DOM 结构一变就会断。

一条横切所有六种的线：严格模式

选哪种策略都绕不开 strictness。docs/src/locators.md 写明：定位器是严格的，所有隐含单个目标元素的操作，在匹配到多于一个元素时会抛异常；而像 count() 这类多元素操作则正常工作。

于是「匹配到两个」这件事有两种处理方式，文档的态度很清楚：first()、last()、nth() 是显式退出严格检查的口子，文档标为 not recommended，理由是页面一变可能点到你没打算点的元素。推荐做法是用 filter 把范围收窄：

page.get_by_role("listitem").filter(has_text="orange").click()

filter 支持 hasText、hasNotText、has、hasNot，还有 visible。有一条约束值得单独记：filter 里传的定位器必须是相对的，它从外层定位器匹配到的元素开始查，而不是从文档根开始——文档为此专门给了一个标 ✖ WRONG 的反例。

还有一处细节，把仓库里两句话放在一起看会发现不一致，容易写错：nth= 定位器传的是零基索引（nth=0 是第一个），而 CSS 伪类 :nth-match(:text("Buy"), 3) 的索引是一基，文档里逐字写了 index is one-based。两处都在 docs/src/other-locators.md，混着用就会差一位。

平台与语言绑定

定位策略这层不涉及操作系统差异，Windows 与 Linux/macOS 的写法一致——我们在这两份文档里没有找到任何与平台相关的定位差异说明，所以这一点不比。

语言绑定这层有一处必须交代：docs/src/locators.md 末尾的 Page-free locators 一节标了 * langs: js，也就是只有 JS 绑定有。它引入 by 对象，可以在模块作用域里定义与页面无关的定位描述，再用 page.get() 绑定到页面：

import { by } from '@playwright/test';

export const newTodo = by.placeholder('What needs to be done?');
export const todoItems = by.testId('todo-list').role('listitem');

文档写明 page.get(by.testId('list').text('Row')) 与 page.getByTestId('list').getByText('Row') 解析到同一个元素，且 test id 是在 By 绑定到页面时才解析的，所以模块作用域的 By 仍然遵守配置里的 testIdAttribute。写 Python、Java、C# 的话，这一节和你无关，别照着抄。

本文代码片段均取自上述两份仓库文档；涉及多段拼接之处，以上为按仓库代码中的接口语义组合的示例，未经实测，以仓库最新代码为准。

落点

六种定位方式没有通用排序，只有「押注对象」的不同：角色押在可访问名称、文本押在文案、label 押在表单关联、test id 押在你和开发的约定、CSS 与 XPath 押在 DOM 结构。选的时候把这句话补完整——「如果 ×× 变了，这条用例就该挂，这正是我想要的」——如果补不出来，说明选错了策略。

本文依据 github.com/microsoft/playwright 仓库于 2026-08-18 的公开内容整理，事实来自仓库内的文档与源码。我们没有对文中涉及的功能做过实测，因此不涉及运行速度、稳定性与实际表现的任何描述。该项目迭代频繁，文中涉及的 API 签名、配置项与默认值随版本变动，请以仓库最新内容为准。本文不涉及浏览器版本矩阵与版本清单，相关信息请以官方发布说明为准。

本文对照的是同一项目内的多种定位方式，依据均为上述仓库内容，不对这些用法做优劣排名，选型结论只在仓库文档写明的能力边界内成立。