Locators

Locators是Playwright自动等待和重试能力的核心部分。简而言之，Locators代表了一种随时在页面上查找元素的方法。

快速指南

这些是推荐的内置定位器。

• page.getbyrole()通过显式和隐式可访问性属性进行定位。
• page.get_by_text()用于按文本内容定位。
• page.get_by_label()通过关联标签的文本定位表单控件。
• page.get_by_placeholder()通过占位符定位输入。
• page.getby_alt_text()通过文本替代来定位元素，通常是图像。
• page.get_by_title()通过元素的title属性定位元素。
• page.getbytestid()用于根据元素的data-testid属性（可以配置其他属性）定位元素。

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结构：

通过名为“登录”的按钮的角色定位元素。

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()，也可以在Locator和FrameLocator类上使用，因此可以将它们链接起来并迭代地缩小定位器的范围。

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

locator.click()

按角色定位

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

考虑以下DOM结构:

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

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

角色定位器包括 buttons, checkboxes, headings, links, lists, tables等，并遵循W3C对ARIA role, ARIA attributes和accessible name的规范。请注意，许多html元素（如）都有一个隐式定义的角色，该角色由角色定位器识别。

按标签定位

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

例如，考虑以下DOM结构。可以通过标签文本定位输入框，然后填充它：

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

按占位符定位

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

例如，考虑以下DOM结构。可以通过占位符文本定位输入框，然后填充它：

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

按文本定位

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

例如，考虑以下DOM结构。可以通过元素包含的文本定位它：

• 精确匹配：

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

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

按替代文本定位

所有图像都应有描述图像的alt属性。可以使用page.get_by_alt_text()基于文本替代来定位图像。

例如，考虑以下DOM结构。可以通过文本替代定位图像，然后点击它：

page.get_by_alt_text("playwright logo").click()

按标题定位

使用与标题属性匹配的page.get_by_title()来定位元素。

例如，考虑以下DOM结构。可以通过标题文本定位它，然后检查问题数量：

expect(page.get_by_title("Issues count")).to_have_text("25 issues")

按测试ID定位

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

例如，考虑以下DOM结构。可以通过其测试ID定位元素：

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

设置自定义测试ID属性

默认情况下，page.get_by_test_id()将基于data-testid属性定位元素，但您可以在测试配置中或通过调用selectors.set_test_id_attribute()进行配置。将测试ID设置为用于测试的自定义数据属性。

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

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

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

按CSS或XPath定位

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

XPath和CSS选择器可以与DOM结构或实现相关联。当DOM结构发生变化时，这些选择器可能会失效。示例：

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

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

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