跳转到主要内容

定位器

简介

定位器是 Playwright 自动等待和重试能力的核心。简而言之,定位器表示在任何时候查找页面上一个或多个元素的方法。

快速指南

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

page.get_by_label("User Name").fill("John")

page.get_by_label("Password").fill("secret-password")

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

expect(page.get_by_text("Welcome, John!")).to_be_visible()

定位元素

Playwright 带有多个内置定位器。为了使测试更具弹性,我们建议优先使用用户可见的属性和显式约定,例如 page.get_by_role()

例如,考虑以下 DOM 结构。

https://:3000
<button>Sign in</button>

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

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

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

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

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

locator.hover()
locator.click()

请注意,所有创建定位器的方法,例如page.get_by_label(),也适用于LocatorFrameLocator类,因此您可以将它们链式调用并迭代地缩小定位器范围。

locator = page.frame_locator("my-frame").get_by_role("button", name="Sign in")

locator.click()

按角色定位

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

例如,考虑以下 DOM 结构。

https://:3000

注册

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

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

expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

page.get_by_role("checkbox", name="Subscribe").check()

page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click()

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

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

何时使用角色定位器

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

按标签定位

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

例如,考虑以下 DOM 结构。

https://:3000
<label>Password <input type="password" /></label>

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

page.get_by_label("Password").fill("secret")
何时使用标签定位器

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

按占位符定位

输入框可能有一个占位符属性,用于提示用户应该输入什么值。您可以使用page.get_by_placeholder()来定位这样的输入框。

例如,考虑以下 DOM 结构。

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

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

page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")
何时使用占位符定位器

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

按文本定位

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

例如,考虑以下 DOM 结构。

https://:3000
欢迎,约翰
<span>Welcome, John</span>

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

expect(page.get_by_text("Welcome, John")).to_be_visible()

设置精确匹配

expect(page.get_by_text("Welcome, John", exact=True)).to_be_visible()

使用正则表达式匹配

expect(page.get_by_text(re.compile("welcome, john", re.IGNORECASE))).to_be_visible()
注意

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

何时使用文本定位器

我们建议使用文本定位器来查找非交互式元素,如 divspanp 等。对于交互式元素,如 buttonainput 等,请使用角色定位器

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

按 alt 文本定位

所有图像都应该有一个描述图像的 alt 属性。您可以使用 page.get_by_alt_text() 根据替代文本定位图像。

例如,考虑以下 DOM 结构。

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

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

page.get_by_alt_text("playwright logo").click()
何时使用 alt 定位器

当您的元素支持 alt 文本时(如 imgarea 元素),请使用此定位器。

按 title 定位

使用 page.get_by_title() 查找具有匹配 title 属性的元素。

例如,考虑以下 DOM 结构。

https://:3000
25 个问题
<span title='Issues count'>25 issues</span>

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

expect(page.get_by_title("Issues count")).to_have_text("25 issues")
何时使用 title 定位器

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

按 test id 定位

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

例如,考虑以下 DOM 结构。

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

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

page.get_by_test_id("directions").click()
何时使用测试 ID 定位器

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

设置自定义 test id 属性

默认情况下,page.get_by_test_id() 将根据 data-testid 属性定位元素,但您可以在测试配置中或通过调用 selectors.set_test_id_attribute() 进行配置。

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

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

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

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

然后像通常一样定位元素

page.get_by_test_id("directions").click()

按 CSS 或 XPath 定位

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

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 中的元素。例外情况是

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

page.get_by_text("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", has_text="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> 包含文本“详细信息”

expect(page.locator("x-details")).to_contain_text("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() 方法按文本进行过滤。它会在元素内部(可能在后代元素中)搜索特定的字符串,不区分大小写。您也可以传递正则表达式。

page.get_by_role("listitem").filter(has_text="Product 2").get_by_role(
"button", name="Add to cart"
).click()

使用正则表达式

page.get_by_role("listitem").filter(has_text=re.compile("Product 2")).get_by_role(
"button", name="Add to cart"
).click()

按不包含文本过滤

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

# 5 in-stock items
expect(page.get_by_role("listitem").filter(has_not_text="Out of stock")).to_have_count(5)

按子/后代过滤

定位器支持一个选项,只选择包含或不包含与另一个定位器匹配的后代元素的元素。因此,您可以根据任何其他定位器进行筛选,例如 locator.get_by_role()locator.get_by_test_id()locator.get_by_text() 等。

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>
page.get_by_role("listitem").filter(
has=page.get_by_role("heading", name="Product 2")
).get_by_role("button", name="Add to cart").click()

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

expect(
page.get_by_role("listitem").filter(
has=page.get_by_role("heading", name="Product 2")
)
).to_have_count(1)

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

# ✖ WRONG
expect(
page.get_by_role("listitem").filter(
has=page.get_by_role("list").get_by_role("heading", name="Product 2")
)
).to_have_count(1)

按不包含子/后代过滤

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

expect(
page.get_by_role("listitem").filter(
has_not=page.get_by_role("heading", name="Product 2")
)
).to_have_count(1)

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

定位器操作符

在定位器内部匹配

您可以链式调用创建定位器的方法,例如 page.get_by_text()locator.get_by_role(),以将搜索范围缩小到页面的特定部分。

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

product = page.get_by_role("listitem").filter(has_text="Product 2")

product.get_by_role("button", name="Add to cart").click()

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

save_button = page.get_by_role("button", name="Save")
# ...
dialog = page.get_by_test_id("settings-dialog")
dialog.locator(save_button).click()

同时匹配两个定位器

方法 locator.and_() 通过匹配附加定位器来缩小现有定位器。例如,您可以结合使用 page.get_by_role()page.get_by_title() 来同时按角色和标题进行匹配。

button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))

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

如果您想定位两个或多个元素中的一个,并且您不知道会是哪一个,请使用 locator.or_() 创建一个匹配其中任何一个或所有备选元素的定位器。

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

注意

如果“新邮件”按钮和安全对话框同时出现在屏幕上,“或”定位器将匹配它们两者,可能会抛出“严格模式违规”错误。在这种情况下,您可以使用locator.first来仅匹配其中一个。

new_email = page.get_by_role("button", name="New")
dialog = page.get_by_text("Confirm security settings")
expect(new_email.or_(dialog).first).to_be_visible()
if (dialog.is_visible()):
page.get_by_role("button", name="Dismiss").click()
new_email.click()

只匹配可见元素

注意

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

考虑一个页面上有两个按钮,第一个不可见,第二个可见

<button style='display: none'>Invisible</button>
<button>Visible</button>
  • 这将找到两个按钮并抛出严格性违规错误

    page.locator("button").click()
  • 这将只找到第二个按钮,因为它可见,然后点击它。

    page.locator("button").filter(visible=True).click()

列表

统计列表中的项目数

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

例如,考虑以下 DOM 结构

https://:3000
  • 苹果
  • 香蕉
  • 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>

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

expect(page.get_by_role("listitem")).to_have_count(3)

断言列表中所有文本

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

例如,考虑以下 DOM 结构

https://:3000
  • 苹果
  • 香蕉
  • 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>

使用 expect(locator).to_have_text() 确保列表包含文本 "apple"、"banana" 和 "orange"。

expect(page.get_by_role("listitem")).to_have_text(["apple", "banana", "orange"])

获取特定项目

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

按文本获取

使用 page.get_by_text() 方法通过其文本内容在列表中定位元素,然后单击它。

例如,考虑以下 DOM 结构

https://:3000
  • 苹果
  • 香蕉
  • 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>

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

page.get_by_text("orange").click()

按文本过滤

使用 locator.filter() 定位列表中的特定项目。

例如,考虑以下 DOM 结构

https://:3000
  • 苹果
  • 香蕉
  • 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>

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

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

按 test id 获取

使用 page.get_by_test_id() 方法定位列表中的元素。如果尚未有测试 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”定位项目,然后点击它。

page.get_by_test_id("orange").click()

按第 n 项获取

如果您有一个相同元素的列表,并且区分它们元素的唯一方法是顺序,则可以使用 locator.firstlocator.lastlocator.nth() 从列表中选择特定元素。

banana = page.get_by_role("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>

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

row_locator = page.get_by_role("listitem")

row_locator.filter(has_text="Mary").filter(
has=page.get_by_role("button", name="Say goodbye")
).screenshot(path="screenshot.png")

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

不常见的用例

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

迭代元素

for row in page.get_by_role("listitem").all():
print(row.text_content())

使用常规 for 循环迭代

rows = page.get_by_role("listitem")
count = rows.count()
for i in range(count):
print(rows.nth(i).text_content())

在页面中评估

locator.evaluate_all() 中的代码在页面中运行,您可以在其中调用任何 DOM API。

rows = page.get_by_role("listitem")
texts = rows.evaluate_all("list => list.map(element => element.textContent)")

严格性

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

如果多于一个则抛出错误

page.get_by_role("button").click()

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

对多个元素正常工作

page.get_by_role("button").count()

您可以通过 locator.firstlocator.lastlocator.nth() 明确选择退出严格性检查,告诉 Playwright 在多个元素匹配时使用哪个元素。这些方法不推荐使用,因为当您的页面更改时,Playwright 可能会单击您不希望的元素。相反,请遵循上述最佳实践,创建一个唯一标识目标元素的定位器。

更多定位器

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