跳转到主要内容

其他定位器

简介

注意

查看主要定位符指南,了解最常用和推荐的定位符。

除了page.getByRole()page.getByText()等推荐的定位符外,Playwright还支持本指南中描述的各种其他定位符。

CSS 定位符

注意

我们建议优先使用用户可见的定位符,例如文本或可访问角色,而不是使用与实现绑定的CSS,因为当页面更改时,它可能会中断。

Playwright 可以通过 CSS 选择器定位元素。

await page.locator('css=button').click();

Playwright 通过两种方式增强了标准 CSS 选择器

  • CSS 选择器穿透开放的 Shadow DOM。
  • Playwright 添加了自定义伪类,例如 :visible:has-text():has():is():nth-match() 等。

CSS:按文本匹配

Playwright 包含许多 CSS 伪类,用于根据其文本内容匹配元素。

  • article:has-text("Playwright") - :has-text() 匹配任何包含指定文本的元素,可能在子元素或后代元素中。匹配不区分大小写,修剪空白并搜索子字符串。

    例如,article:has-text("Playwright") 匹配 <article><div>Playwright</div></article>

    请注意,:has-text() 应与其他 CSS 指定符一起使用,否则它将匹配所有包含指定文本的元素,包括 <body>

    // Wrong, will match many elements including <body>
    await page.locator(':has-text("Playwright")').click();
    // Correct, only matches the <article> element
    await page.locator('article:has-text("Playwright")').click();
  • #nav-bar :text("Home") - :text() 伪类匹配包含指定文本的最小元素。匹配不区分大小写,修剪空白并搜索子字符串。

    例如,这将在 #nav-bar 元素中查找包含文本“Home”的元素

    await page.locator('#nav-bar :text("Home")').click();
  • #nav-bar :text-is("Home") - :text-is() 伪类匹配具有精确文本的最小元素。精确匹配区分大小写,修剪空白并搜索完整字符串。

    例如,:text-is("Log") 不匹配 <button>Log in</button>,因为 <button> 包含一个文本节点 "Log in",它不等于 "Log"。但是,:text-is("Log") 匹配 <button> Log <span>in</span></button>,因为 <button> 包含一个文本节点 " Log "

    同样,:text-is("Download") 不会匹配 <button>download</button>,因为它区分大小写。

  • #nav-bar :text-matches("reg?ex", "i") - :text-matches() 伪类匹配文本内容与类似 JavaScript 的正则表达式匹配的最小元素。

    例如,:text-matches("Log\s*in", "i") 匹配 <button>Login</button><button>log IN</button>

注意

文本匹配始终规范化空白。例如,它将多个空格转换为一个,将换行符转换为空格,并忽略前导和尾随空白。

注意

类型为 buttonsubmit 的输入元素按其 value 而不是文本内容匹配。例如,:text("Log in") 匹配 <input type=button value="Log in">

CSS:仅匹配可见元素

Playwright 支持 CSS 选择器中的 :visible 伪类。例如,css=button 匹配页面上的所有按钮,而 css=button:visible 仅匹配可见按钮。这对于区分非常相似但在可见性方面不同的元素非常有用。

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

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

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

    await page.locator('button:visible').click();

CSS:包含其他元素的元素

:has() 伪类是一个实验性 CSS 伪类。如果作为参数传递的任何选择器相对于给定元素的 :scope 匹配至少一个元素,则它将返回该元素。

以下代码片段返回包含 <div class=promo><article> 元素的文本内容。

await page.locator('article:has(div.promo)').textContent();

CSS:匹配其中一个条件的元素

逗号分隔的 CSS 选择器列表将匹配所有可以由该列表中某个选择器选择的元素。

// Clicks a <button> that has either a "Log in" or "Sign in" text.
await page.locator('button:has-text("Log in"), button:has-text("Sign in")').click();

:is() 伪类是一个实验性 CSS 伪类,可能有助于指定元素上的一系列额外条件。

CSS:基于布局匹配元素

注意

基于布局的匹配可能会产生意外结果。例如,当布局变化一个像素时,可能会匹配到不同的元素。

有时,当目标元素缺乏独特特征时,很难为其找到一个好的选择器。在这种情况下,使用 Playwright 布局 CSS 伪类可能会有所帮助。这些可以与常规 CSS 结合使用以精确选择多个选项之一。

例如,input:right-of(:text("Password")) 匹配位于文本“Password”右侧的输入字段——当页面有多个难以区分的输入时非常有用。

请注意,布局伪类在附加到其他东西(例如 input)时很有用。如果您单独使用布局伪类,例如 :right-of(:text("Password")),您很可能不会得到您正在寻找的输入,而是文本和目标输入之间的一些空元素。

布局伪类使用边界客户端矩形来计算元素的距离和相对位置。

  • :right-of(div > button) - 匹配位于任何匹配内部选择器的元素右侧的元素,位于任何垂直位置。
  • :left-of(div > button) - 匹配位于任何匹配内部选择器的元素左侧的元素,位于任何垂直位置。
  • :above(div > button) - 匹配位于任何匹配内部选择器的元素上方的元素,位于任何水平位置。
  • :below(div > button) - 匹配位于任何匹配内部选择器的元素下方的元素,位于任何水平位置。
  • :near(div > button) - 匹配靠近(50 CSS 像素以内)任何匹配内部选择器的元素的元素。

请注意,匹配结果按其到锚定元素的距离排序,因此您可以使用 locator.first() 来选择最近的一个。这仅在您有一系列相似元素时有用,其中最近的一个显然是正确的。但是,在其他情况下使用 locator.first() 很可能不会按预期工作 - 它不会定位您正在寻找的元素,而是定位恰好是最近的某个其他元素,例如一个随机的空 <div>,或一个滚动出且当前不可见的元素。

// Fill an input to the right of "Username".
await page.locator('input:right-of(:text("Username"))').fill('value');

// Click a button near the promo card.
await page.locator('button:near(.promo-card)').click();

// Click the radio input in the list closest to the "Label 3".
await page.locator('[type=radio]:left-of(:text("Label 3"))').first().click();

所有布局伪类都支持可选的最大像素距离作为最后一个参数。例如 button:near(:text("Username"), 120) 匹配距离文本“Username”元素最多 120 CSS 像素的按钮。

CSS:从查询结果中选择第 n 个匹配项

注意

通常可以通过某些属性或文本内容来区分元素,这对于页面更改更具弹性。

有时页面包含许多相似的元素,并且很难选择特定的元素。例如

<section> <button>Buy</button> </section>
<article><div> <button>Buy</button> </div></article>
<div><div> <button>Buy</button> </div></div>

在这种情况下,:nth-match(:text("Buy"), 3) 将选择上面代码片段中的第三个按钮。请注意,索引是从 1 开始的。

// Click the third "Buy" button
await page.locator(':nth-match(:text("Buy"), 3)').click();

:nth-match() 也可用于使用 locator.waitFor() 等待指定数量的元素出现。

// Wait until all three buttons are visible
await page.locator(':nth-match(:text("Buy"), 3)').waitFor();
注意

:nth-child() 不同,元素不必是兄弟姐妹,它们可以在页面上的任何位置。在上面的代码片段中,所有三个按钮都匹配 :text("Buy") 选择器,而 :nth-match() 选择第三个按钮。

第 N 个元素定位符

您可以使用 nth= 定位符将查询缩小到第 n 个匹配项,传递一个从零开始的索引。

// Click first button
await page.locator('button').locator('nth=0').click();

// Click last button
await page.locator('button').locator('nth=-1').click();

父元素定位符

当您需要定位某个其他元素的父元素时,大多数情况下您应该通过子定位符locator.filter()进行过滤。例如,考虑以下 DOM 结构

<li><label>Hello</label></li>
<li><label>World</label></li>

如果您想定位带有文本 "Hello" 的标签的父级 <li>,使用 locator.filter() 效果最佳

const child = page.getByText('Hello');
const parent = page.getByRole('listitem').filter({ has: child });

或者,如果您找不到合适的父元素定位器,请使用 xpath=..。请注意,此方法不可靠,因为对 DOM 结构的任何更改都会破坏您的测试。在可能的情况下,优先使用 locator.filter()

const parent = page.getByText('Hello').locator('xpath=..');

React 定位符

注意

React 定位符是实验性的,并带有 _ 前缀。其功能将来可能会发生变化。

React 定位器允许通过其组件名称和属性值查找元素。语法与CSS 属性选择器非常相似,并支持所有 CSS 属性选择器运算符。

在 React 定位符中,组件名称以驼峰式转录。

await page.locator('_react=BookItem').click();

更多示例

  • 组件匹配:_react=BookItem
  • 按组件和精确属性值匹配,区分大小写:_react=BookItem[author = "Steven King"]
  • 仅按属性值匹配,不区分大小写_react=[author = "steven king" i]
  • 按组件和真实属性值匹配:_react=MyButton[enabled]
  • 按组件和布尔值匹配:_react=MyButton[enabled = false]
  • 按属性值子字符串匹配:_react=[author *= "King"]
  • 按组件和多个属性匹配:_react=BookItem[author *= "king" i][year = 1990]
  • 嵌套属性值匹配:_react=[some.nested.value = 12]
  • 按组件和属性值前缀匹配:_react=BookItem[author ^= "Steven"]
  • 按组件和属性值后缀匹配:_react=BookItem[author $= "Steven"]
  • 按组件和匹配:_react=BookItem[key = '2']
  • 按属性值正则表达式匹配:_react=[author = /Steven(\\s+King)?/i]

要查找树中的 React 元素名称,请使用React DevTools

注意

React 定位符支持 React 15 及更高版本。

注意

React 定位器以及React DevTools仅适用于未缩小的应用程序构建。

Vue 定位符

注意

Vue 定位符是实验性的,并带有 _ 前缀。其功能将来可能会发生变化。

Vue 定位器允许通过其组件名称和属性值查找元素。语法与CSS 属性选择器非常相似,并支持所有 CSS 属性选择器运算符。

在 Vue 定位符中,组件名称以短横线命名法 (kebab-case) 转录。

await page.locator('_vue=book-item').click();

更多示例

  • 组件匹配:_vue=book-item
  • 按组件和精确属性值匹配,区分大小写:_vue=book-item[author = "Steven King"]
  • 仅按属性值匹配,不区分大小写_vue=[author = "steven king" i]
  • 按组件和真实属性值匹配:_vue=my-button[enabled]
  • 按组件和布尔值匹配:_vue=my-button[enabled = false]
  • 按属性值子字符串匹配:_vue=[author *= "King"]
  • 按组件和多个属性匹配:_vue=book-item[author *= "king" i][year = 1990]
  • 嵌套属性值匹配:_vue=[some.nested.value = 12]
  • 按组件和属性值前缀匹配:_vue=book-item[author ^= "Steven"]
  • 按组件和属性值后缀匹配:_vue=book-item[author $= "Steven"]
  • 按属性值正则表达式匹配:_vue=[author = /Steven(\\s+King)?/i]

要查找树中的 Vue 元素名称,请使用Vue DevTools

注意

Vue 定位符支持 Vue2 及更高版本。

注意

Vue 定位器以及Vue DevTools仅适用于未缩小的应用程序构建。

XPath 定位符

警告

我们建议优先使用用户可见的定位符,例如文本或可访问角色,而不是使用与实现绑定的 XPath,因为当页面更改时,它很容易中断。

XPath 定位符等同于调用 Document.evaluate

await page.locator('xpath=//button').click();
注意

任何以 //.. 开头的选择器字符串都被认为是 xpath 选择器。例如,Playwright 将 '//html/body' 转换为 'xpath=//html/body'

注意

XPath 不会穿透 Shadow DOM。

XPath 联合

管道运算符(|)可用于在 XPath 中指定多个选择器。它将匹配所有可以通过该列表中某个选择器选择的元素。

// Waits for either confirmation dialog or load spinner.
await page.locator(
`//span[contains(@class, 'spinner__loading')]|//div[@id='confirmation']`
).waitFor();

标签到表单控件的重定向

警告

我们建议通过标签文本进行定位,而不是依赖标签到控件的重定向。

Playwright 中的目标输入操作会自动区分标签和控件,因此您可以将标签作为目标,对关联的控件执行操作。

例如,考虑以下 DOM 结构:<label for="password">Password:</label><input id="password" type="password">。您可以使用 page.getByText() 以其“Password”文本为目标。但是,以下操作将在输入上执行,而不是在标签上执行

// Fill the input by targeting the label.
await page.getByText('Password').fill('secret');

但是,其他方法将以标签本身为目标,例如 expect(locator).toHaveText() 将断言标签的文本内容,而不是输入字段。

// Fill the input by targeting the label.
await expect(page.locator('label')).toHaveText('Password');

传统文本定位符

警告

我们建议使用现代的文本定位符

传统文本定位符匹配包含传递文本的元素。

await page.locator('text=Log in').click();

传统文本定位符有几种变体

  • text=Log in - 默认匹配不区分大小写,修剪空白并搜索子字符串。例如,text=Log 匹配 <button>Log in</button>

    await page.locator('text=Log in').click();
  • text="Log in" - 文本内容可以用单引号或双引号括起来,以搜索修剪空白后具有精确内容的文本节点。

    例如,text="Log" 不匹配 <button>Log in</button>,因为 <button> 包含一个文本节点 "Log in",它不等于 "Log"。但是,text="Log" 匹配 <button> Log <span>in</span></button>,因为 <button> 包含一个文本节点 " Log "。这种精确模式意味着区分大小写的匹配,因此 text="Download" 不会匹配 <button>download</button>

    带引号的主体遵循常规的转义规则,例如,在双引号字符串中使用 \" 转义双引号:text="foo\"bar"

    await page.locator('text="Log in"').click();
  • /Log\s*in/i - 主体可以是括在 / 符号中的类似 JavaScript 的正则表达式。例如,text=/Log\s*in/i 匹配 <button>Login</button><button>log IN</button>

    await page.locator('text=/Log\\s*in/i').click();
注意

以引号("')开头和结尾的字符串选择器被认为是传统文本定位符。例如,"Log in" 在内部转换为 text="Log in"

注意

匹配总是规范化空白。例如,它将多个空格转换为一个,将换行符转换为空格,并忽略前导和尾随空白。

注意

类型为 buttonsubmit 的输入元素按其 value 而不是文本内容匹配。例如,text=Log in 匹配 <input type=button value="Log in">

id、data-testid、data-test-id、data-test 选择器

警告

我们建议通过测试 ID 定位

Playwright 支持使用特定属性选择元素的简写形式。目前,仅支持以下属性

  • id
  • data-testid
  • data-test-id
  • data-test
// Fill an input with the id "username"
await page.locator('id=username').fill('value');

// Click an element with data-test-id "submit"
await page.locator('data-test-id=submit').click();
注意

属性选择器不是 CSS 选择器,因此不支持任何 CSS 特定的东西,例如 :enabled。有关更多功能,请使用适当的 css 选择器,例如 css=[data-test="login"]:enabled

链式选择器

警告

我们建议链接定位符

定义为 engine=body 或短格式的选择器可以使用 >> 标记组合,例如 selector1 >> selector2 >> selectors3。当选择器链接时,下一个选择器相对于前一个选择器的结果进行查询。

例如,

css=article >> css=.bar > .baz >> css=span[attr=value]

等价于

document
.querySelector('article')
.querySelector('.bar > .baz')
.querySelector('span[attr=value]');

如果选择器需要在主体中包含 >>,则应在字符串内转义,以免与链接分隔符混淆,例如 text="some >> text"

中间匹配项

警告

我们建议通过另一个定位符过滤以定位包含其他元素的元素。

默认情况下,链式选择器解析为最后一个选择器查询到的元素。选择器可以以 * 为前缀,以捕获由中间选择器查询到的元素。

例如,css=article >> text=Hello 捕获带有文本 Hello 的元素,而 *css=article >> text=Hello(注意 *)捕获包含带有文本 Hello 的元素的 article 元素。