定位器

简介

定位器是 Playwright 自动等待和可重试性的核心。简而言之，定位器表示在任何时刻在页面上查找元素的方式。

快速指南

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

• Page.GetByRole() 按显式和隐式辅助功能属性定位。
• Page.GetByText() 按文本内容定位。
• Page.GetByLabel() 按关联标签的文本定位表单控件。
• Page.GetByPlaceholder() 按占位符定位输入。
• Page.GetByAltText() 按其文本替代项定位元素（通常是图像）。
• Page.GetByTitle() 按其标题属性定位元素。
• Page.GetByTestId() 根据其 data-testid 属性定位元素（可以配置其他属性）。

await Page.GetByLabel("User Name").FillAsync("John");

await Page.GetByLabel("Password").FillAsync("secret-password");

await Page.GetByRole(AriaRole.Button, new() { Name = "Sign in" }).ClickAsync();

await Expect(Page.GetByText("Welcome, John!")).ToBeVisibleAsync();

定位元素

Playwright 附带多个内置定位器。为了使测试更具弹性，我们建议优先使用面向用户的属性和显式契约，例如 Page.GetByRole()。

例如，考虑以下 DOM 结构。

https://:3000

<button>Sign in</button>

通过其 button 角色和名称“登录”定位元素。

await Page.GetByRole(AriaRole.Button, new() { Name = "Sign in" }).ClickAsync();

注意

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

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

var locator = Page.GetByRole(AriaRole.Button, new() { Name = "Sign in" });

await locator.HoverAsync();
await locator.ClickAsync();

请注意，所有创建定位器的方法，例如 Page.GetByLabel()，也可用于 Locator 和 FrameLocator 类，因此您可以将它们链接起来并迭代地缩小定位器范围。

var locator = Page
    .FrameLocator("#my-frame")
    .GetByRole(AriaRole.Button, new() { Name = "Sign in" });

await locator.ClickAsync();

按角色定位

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

例如，考虑以下 DOM 结构。

https://:3000

注册

订阅

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

您可以按其隐式角色定位每个元素

await Expect(Page
    .GetByRole(AriaRole.Heading, new() { Name = "Sign up" }))
    .ToBeVisibleAsync();

await Page
    .GetByRole(AriaRole.Checkbox, new() { Name = "Subscribe" })
    .CheckAsync();

await Page
    .GetByRole(AriaRole.Button, new() {
        NameRegex = new Regex("submit", RegexOptions.IgnoreCase)
    })
    .ClickAsync();

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

请注意，角色定位器不替代辅助功能审计和符合性测试，而是提供有关 ARIA 指南的早期反馈。

何时使用角色定位器

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

按标签定位

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

例如，考虑以下 DOM 结构。

https://:3000

密码

<label>Password <input type="password" /></label>

您可以通过标签文本定位输入框后填充它

await Page.GetByLabel("Password").FillAsync("secret");

何时使用标签定位器

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

按占位符定位

输入框可能有一个 placeholder 属性来提示用户应该输入什么值。您可以使用 Page.GetByPlaceholder() 定位此类输入框。

例如，考虑以下 DOM 结构。

https://:3000

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

您可以按占位符文本定位输入框后填充它

await Page
    .GetByPlaceholder("name@example.com")
    .FillAsync("playwright@microsoft.com");

何时使用占位符定位器

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

按文本定位

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

例如，考虑以下 DOM 结构。

https://:3000

欢迎，约翰

<span>Welcome, John</span>

您可以按元素包含的文本定位它

await Expect(Page.GetByText("Welcome, John")).ToBeVisibleAsync();

设置精确匹配

await Expect(Page
    .GetByText("Welcome, John", new() { Exact = true }))
    .ToBeVisibleAsync();

使用正则表达式匹配

await Expect(Page
    .GetByText(new Regex("welcome, john", RegexOptions.IgnoreCase)))
    .ToBeVisibleAsync();

注意

按文本匹配始终会规范化空格，即使是精确匹配也是如此。例如，它会将多个空格转换为一个空格，将换行符转换为空格，并忽略前导和尾随空格。

何时使用文本定位器

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

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

按 alt 文本定位

所有图像都应具有描述图像的 alt 属性。您可以使用 Page.GetByAltText() 根据文本替代项定位图像。

例如，考虑以下 DOM 结构。

https://:3000

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

您可以通过文本替代内容定位图像后点击它

await Page.GetByAltText("playwright logo").ClickAsync();

何时使用alt定位器

当您的元素支持 alt 文本时（如 img 和 area 元素），请使用此定位器。

按 title 定位

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

例如，考虑以下 DOM 结构。

https://:3000

25 个问题

<span title='Issues count'>25 issues</span>

您可以通过 title 文本定位它后检查问题数量

await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");

何时使用标题定位器

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

按 test id 定位

通过测试 ID 进行测试是最具弹性的测试方式，因为即使文本或属性角色发生变化，测试仍然会通过。QA 和开发人员应定义明确的测试 ID，并使用 Page.GetByTestId() 查询它们。但是，通过测试 ID 进行测试并非面向用户。如果角色或文本值对您很重要，请考虑使用面向用户的定位器，例如角色和文本定位器。

例如，考虑以下 DOM 结构。

https://:3000

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

您可以按其测试 ID 定位元素

await Page.GetByTestId("directions").ClickAsync();

何时使用testid定位器

您还可以在选择使用测试 ID 方法时，或者无法通过角色或文本定位时使用测试 ID。

设置自定义 test id 属性

默认情况下，Page.GetByTestId() 将根据 data-testid 属性定位元素，但您可以在测试配置中或通过调用 Selectors.SetTestIdAttribute() 来配置它。

设置测试 ID 以便为您的测试使用自定义数据属性。

playwright.Selectors.SetTestIdAttribute("data-pw");

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

https://:3000

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

然后像通常一样定位元素

await Page.GetByTestId("directions").ClickAsync();

按 CSS 或 XPath 定位

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

await Page.Locator("css=button").ClickAsync();
await Page.Locator("xpath=//button").ClickAsync();

await Page.Locator("button").ClickAsync();
await Page.Locator("//button").ClickAsync();

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

await Page.Locator("#tsf > div:nth-child(2) > div.A8SBwf > div.RNNXgb > div > div.a4bIc > input").ClickAsync();

await Page.Locator("//*[@id='tsf']/div[2]/div[1]/div[1]/div/div[2]/input").ClickAsync();

何时使用此方法

不建议使用 CSS 和 XPath，因为 DOM 经常变化，导致测试不稳定。相反，尝试提出一种接近用户感知页面的定位器，例如角色定位器或使用测试 ID 定义显式测试契约。

在 Shadow DOM 中定位

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

• 按 XPath 定位不会穿透 Shadow Roots。
• 不支持封闭模式 Shadow Roots。

考虑以下带有自定义 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>

您可以像 Shadow Root 不存在一样进行定位。

点击 <div>Details</div>

await page.GetByText("Details").ClickAsync();

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

await page
    .Locator("x-details", new() { HasText = "Details" })
    .ClickAsync();

<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> 包含文本“详细信息”

await Expect(Page.Locator("x-details")).ToContainTextAsync("Details");

过滤定位器

考虑以下 DOM 结构，我们想点击第二个产品卡片的购买按钮。我们有几种选择来过滤定位器以获得正确的定位器。

https://:3000

• 产品 1

• 产品 2

<ul>
  <li>
    <h3>Product 1</h3>
    <button>Add to cart</button>
  </li>
  <li>
    <h3>Product 2</h3>
    <button>Add to cart</button>
  </li>
</ul>

按文本过滤

定位器可以使用 Locator.Filter() 方法按文本进行过滤。它将不区分大小写地在元素内部的某个位置（可能在子元素中）搜索特定字符串。您还可以传递正则表达式。

await page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() { HasText = "Product 2" })
    .GetByRole(AriaRole.Button, new() { Name = "Add to cart" })
    .ClickAsync();

使用正则表达式

await page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() { HasTextRegex = new Regex("Product 2") })
    .GetByRole(AriaRole.Button, new() { Name = "Add to cart" })
    .ClickAsync();

按不包含文本过滤

或者，按不包含文本进行过滤

// 5 in-stock items
await Expect(Page.getByRole(AriaRole.Listitem).Filter(new() { HasNotText = "Out of stock" }))
    .ToHaveCountAsync(5);

按子/后代过滤

定位器支持一个选项，只选择具有或不具有匹配另一个定位器的子元素的元素。因此，您可以按任何其他定位器进行过滤，例如 Locator.GetByRole()、Locator.GetByTestId()、Locator.GetByText() 等。

https://:3000

• 产品 1

• 产品 2

<ul>
  <li>
    <h3>Product 1</h3>
    <button>Add to cart</button>
  </li>
  <li>
    <h3>Product 2</h3>
    <button>Add to cart</button>
  </li>
</ul>

await page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() {
        Has = page.GetByRole(AriaRole.Heading, new() {
            Name = "Product 2"
        })
    })
    .GetByRole(AriaRole.Button, new() { Name = "Add to cart" })
    .ClickAsync();

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

await Expect(Page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() {
        Has = page.GetByRole(AriaRole.Heading, new() { Name = "Product 2" })
    }))
    .ToHaveCountAsync(1);

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

// ✖ WRONG
await Expect(Page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() {
        Has = page.GetByRole(AriaRole.List).GetByRole(AriaRole.Heading, new() { Name = "Product 2" })
    }))
    .ToHaveCountAsync(1);

按不包含子/后代过滤

我们还可以按不包含匹配元素进行过滤。

await Expect(Page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() {
        HasNot = page.GetByRole(AriaRole.Heading, new() { Name = "Product 2" })
    }))
    .ToHaveCountAsync(1);

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

定位器操作符

在定位器内部匹配

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

在此示例中，我们首先通过定位其 listitem 角色来创建一个名为 product 的定位器。然后我们按文本进行过滤。我们可以再次使用 product 定位器来按按钮角色获取并单击它，然后使用断言确保只有一个文本为“产品 2”的产品。

var product = page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() { HasText = "Product 2" });

await product
    .GetByRole(AriaRole.Button, new() { Name = "Add to cart" })
    .ClickAsync();

您还可以将两个定位器链式调用在一起，例如在特定对话框中查找“保存”按钮

var saveButton = page.GetByRole(AriaRole.Button, new() { Name = "Save" });
// ...
var dialog = page.GetByTestId("settings-dialog");
await dialog.Locator(saveButton).ClickAsync();

同时匹配两个定位器

方法 Locator.And() 通过匹配附加定位器来缩小现有定位器的范围。例如，您可以结合使用 Page.GetByRole() 和 Page.GetByTitle() 来同时匹配角色和标题。

var button = page.GetByRole(AriaRole.Button).And(page.GetByTitle("Subscribe"));

匹配两个或多个备选定位器中的一个

如果您想定位两个或多个元素中的一个，并且不知道是哪一个，请使用 Locator.Or() 创建一个可以匹配其中任意一个或所有备选方案的定位器。

例如，考虑一个您想点击“新电子邮件”按钮的场景，但有时会显示安全设置对话框。在这种情况下，您可以等待“新电子邮件”按钮或对话框，并根据情况采取行动。

注意

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

var newEmail = page.GetByRole(AriaRole.Button, new() { Name = "New" });
var dialog = page.GetByText("Confirm security settings");
await Expect(newEmail.Or(dialog).First).ToBeVisibleAsync();
if (await dialog.IsVisibleAsync())
  await page.GetByRole(AriaRole.Button, new() { Name = "Dismiss" }).ClickAsync();
await newEmail.ClickAsync();

只匹配可见元素

注意

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

考虑一个有两个按钮的页面，第一个不可见，第二个可见。

<button style='display: none'>Invisible</button>
<button>Visible</button>

• 这将找到两个按钮并抛出严格性违规错误

  await page.Locator("button").ClickAsync();

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

  await page.Locator("button").Filter(new() { Visible = true }).ClickAsync();

列表

统计列表中的项目数

您可以断言定位器以统计列表中的项目数。

例如，考虑以下 DOM 结构

https://:3000

• 苹果
• 香蕉
• 橙子

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

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

await Expect(Page.GetByRole(AriaRole.Listitem)).ToHaveCountAsync(3);

断言列表中所有文本

您可以断言定位器以查找列表中所有文本。

例如，考虑以下 DOM 结构

https://:3000

• 苹果
• 香蕉
• 橙子

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

使用 Expect(Locator).ToHaveTextAsync() 确保列表包含文本“apple”、“banana”和“orange”。

await Expect(Page
    .GetByRole(AriaRole.Listitem))
    .ToHaveTextAsync(new string[] {"apple", "banana", "orange"});

获取特定项目

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

按文本获取

使用 Page.GetByText() 方法按文本内容定位列表中的元素，然后单击它。

例如，考虑以下 DOM 结构

https://:3000

• 苹果
• 香蕉
• 橙子

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

按其文本内容定位项目并点击它。

await page.GetByText("orange").ClickAsync();

按文本过滤

使用 Locator.Filter() 定位列表中的特定项。

例如，考虑以下 DOM 结构

https://:3000

• 苹果
• 香蕉
• 橙子

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

按“listitem”角色定位项目，然后按“orange”文本过滤，然后点击它。

await page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() { HasText = "orange" })
    .ClickAsync();

按 test id 获取

使用 Page.GetByTestId() 方法定位列表中的元素。如果您尚未拥有测试 ID，则可能需要修改 HTML 并添加测试 ID。

例如，考虑以下 DOM 结构

https://:3000

• 苹果
• 香蕉
• 橙子

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

按其测试 ID“orange”定位项目，然后点击它。

await page.GetByTestId("orange").ClickAsync();

按第 n 项获取

如果您有一个相同元素的列表，并且区分它们唯一的方法是顺序，则可以使用 Locator.First、Locator.Last 或 Locator.Nth() 从列表中选择特定元素。

var banana = await page.GetByRole(AriaRole.Listitem).Nth(1);

但是，请谨慎使用此方法。通常，页面可能会发生变化，定位器将指向与您预期完全不同的元素。相反，尝试提出一个唯一的定位器，该定位器将通过严格性标准。

链式过滤器

当元素具有各种相似性时，您可以使用 Locator.Filter() 方法选择正确的元素。您还可以链式调用多个过滤器以缩小选择范围。

例如，考虑以下 DOM 结构

https://:3000

• 约翰
• 玛丽
• 约翰
• 玛丽

<ul>
  <li>
    <div>John</div>
    <div><button>Say hello</button></div>
  </li>
  <li>
    <div>Mary</div>
    <div><button>Say hello</button></div>
  </li>
  <li>
    <div>John</div>
    <div><button>Say goodbye</button></div>
  </li>
  <li>
    <div>Mary</div>
    <div><button>Say goodbye</button></div>
  </li>
</ul>

截取带有“玛丽”和“说再见”的行的屏幕截图

var rowLocator = page.GetByRole(AriaRole.Listitem);

await rowLocator
    .Filter(new() { HasText = "Mary" })
    .Filter(new() {
        Has = page.GetByRole(AriaRole.Button, new() { Name = "Say goodbye" })
    })
    .ScreenshotAsync(new() { Path = "screenshot.png" });

您现在应该在项目根目录中有一个“screenshot.png”文件。

不常见的用例

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

迭代元素

foreach (var row in await page.GetByRole(AriaRole.Listitem).AllAsync())
  Console.WriteLine(await row.TextContentAsync());

使用常规 for 循环迭代

var rows = page.GetByRole(AriaRole.Listitem);
var count = await rows.CountAsync();
for (int i = 0; i < count; ++i)
  Console.WriteLine(await rows.Nth(i).TextContentAsync());

在页面中评估

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

var rows = page.GetByRole(AriaRole.Listitem);
var texts = await rows.EvaluateAllAsync(
    "list => list.map(element => element.textContent)");

严格性

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

如果多于一个则抛出错误

await page.GetByRole(AriaRole.Button).ClickAsync();

另一方面，Playwright 了解您何时执行多元素操作，因此当定位器解析为多个元素时，以下调用可以正常工作。

对多个元素正常工作

await page.GetByRole(AriaRole.Button).CountAsync();

您可以通过 Locator.First、Locator.Last 和 Locator.Nth() 明确选择退出严格性检查，告诉 Playwright 在多个元素匹配时使用哪个元素。不建议使用这些方法，因为当您的页面更改时，Playwright 可能会单击您不打算单击的元素。相反，请遵循上述最佳实践，以创建唯一标识目标元素的定位器。

更多定位器

对于不常用的定位器，请参阅其他定位器指南。