定位器
简介
Locator 是 Playwright 自动等待和重试能力的核心部分。 简而言之，定位器代表一种在任何时刻在页面上查找元素的方法。
快速指南
以下是推荐的内置定位器。
- page.getByRole() 通过显式和隐式可访问性属性进行定位。
- page.getByText() 通过文本内容进行定位。
- page.getByLabel() 通过关联标签的文本定位表单控件。
- page.getByPlaceholder() 通过占位符定位输入框。
- page.getByAltText() 通过其替代文本定位元素，通常是图像。
- page.getByTitle() 通过其标题属性定位元素。
- page.getByTestId() 基于其
data-testid属性（可以配置其他属性）定位元素。
await page.getByLabel('User Name').fill('John');
await page.getByLabel('Password').fill('secret-password');
await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page.getByText('Welcome, John!')).toBeVisible();
定位元素
Playwright 提供了多个内置定位器。 为了使测试具有弹性，我们建议优先考虑面向用户的属性和显式约定，例如 page.getByRole()。
例如，考虑以下 DOM 结构。
<button>Sign in</button>
通过角色 button 和名称 “Sign in” 定位元素。
await page.getByRole('button', { name: 'Sign in' }).click();
使用 代码生成器 生成定位器，然后根据需要进行编辑。
每次定位器用于操作时，都会在页面中定位最新的 DOM 元素。 在下面的代码片段中，底层 DOM 元素将被定位两次，每次操作之前一次。 这意味着，如果由于重新渲染导致 DOM 在调用之间发生更改，则将使用与定位器对应的新元素。
const locator = page.getByRole('button', { name: 'Sign in' });
await locator.hover();
await locator.click();
请注意，所有创建定位器的方法，例如 page.getByLabel()，在 Locator 和 FrameLocator 类上也可用，因此您可以将它们链接起来并迭代地缩小定位器的范围。
const locator = page
.frameLocator('#my-frame')
.getByRole('button', { name: 'Sign in' });
await locator.click();
按角色定位
page.getByRole() 定位器反映了用户和辅助技术如何感知页面，例如某些元素是按钮还是复选框。 当按角色定位时，您通常还应该传递可访问的名称，以便定位器精确地找到元素。
例如，考虑以下 DOM 结构。
注册
<h3>Sign up</h3>
<label>
<input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>
您可以按其隐式角色定位每个元素
await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();
await page.getByRole('checkbox', { name: 'Subscribe' }).check();
await page.getByRole('button', { name: /submit/i }).click();
角色定位器包括 按钮、复选框、标题、链接、列表、表格等等，并遵循 W3C 规范，用于 ARIA 角色、ARIA 属性 和 可访问名称。 请注意，许多 html 元素（如 <button>）都有一个 隐式定义的角色，该角色被角色定位器识别。
请注意，角色定位器不能替代可访问性审计和一致性测试，而是提供关于 ARIA 指南的早期反馈。
我们建议优先使用角色定位器来定位元素，因为这是用户和辅助技术感知页面的最接近方式。
按标签定位
大多数表单控件通常都有专用的标签，可以方便地用于与表单进行交互。 在这种情况下，您可以使用 page.getByLabel() 通过其关联的标签定位控件。
例如，考虑以下 DOM 结构。
<label>Password <input type="password" /></label>
您可以在通过标签文本定位输入框后填写内容
await page.getByLabel('Password').fill('secret');
当定位表单字段时，使用此定位器。
按占位符定位
输入框可能具有占位符属性，以提示用户应输入的值。 您可以使用 page.getByPlaceholder() 定位此类输入框。
例如，考虑以下 DOM 结构。
<input type="email" placeholder="name@example.com" />
您可以在通过占位符文本定位输入框后填写内容
await page
.getByPlaceholder('name@example.com')
.fill('playwright@microsoft.com');
当定位没有标签但有占位符文本的表单元素时，使用此定位器。
按文本定位
通过元素包含的文本查找元素。 使用 page.getByText() 时，您可以按子字符串、精确字符串或正则表达式进行匹配。
例如，考虑以下 DOM 结构。
<span>Welcome, John</span>
您可以按其包含的文本定位元素
await expect(page.getByText('Welcome, John')).toBeVisible();
设置精确匹配
await expect(page.getByText('Welcome, John', { exact: true })).toBeVisible();
使用正则表达式匹配
await expect(page.getByText(/welcome, [A-Za-z]+$/i)).toBeVisible();
按文本匹配始终会规范化空格，即使是精确匹配。 例如，它将多个空格变成一个空格，将换行符变成空格，并忽略前导和尾随空格。
我们建议使用文本定位器来查找非交互式元素，如 div、span、p 等。对于交互式元素，如 button、a、input 等，请使用 角色定位器。
您也可以 按文本过滤，这在尝试查找列表中的特定项目时非常有用。
按替代文本定位
所有图像都应具有描述图像的 alt 属性。 您可以使用 page.getByAltText() 基于替代文本定位图像。
例如，考虑以下 DOM 结构。
<img alt="playwright logo" src="/img/playwright-logo.svg" width="100" />
您可以在通过替代文本定位图像后单击它
await page.getByAltText('playwright logo').click();
当您的元素支持替代文本时，例如 img 和 area 元素，请使用此定位器。
按标题定位
使用 page.getByTitle() 定位具有匹配标题属性的元素。
例如，考虑以下 DOM 结构。
<span title='Issues count'>25 issues</span>
您可以在通过标题文本定位问题计数后检查问题计数
await expect(page.getByTitle('Issues count')).toHaveText('25 issues');
当您的元素具有 title 属性时，请使用此定位器。
按测试 ID 定位
通过测试 ID 进行测试是最具弹性的测试方式，即使您的文本或属性的角色发生更改，测试仍然会通过。 QA 和开发人员应定义显式测试 ID 并使用 page.getByTestId() 查询它们。 但是，通过测试 ID 进行测试不是面向用户的。 如果角色或文本值对您很重要，请考虑使用面向用户的定位器，例如 角色 和 文本定位器。
例如，考虑以下 DOM 结构。
<button data-testid="directions">Itinéraire</button>
您可以通过其测试 ID 定位元素
await page.getByTestId('directions').click();
设置自定义测试 ID 属性
默认情况下，page.getByTestId() 将基于 data-testid 属性定位元素，但您可以在测试配置中或通过调用 selectors.setTestIdAttribute() 来配置它。
设置测试 ID 以使用自定义数据属性进行测试。
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
testIdAttribute: 'data-pw'
}
});
在您的 html 中，您现在可以使用 data-pw 作为您的测试 ID，而不是默认的 data-testid。
<button data-pw="directions">Itinéraire</button>
然后像平常一样定位元素
await page.getByTestId('directions').click();
按 CSS 或 XPath 定位
如果您绝对必须使用 CSS 或 XPath 定位器，则可以使用 page.locator() 创建一个定位器，该定位器采用描述如何在页面中查找元素的选择器。 Playwright 支持 CSS 和 XPath 选择器，如果您省略 css= 或 xpath= 前缀，则会自动检测到它们。
await page.locator('css=button').click();
await page.locator('xpath=//button').click();
await page.locator('button').click();
await page.locator('//button').click();
XPath 和 CSS 选择器可以绑定到 DOM 结构或实现。 当 DOM 结构更改时，这些选择器可能会中断。 下面的长 CSS 或 XPath 链是不稳定测试的不良实践示例
await page.locator(
'#tsf > div:nth-child(2) > div.A8SBwf > div.RNNXgb > div > div.a4bIc > input'
).click();
await page
.locator('//*[@id="tsf"]/div[2]/div[1]/div[1]/div/div[2]/input')
.click();
在 Shadow DOM 中定位
Playwright 中的所有定位器默认都适用于 Shadow DOM 中的元素。 例外情况是
- 通过 XPath 定位不会穿透 shadow root。
- 封闭模式 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>
您可以像 shadow root 完全不存在一样进行定位。
要单击 <div>Details</div>
await 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>
await page.locator('x-details', { hasText: '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”
await expect(page.locator('x-details')).toContainText('Details');
过滤定位器
考虑以下 DOM 结构，我们要在其中单击第二个产品卡的购买按钮。 我们有几个选项可以过滤定位器以获得正确的定位器。
产品 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('listitem')
.filter({ hasText: 'Product 2' })
.getByRole('button', { name: 'Add to cart' })
.click();
使用正则表达式
await page
.getByRole('listitem')
.filter({ hasText: /Product 2/ })
.getByRole('button', { name: 'Add to cart' })
.click();
按不包含文本过滤
或者，按不包含文本过滤
// 5 in-stock items
await expect(page.getByRole('listitem').filter({ hasNotText: 'Out of stock' })).toHaveCount(5);
按子项/后代过滤
定位器支持一个选项，仅选择具有或不具有与另一个定位器匹配的后代的元素。 因此，您可以通过任何其他定位器进行过滤，例如 locator.getByRole()、locator.getByTestId()、locator.getByText() 等。
产品 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('listitem')
.filter({ has: page.getByRole('heading', { name: 'Product 2' }) })
.getByRole('button', { name: 'Add to cart' })
.click();
我们还可以断言产品卡，以确保只有一个
await expect(page
.getByRole('listitem')
.filter({ has: page.getByRole('heading', { name: 'Product 2' }) }))
.toHaveCount(1);
过滤定位器必须相对于原始定位器，并且查询从原始定位器匹配项开始，而不是从文档根目录开始。 因此，以下代码将不起作用，因为过滤定位器从 <ul> 列表元素开始匹配，该元素位于原始定位器匹配的 <li> 列表项之外
// ✖ WRONG
await expect(page
.getByRole('listitem')
.filter({ has: page.getByRole('list').getByText('Product 2') }))
.toHaveCount(1);
按不包含子项/后代过滤
我们还可以按不包含内部匹配元素进行过滤。
await expect(page
.getByRole('listitem')
.filter({ hasNot: page.getByText('Product 2') }))
.toHaveCount(1);
请注意，内部定位器是从外部定位器而不是从文档根目录开始匹配的。
定位器运算符
在定位器内部匹配
您可以链接创建定位器的方法，如 page.getByText() 或 locator.getByRole()，以将搜索范围缩小到页面的特定部分。
在此示例中，我们首先通过定位其 listitem 角色来创建一个名为 product 的定位器。 然后，我们按文本进行过滤。 我们可以再次使用 product 定位器按按钮角色获取并单击它，然后使用断言来确保只有一个文本为 “Product 2” 的产品。
const product = page.getByRole('listitem').filter({ hasText: 'Product 2' });
await product.getByRole('button', { name: 'Add to cart' }).click();
await expect(product).toHaveCount(1);
您还可以将两个定位器链接在一起，例如，在特定对话框中查找 “保存” 按钮
const saveButton = page.getByRole('button', { name: 'Save' });
// ...
const dialog = page.getByTestId('settings-dialog');
await dialog.locator(saveButton).click();
同时匹配两个定位器
方法 locator.and() 通过匹配附加定位器来缩小现有定位器的范围。 例如，您可以组合 page.getByRole() 和 page.getByTitle() 以同时按角色和标题进行匹配。
const button = page.getByRole('button').and(page.getByTitle('Subscribe'));
匹配两个备选定位器之一
如果您想定位两个或多个元素中的一个，但您不知道它将是哪一个，请使用 locator.or() 创建一个定位器，该定位器与任何一个或两个备选项都匹配。
例如，考虑这样一种情况：您想单击 “新邮件” 按钮，但有时会出现安全设置对话框。 在这种情况下，您可以等待 “新邮件” 按钮或对话框，并采取相应的操作。
如果 “新邮件” 按钮和安全对话框都出现在屏幕上，“或” 定位器将同时匹配它们，这可能会引发 “严格模式违规” 错误。 在这种情况下，您可以使用 locator.first() 仅匹配其中一个。
const newEmail = page.getByRole('button', { name: 'New' });
const dialog = page.getByText('Confirm security settings');
await expect(newEmail.or(dialog).first()).toBeVisible();
if (await dialog.isVisible())
await page.getByRole('button', { name: 'Dismiss' }).click();
await newEmail.click();
仅匹配可见元素
通常最好找到一种 更可靠的方法 来唯一标识元素，而不是检查可见性。
考虑一个页面，其中包含两个按钮，第一个按钮不可见，第二个按钮 可见。
<button style='display: none'>Invisible</button>
<button>Visible</button>
-
这将找到两个按钮并引发 严格性 违规错误
await page.locator('button').click(); -
这将仅找到第二个按钮，因为它可见，然后单击它。
await page.locator('button').filter({ visible: true }).click();
列表
计算列表中的项目数
您可以断言定位器以计算列表中的项目数。
例如，考虑以下 DOM 结构
- 苹果
- 香蕉
- 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>
使用计数断言以确保列表包含 3 个项目。
await expect(page.getByRole('listitem')).toHaveCount(3);
断言列表中的所有文本
您可以断言定位器以查找列表中的所有文本。
例如，考虑以下 DOM 结构
- 苹果
- 香蕉
- 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>
使用 expect(locator).toHaveText() 以确保列表包含文本 “apple”、“banana” 和 “orange”。
await expect(page
.getByRole('listitem'))
.toHaveText(['apple', 'banana', 'orange']);
获取特定项目
有很多方法可以获取列表中的特定项目。
按文本获取
使用 page.getByText() 方法按其文本内容定位列表中的元素，然后单击它。
例如，考虑以下 DOM 结构
- 苹果
- 香蕉
- 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>
按项目的文本内容定位项目并单击它。
await page.getByText('orange').click();
按文本过滤
使用 locator.filter() 定位列表中的特定项目。
例如，考虑以下 DOM 结构
- 苹果
- 香蕉
- 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>
按 “listitem” 角色定位项目，然后按 “orange” 文本过滤，然后单击它。
await page
.getByRole('listitem')
.filter({ hasText: 'orange' })
.click();
按测试 ID 获取
使用 page.getByTestId() 方法定位列表中的元素。 如果您还没有测试 ID，您可能需要修改 html 并添加测试 ID。
例如，考虑以下 DOM 结构
- 苹果
- 香蕉
- 橙子
<ul>
<li data-testid='apple'>apple</li>
<li data-testid='banana'>banana</li>
<li data-testid='orange'>orange</li>
</ul>
按其 “orange” 测试 ID 定位项目，然后单击它。
await page.getByTestId('orange').click();
按第 n 个项目获取
如果您有一个相同的元素列表，并且区分它们的唯一方法是顺序，则可以使用 locator.first()、locator.last() 或 locator.nth() 从列表中选择特定元素。
const banana = await page.getByRole('listitem').nth(1);
但是，请谨慎使用此方法。 通常，页面可能会更改，并且定位器将指向与您期望的元素完全不同的元素。 相反，尝试提出一个唯一的定位器，该定位器将通过 严格性标准。
链接过滤器
当您有各种相似之处的元素时，可以使用 locator.filter() 方法选择正确的元素。 您还可以链接多个过滤器以缩小选择范围。
例如，考虑以下 DOM 结构
- John
- Mary
- John
- Mary
<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>
要截取包含 “Mary” 和 “Say goodbye” 的行的屏幕截图
const rowLocator = page.getByRole('listitem');
await rowLocator
.filter({ hasText: 'Mary' })
.filter({ has: page.getByRole('button', { name: 'Say goodbye' }) })
.screenshot({ path: 'screenshot.png' });
您现在应该在项目的根目录中有一个 “screenshot.png” 文件。
罕见用例
对列表中的每个元素执行某些操作
迭代元素
for (const row of await page.getByRole('listitem').all())
console.log(await row.textContent());
使用常规 for 循环迭代
const rows = page.getByRole('listitem');
const count = await rows.count();
for (let i = 0; i < count; ++i)
console.log(await rows.nth(i).textContent());
在页面中评估
locator.evaluateAll() 内部的代码在页面中运行，您可以在此处调用任何 DOM api。
const rows = page.getByRole('listitem');
const texts = await rows.evaluateAll(
list => list.map(element => element.textContent));
严格性
定位器是严格的。 这意味着，如果多个元素匹配，则对定位器执行的所有暗示某些目标 DOM 元素的操作都将抛出异常。 例如，如果 DOM 中有多个按钮，则以下调用将抛出异常
如果多个则抛出错误
await page.getByRole('button').click();
另一方面，当您执行多元素操作时，Playwright 可以理解，因此当定位器解析为多个元素时，以下调用可以完美地工作。
多个元素可以正常工作
await page.getByRole('button').count();
您可以通过告诉 Playwright 在多个元素匹配时使用哪个元素来显式选择退出严格性检查，通过 locator.first()、locator.last() 和 locator.nth()。 不建议使用这些方法，因为当您的页面更改时，Playwright 可能会单击您不希望单击的元素。 相反，请遵循上述最佳实践来创建一个唯一标识目标元素的定位器。
更多定位器
对于不太常用的定位器，请查看其他定位器指南。