定位器

简介

[定位器（Locator）]是 Playwright 自动等待和重试功能的核心部分。简而言之，定位器代表了一种随时在页面上查找元素的方法。

快速指南

以下是推荐使用的内置定位器。

Page.getByRole()：通过显式和隐式的无障碍访问属性进行定位。
Page.getByText()：通过文本内容进行定位。
Page.getByLabel()：通过关联标签的文本定位表单控件。
Page.getByPlaceholder()：通过占位符定位输入框。
Page.getByAltText()：通过元素（通常是图像）的替代文本定位元素。
Page.getByTitle()：通过元素的 title 属性定位元素。
Page.getByTestId()：根据元素的 data-testid 属性（也可以配置其他属性）定位元素。

page.getByLabel("用户名").fill("John");

page.getByLabel("密码").fill("secret-password");

page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("登录"))
    .click();

assertThat(page.getByText("欢迎，John！")).isVisible();

定位元素

Playwright 提供了多种内置定位器。为了使测试更具弹性，我们建议优先使用面向用户的属性和明确的约定，例如 Page.getByRole()。

例如，考虑以下 DOM 结构。

http://localhost:3000

<button>Sign in</button>

通过其 button 角色和名称 “Sign in” 来定位该元素。

page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"))
   .click();

备注

使用代码生成器生成定位器，然后根据需要进行编辑。

每次将定位器用于某个操作时，都会在页面中定位最新的 DOM 元素。在下面的代码片段中，底层 DOM 元素将被定位两次，每次操作前各定位一次。这意味着，如果在两次调用之间由于重新渲染导致 DOM 发生变化，将使用与定位器对应的新元素。

Locator locator = page.getByRole(AriaRole.BUTTON,
                                 new Page.GetByRoleOptions().setName("Sign in"));

locator.hover();
locator.click();

请注意，所有创建定位器的方法，例如 Page.getByLabel()，在 Locator 和 FrameLocator 类中也同样可用，因此你可以将它们链接起来，逐步缩小定位范围。

Locator locator = page
   .frameLocator("#my-frame")
   .getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"));

locator.click();

按角色定位

Page.getByRole() 定位器反映了用户和辅助技术对页面的感知，例如某个元素是按钮还是复选框。按角色定位时，通常还应传递可访问名称，以便定位器能精准定位到确切元素。

例如，考虑以下 DOM 结构。

http://localhost:3000

注册

<h3>注册</h3>
<label>
  <input type="checkbox" /> 订阅
</label>
<br/>
<button>提交</button>

你可以通过每个元素的隐式角色来定位它们：

assertThat(page
    .getByRole(AriaRole.HEADING,
               new Page.GetByRoleOptions().setName("注册")))
    .isVisible();

page.getByRole(AriaRole.CHECKBOX,
               new Page.GetByRoleOptions().setName("订阅"))
    .check();

page.getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName(
                   Pattern.compile("提交", Pattern.CASE_INSENSITIVE)))
    .click();

角色定位器包括按钮、复选框、标题、链接、列表、表格等等，并遵循 W3C 关于 ARIA 角色、ARIA 属性和可访问名称的规范。请注意，许多 HTML 元素（如 <button>）都有一个隐式定义的角色，角色定位器可以识别该角色。

请注意，角色定位器 不能替代 可访问性审核和一致性测试，而是能就 ARIA 指南给出早期反馈。

何时使用角色定位器

我们建议优先使用角色定位器来定位元素，因为这与用户和辅助技术感知页面的方式最为接近。

通过标签定位

大多数表单控件通常都有专门的标签，可方便地用于与表单进行交互。在这种情况下，可以使用 Page.getByLabel() 通过关联的标签来定位控件。

例如，考虑以下 DOM 结构。

http://localhost:3000

密码

<label>密码 <input type="password" /></label>

可以在通过标签文本定位到输入框后填充内容：

page.getByLabel("密码").fill("secret");

何时使用标签定位器

定位表单字段时使用此定位器。

通过占位符定位

输入框可能有一个 placeholder 属性，用于向用户提示应输入什么值。可以使用 Page.getByPlaceholder() 来定位这样的输入框。

例如，考虑以下 DOM 结构。

http://localhost:3000

<input type="email" placeholder="name@example.com" />

可以在通过占位符文本定位到输入框后填充内容：

page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");

何时使用占位符定位器

定位没有标签但有占位符文本的表单元素时使用此定位器。

通过文本定位

通过元素包含的文本查找元素。使用 Page.getByText() 时，可以按子字符串、精确字符串或正则表达式进行匹配。

例如，考虑以下 DOM 结构。

http://localhost:3000

Welcome, John

<span>Welcome, John</span>

可以通过元素包含的文本定位该元素：

assertThat(page.getByText("Welcome, John")).isVisible();

设置精确匹配：

assertThat(page
    .getByText("Welcome, John", new Page.GetByTextOptions().setExact(true)))
    .isVisible();

使用正则表达式匹配：

assertThat(page
    .getByText(Pattern.compile("welcome, john$", Pattern.CASE_INSENSITIVE)))
    .isVisible();

备注

即使是精确匹配，按文本匹配也总会对空白字符进行规范化处理。例如，它会将多个空格合并为一个，将换行符转换为空格，并忽略前导和尾随的空白字符。

何时使用文本定位器

我们建议使用文本定位器查找非交互式元素，如 div、span、p 等。对于交互式元素，如 button、a、input 等，请使用角色定位器。

还可以按文本过滤，这在尝试在列表中查找特定项目时很有用。

通过替代文本（alt text）定位

所有图像都应该有一个 alt 属性来描述该图像。你可以使用 Page.getByAltText() 基于替代文本定位图像。

例如，考虑以下 DOM 结构。

http://localhost:3000

<img alt="Playwright 徽标" src="/img/playwright-logo.svg" width="100" />

你可以在通过替代文本定位到图像后点击它：

page.getByAltText("Playwright 徽标").click();

何时使用替代文本定位器

当你的元素（如 img 和 area 元素）支持替代文本时，使用此定位器。

通过标题（title）定位

使用 Page.getByTitle() 定位具有匹配标题属性的元素。

例如，考虑以下 DOM 结构。

http://localhost:3000

25 个问题

<span title='问题数量'>25 个问题</span>

你可以在通过标题文本定位到元素后检查问题数量：

assertThat(page.getByTitle("问题数量")).hasText("25 个问题");

何时使用标题定位器

当你的元素具有 title 属性时，使用此定位器。

通过测试 ID 定位

通过测试 ID 进行测试是最可靠的测试方式，因为即使文本或属性的角色发生变化，测试仍会通过。质量保证人员（QA）和开发人员应定义明确的测试 ID，并使用 Page.getByTestId() 来查询它们。然而，通过测试 ID 进行测试并非面向用户。如果角色或文本值对你很重要，那么可以考虑使用面向用户的定位器，如角色定位器和文本定位器。

例如，考虑以下 DOM 结构。

http://localhost:3000

<button data-testid="directions">Itinéraire</button>

你可以通过测试 ID 定位该元素：

page.getByTestId("directions").click();

何时使用测试 ID 定位器

当你选择使用测试 ID 方法，或者无法通过角色或文本进行定位时，也可以使用测试 ID。

设置自定义测试 ID 属性

默认情况下，Page.getByTestId() 将基于 data-testid 属性定位元素，但你可以在测试配置中进行配置，或者通过调用 Selectors.setTestIdAttribute() 来配置。

设置测试 ID，以便在测试中使用自定义数据属性。

playwright.selectors().setTestIdAttribute("data-pw");

现在，在你的 HTML 中，你可以使用 data-pw 作为测试 ID，而不是默认的 data-testid。

http://localhost:3000

<button data-pw="directions">Itinéraire</button>

然后像平常一样定位元素：

page.getByTestId("directions").click();

通过 CSS 或 XPath 定位

如果确实必须使用 CSS 或 XPath 定位器，可以使用 Page.locator() 创建一个定位器，该定位器接受一个选择器，用于描述如何在页面中查找元素。Playwright 支持 CSS 和 XPath 选择器，如果省略 css= 或 xpath= 前缀，Playwright 会自动检测选择器类型。

page.locator("css=button").click();
page.locator("xpath=//button").click();

page.locator("button").click();
page.locator("//button").click();

XPath 和 CSS 选择器可能与 DOM 结构或实现相关联。当 DOM 结构发生变化时，这些选择器可能会失效。以下冗长的 CSS 或 XPath 链是导致测试不稳定的 不良实践 示例：

page.locator(
    "#tsf > div:nth-child(2) > div.A8SBwf > div.RNNXgb > div > div.a4bIc > input"
).click();

page.locator("//*[@id='tsf']/div[2]/div[1]/div[1]/div/div[2]/input").click();

何时使用此方法

不建议使用 CSS 和 XPath，因为 DOM 经常变化，可能导致测试不可靠。相反，可以尝试使用与用户感知页面方式相近的定位器，例如角色定位器，或使用测试 ID 定义明确的测试契约。

在 Shadow DOM 中定位

Playwright 中的所有定位器默认都适用于 Shadow DOM 中的元素。例外情况如下：

通过 XPath 定位不会穿透影子根（shadow root）。
不支持封闭模式的影子根。

考虑以下自定义 web 组件的示例：

<x-details role=button aria-expanded=true aria-controls=inner-details>
  <div>Title</div>
  #shadow-root
    <div id=inner-details>Details</div>
</x-details>

你可以像影子根根本不存在一样进行定位。

要点击 <div>Details</div>：

page.getByText("Details").click();

<x-details role=button aria-expanded=true aria-controls=inner-details>
  <div>Title</div>
  #shadow-root
    <div id=inner-details>Details</div>
</x-details>

要点击 <x-details>：

page.locator("x-details", new Page.LocatorOptions().setHasText("Details"))
    .click();

<x-details role=button aria-expanded=true aria-controls=inner-details>
  <div>Title</div>
  #shadow-root
    <div id=inner-details>Details</div>
</x-details>

要确保 <x-details> 包含文本 “Details”：

assertThat(page.locator("x-details")).containsText("Details");

筛选定位器

考虑以下 DOM 结构，我们想要点击第二个产品卡片的购买按钮。为了筛选出正确的定位器，我们有几种选择。

http://localhost:3000

产品 1
产品 2

<ul>
  <li>
    <h3>产品 1</h3>
    <button>加入购物车</button>
  </li>
  <li>
    <h3>产品 2</h3>
    <button>加入购物车</button>
  </li>
</ul>

按文本筛选

可以使用 Locator.filter() 方法按文本筛选定位器。它会在元素内部的某个位置（可能在后代元素中）搜索特定字符串，且不区分大小写。你也可以传入正则表达式。

page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions().setHasText("Product 2"))
    .getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName("Add to cart"))
    .click();

使用正则表达式：

page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions()
        .setHasText(Pattern.compile("Product 2")))
    .getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName("Add to cart"))
    .click();

按不包含文本筛选

或者，按 不包含 文本进行筛选：

// 5 个有货商品
assertThat(page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions().setHasNotText("Out of stock")))
    .hasCount(5);

按子元素/后代元素过滤

定位器支持一个选项，仅选择具有或不具有与另一个定位器匹配的后代元素的元素。因此，你可以使用任何其他定位器进行过滤，例如 Locator.getByRole()、Locator.getByTestId()、Locator.getByText() 等。

http://localhost:3000

产品 1
产品 2

<ul>
  <li>
    <h3>产品 1</h3>
    <button>加入购物车</button>
  </li>
  <li>
    <h3>产品 2</h3>
    <button>加入购物车</button>
  </li>
</ul>

page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions()
        .setHas(page.GetByRole(AriaRole.HEADING, new Page.GetByRoleOptions()
        .setName("产品 2"))))
    .getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName("加入购物车"))
    .click();

我们还可以断言产品卡片，确保只有一个：

assertThat(page
    .getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions()
        .setHas(page.GetByRole(AriaRole.HEADING,
                               new Page.GetByRoleOptions().setName("产品 2")))))
    .hasCount(1);

过滤定位器 必须是相对于 原始定位器的，并且从原始定位器匹配的元素开始查询，而不是从文档根开始。因此，以下操作将不起作用，因为过滤定位器从 <ul> 列表元素开始匹配，而该元素在原始定位器匹配的 <li> 列表项之外：

// ✖ 错误
assertThat(page
    .getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions()
        .setHas(page.GetByRole(AriaRole.LIST)
                    .GetByRole(AriaRole.HEADING,
                               new Page.GetByRoleOptions().setName("产品 2")))))
    .hasCount(1);

根据不存在子元素/后代元素进行筛选

我们还可以根据内部 不存在 匹配元素进行筛选。

assertThat(page
    .getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions().setHasNot(page.getByText("Product 2"))))
    .hasCount(1);

请注意，内部定位器是从外部定位器开始匹配的，而不是从文档根目录开始。

定位器操作符

在定位器内部进行匹配

你可以链式调用创建定位器的方法，比如 Page.getByText() 或 Locator.getByRole()，将搜索范围缩小到页面的特定部分。

在这个示例中，我们首先通过定位 listitem 角色创建一个名为 product 的定位器。然后根据文本进行筛选。我们可以再次使用 product 定位器通过按钮角色获取并点击它，然后使用断言确保只有一个文本为 "Product 2" 的产品。

Locator product = page
    .getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions().setHasText("Product 2"));

product
    .getByRole(AriaRole.BUTTON,
               new Locator.GetByRoleOptions().setName("Add to cart"))
    .click();

你还可以将两个定位器链接在一起，例如在特定对话框中找到 "保存" 按钮：

Locator saveButton = page.getByRole(AriaRole.BUTTON,
                                    new Page.GetByRoleOptions().setName("Save"));
// ...
Locator dialog = page.getByTestId("settings-dialog");
dialog.locator(saveButton).click();

同时匹配两个定位器

方法 Locator.and() 通过匹配额外的定位器来缩小现有定位器的范围。例如，你可以结合 Page.getByRole() 和 Page.getByTitle() 来同时按角色和标题进行匹配。

Locator button = page.getByRole(AriaRole.BUTTON).and(page.getByTitle("Subscribe"));

匹配两个可选定位器中的任意一个

如果你想定位两个或更多元素中的任意一个，且不知道具体是哪一个，可以使用 Locator.or() 创建一个定位器，它可以匹配任意一个或两个可选元素。

例如，假设你想点击 “新建邮件” 按钮，但有时会弹出安全设置对话框。在这种情况下，你可以等待 “新建邮件” 按钮或对话框出现，并相应地采取行动。

备注

如果 “新建邮件” 按钮和安全对话框同时出现在屏幕上，“or” 定位器将匹配它们两个，这可能会抛出 "严格模式违规" 错误。在这种情况下，你可以使用 Locator.first() 只匹配其中一个。

Locator newEmail = page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("New"));
Locator dialog = page.getByText("Confirm security settings");
assertThat(newEmail.or(dialog).first()).isVisible();
if (dialog.isVisible())
  page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Dismiss")).click();
newEmail.click();

仅匹配可见元素

备注

通常，找到一种更可靠的方法来唯一标识元素，比检查可见性更好。

假设有一个包含两个按钮的页面，第一个按钮不可见，第二个按钮可见。

<button style='display: none'>不可见</button>
<button>可见</button>

这将找到两个按钮，并抛出一个严格性违规错误：
```
page.locator("button").click();
```

这只会找到第二个按钮，因为它是可见的，然后点击它。

page.locator("button").filter(new Locator.FilterOptions.setVisible(true)).click();

列表

统计列表中的项目数量

你可以对定位器进行断言，以统计列表中的项目数量。

例如，考虑以下 DOM 结构：

http://localhost:3000

苹果
香蕉
橙子

<ul>
  <li>苹果</li>
  <li>香蕉</li>
  <li>橙子</li>
</ul>

使用 count 断言来确保列表有 3 个项目。

assertThat(page.getByRole(AriaRole.LISTITEM)).hasCount(3);

断言列表中的所有文本

你可以对定位器进行断言，以查找列表中的所有文本。

例如，考虑以下 DOM 结构：

http://localhost:3000

苹果
香蕉
橙子

<ul>
  <li>苹果</li>
  <li>香蕉</li>
  <li>橙子</li>
</ul>

使用 assertThat(locator).hasText() 来确保列表包含文本 “苹果”、“香蕉” 和 “橙子”。

assertThat(page
    .getByRole(AriaRole.LISTITEM))
    .hasText(new String[] { "苹果", "香蕉", "橙子" });

获取特定项目

有多种方法可以获取列表中的特定项目。

通过文本获取

使用 Page.getByText() 方法，根据文本内容在列表中定位元素，然后点击该元素。

例如，考虑以下 DOM 结构：

http://localhost:3000

apple
banana
orange

<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

根据文本内容定位一个项目并点击它。

page.getByText("orange").click();

按文本筛选

使用 Locator.filter() 在列表中定位特定项目。

例如，考虑以下 DOM 结构：

http://localhost:3000

apple
banana
orange

<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

通过 “listitem” 角色定位一个项目，然后按 “orange” 文本进行筛选，再点击它。

page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions().setHasText("orange"))
    .click();

通过测试 ID 获取

使用 Page.getByTestId() 方法在列表中定位元素。如果还没有测试 ID，可能需要修改 HTML 并添加一个测试 ID。

例如，考虑以下 DOM 结构：

http://localhost:3000

apple
banana
orange

<ul>
  <li data-testid='apple'>apple</li>
  <li data-testid='banana'>banana</li>
  <li data-testid='orange'>orange</li>
</ul>

通过 “orange” 测试 ID 定位一个项目，然后点击它。

page.getByTestId("orange").click();

通过第 n 个项目获取

如果你有一组相同的元素，并且区分它们的唯一方法是顺序，那么你可以使用 Locator.first()、Locator.last() 或 Locator.nth() 从列表中选择特定的元素。

Locator banana = page.getByRole(AriaRole.LISTITEM).nth(1);

不过，使用此方法时要谨慎。很多时候，页面可能会发生变化，定位器可能会指向与你预期完全不同的元素。相反，尝试想出一个唯一的定位器，使其符合严格性标准。

链式过滤

当你有各种相似的元素时，可以使用 Locator.filter() 方法来选择正确的元素。你还可以链接多个过滤器来缩小选择范围。

例如，考虑以下 DOM 结构：

http://localhost:3000

John
Mary
John
Mary

<ul>
  <li>
    <div>John</div>
    <div><button>打招呼</button></div>
  </li>
  <li>
    <div>Mary</div>
    <div><button>打招呼</button></div>
  </li>
  <li>
    <div>John</div>
    <div><button>说再见</button></div>
  </li>
  <li>
    <div>Mary</div>
    <div><button>说再见</button></div>
  </li>
</ul>

要对包含 “Mary” 和 “说再见” 的行进行截图：

Locator rowLocator = page.getByRole(AriaRole.LISTITEM);

rowLocator
    .filter(new Locator.FilterOptions().setHasText("Mary"))
    .filter(new Locator.FilterOptions()
        .setHas(page.getByRole(
            AriaRole.BUTTON,
            new Page.GetByRoleOptions().setName("说再见"))))
    .screenshot(new Page.ScreenshotOptions().setPath("screenshot.png"));

此时，你的项目根目录中应该有一个 “screenshot.png” 文件。

罕见用例

对列表中的每个元素执行某些操作

迭代元素：

for (Locator row : page.getByRole(AriaRole.LISTITEM).all())
  System.out.println(row.textContent());

使用普通 for 循环进行迭代：

Locator rows = page.getByRole(AriaRole.LISTITEM);
int count = rows.count();
for (int i = 0; i < count; ++i)
  System.out.println(rows.nth(i).textContent());

在页面中求值

Locator.evaluateAll() 内部的代码在页面中运行，你可以在其中调用任何 DOM API。

Locator rows = page.getByRole(AriaRole.LISTITEM);
Object texts = rows.evaluateAll(
    "list => list.map(element => element.textContent)");

严格性

定位器是严格的。这意味着，如果匹配的元素不止一个，对定位器执行的所有暗示某个目标 DOM 元素的操作都将抛出异常。例如，如果 DOM 中有多个按钮，以下调用将抛出异常：

如果不止一个则抛出错误

page.getByRole(AriaRole.BUTTON).click();

另一方面，Playwright 能识别你何时执行多元素操作，因此，当定位器解析为多个元素时，以下调用完全正常。

对多个元素正常工作

page.getByRole(AriaRole.BUTTON).count();

你可以通过 Locator.first()、Locator.last() 和 Locator.nth() 明确选择不进行严格性检查，从而告知 Playwright 当有多个元素匹配时使用哪个元素。不建议使用这些方法，因为当页面发生变化时，Playwright 可能会点击你不想要的元素。相反，应遵循上述最佳实践来创建唯一标识目标元素的定位器。

简介​

快速指南​

定位元素​

按角色定位​

注册

通过标签定位​

通过占位符定位​

通过文本定位​

通过替代文本（alt text）定位​

通过标题（title）定位​

通过测试 ID 定位​

设置自定义测试 ID 属性​

通过 CSS 或 XPath 定位​

在 Shadow DOM 中定位​

筛选定位器​

产品 1

产品 2

按文本筛选​

按不包含文本筛选​

按子元素/后代元素过滤​

产品 1

产品 2

根据不存在子元素/后代元素进行筛选​

定位器操作符​

在定位器内部进行匹配​

同时匹配两个定位器​

匹配两个可选定位器中的任意一个​

仅匹配可见元素​

列表​

统计列表中的项目数量​

断言列表中的所有文本​

获取特定项目​

通过文本获取​

按文本筛选​

通过测试 ID 获取​

通过第 n 个项目获取​

链式过滤​

罕见用例​

对列表中的每个元素执行某些操作​

在页面中求值​

严格性​

如果不止一个则抛出错误​

对多个元素正常工作​

更多定位器​

简介

快速指南

定位元素

按角色定位

通过标签定位

通过占位符定位

通过文本定位

通过替代文本（alt text）定位

通过标题（title）定位

通过测试 ID 定位

设置自定义测试 ID 属性

通过 CSS 或 XPath 定位

在 Shadow DOM 中定位

筛选定位器

按文本筛选

按不包含文本筛选

按子元素/后代元素过滤

根据不存在子元素/后代元素进行筛选

定位器操作符

在定位器内部进行匹配

同时匹配两个定位器

匹配两个可选定位器中的任意一个

仅匹配可见元素

列表

统计列表中的项目数量

断言列表中的所有文本

获取特定项目

通过文本获取

按文本筛选

通过测试 ID 获取

通过第 n 个项目获取

链式过滤

罕见用例

对列表中的每个元素执行某些操作

在页面中求值

严格性

如果不止一个则抛出错误

对多个元素正常工作

更多定位器