其他定位器
简介
查看主要的定位器指南以获取最常用和推荐的定位器。
除了Page.GetByRole()和Page.GetByText()等推荐定位器外，Playwright还支持本指南中描述的各种其他定位器。
CSS 定位符
我们建议优先使用用户可见的定位器，例如文本或可访问角色，而不是使用与实现绑定并在页面更改时可能中断的CSS。
Playwright 可以通过 CSS 选择器定位元素。
await page.Locator("css=button").ClickAsync();
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\")").ClickAsync();
// Correct, only matches the <article> element
await page.Locator("article:has-text(\"Playwright\")").ClickAsync(); -
#nav-bar :text("Home")-:text()伪类匹配包含指定文本的最小元素。匹配不区分大小写，修剪空白并搜索子字符串。例如，这将在
#nav-bar元素中查找包含文本“Home”的元素await page.Locator("#nav-bar :text('Home')").ClickAsync(); -
#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>。
文本匹配始终规范化空白。例如，它将多个空格转换为一个，将换行符转换为空格，并忽略前导和尾随空白。
类型为 button 和 submit 的输入元素按其 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").ClickAsync(); -
这将只找到第二个按钮，因为它可见，然后点击它。
await page.Locator("button:visible").ClickAsync();
CSS：包含其他元素的元素
:has()伪类是一个实验性CSS伪类。如果作为参数传递的任何选择器相对于给定元素的:scope匹配至少一个元素，则返回该元素。
以下代码片段返回包含 <div class=promo> 的 <article> 元素的文本内容。
await page.Locator("article:has(div.promo)").TextContentAsync();
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\")").ClickAsync();
: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\"))").FillAsync("value");
// Click a button near the promo card.
await page.Locator("button:near(.promo-card)").ClickAsync();
// Click the radio input in the list closest to the "Label 3".
await page.Locator("[type=radio]:left-of(:text(\"Label 3\"))").First.ClickAsync();
所有布局伪类都支持可选的最大像素距离作为最后一个参数。例如 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)").ClickAsync();
:nth-match()也常用于使用Locator.WaitForAsync()等待指定数量的元素出现。
// Wait until all three buttons are visible
await page.Locator(":nth-match(:text('Buy'), 3)").WaitForAsync();
与:nth-child()不同，元素不必是兄弟元素，它们可以位于页面的任何位置。在上面的代码片段中，所有三个按钮都匹配:text("Buy")选择器，而:nth-match()选择第三个按钮。
第 N 个元素定位符
您可以使用 nth= 定位符将查询缩小到第 n 个匹配项，传递一个从零开始的索引。
// Click first button
await page.Locator("button").Locator("nth=0").ClickAsync();
// Click last button
await page.Locator("button").Locator("nth=-1").ClickAsync();
父元素定位符
当您需要定位某个元素的父元素时，大多数情况下您应该通过子定位器来Locator.Filter()。例如，考虑以下DOM结构
<li><label>Hello</label></li>
<li><label>World</label></li>
如果您想定位文本为"Hello"的标签的父级<li>，使用Locator.Filter()效果最好
var child = page.GetByText("Hello");
var parent = page.GetByRole(AriaRole.Listitem).Filter(new () { Has = child });
或者，如果您找不到适合父元素的定位器，请使用xpath=..。请注意，这种方法不太可靠，因为对DOM结构的任何更改都会破坏您的测试。尽可能优先使用Locator.Filter()。
var parent = page.GetByText("Hello").Locator("xpath=..");
React 定位符
React 定位符是实验性的，并带有 _ 前缀。其功能将来可能会发生变化。
React 定位器允许通过其组件名称和属性值查找元素。语法与CSS 属性选择器非常相似，并支持所有 CSS 属性选择器运算符。
在 React 定位符中，组件名称以驼峰式转录。
await page.Locator("_react=BookItem").ClickAsync();
更多示例
- 按组件匹配：
_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").ClickAsync();
更多示例
- 按组件匹配：
_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").ClickAsync();
任何以 // 或 .. 开头的选择器字符串都被认为是 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']").WaitForAsync();
标签到表单控件的重定向
我们建议通过标签文本定位，而不是依赖标签到控件的重定向。
Playwright 中的目标输入操作会自动区分标签和控件，因此您可以将标签作为目标，对关联的控件执行操作。
例如，考虑以下 DOM 结构：<label for="password">Password:</label><input id="password" type="password">。您可以使用Page.GetByText()通过其“Password”文本来定位该标签。但是，以下操作将在输入框而不是标签上执行
- Locator.ClickAsync() 将点击标签并自动聚焦输入字段；
- Locator.FillAsync() 将填充输入字段；
- Locator.InputValueAsync() 将返回输入字段的值；
- Locator.SelectTextAsync() 将选择输入字段中的文本；
- Locator.SetInputFilesAsync() 将为
type=file的输入字段设置文件； - Locator.SelectOptionAsync() 将从选择框中选择一个选项。
// Fill the input by targeting the label.
await page.GetByText("Password").FillAsync("secret");
但是，其他方法将定位标签本身，例如Expect(Locator).ToHaveTextAsync()将断言标签的文本内容，而不是输入字段。
// Fill the input by targeting the label.
await Expect(Page.Locator("label")).ToHaveTextAsync("Password");
传统文本定位符
我们推荐使用现代的文本定位器。
传统文本定位符匹配包含传递文本的元素。
await page.Locator("text=Log in").ClickAsync();
传统文本定位符有几种变体
-
text=Log in- 默认匹配不区分大小写，修剪空白并搜索子字符串。例如，text=Log匹配<button>Log in</button>。await page.Locator("text=Log in").ClickAsync(); -
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'").ClickAsync(); -
/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").ClickAsync();
以引号（" 或 '）开头和结尾的字符串选择器被认为是传统文本定位符。例如，"Log in" 在内部转换为 text="Log in"。
匹配总是规范化空白。例如，它将多个空格转换为一个，将换行符转换为空格，并忽略前导和尾随空白。
类型为 button 和 submit 的输入元素按其 value 而不是文本内容匹配。例如，text=Log in 匹配 <input type=button value="Log in">。
id, data-testid, data-test-id, data-test 选择器
我们建议按测试 ID 定位。
Playwright 支持使用特定属性选择元素的简写形式。目前，仅支持以下属性
iddata-testiddata-test-iddata-test
// Fill an input with the id "username"
await page.Locator("id=username").FillAsync("value");
// Click an element with data-test-id "submit"
await page.Locator("data-test-id=submit").ClickAsync();
属性选择器不是 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元素。