跳到主要内容

Locator

定位器（Locator）是Playwright自动等待和重试功能的核心部分。简而言之，定位器代表了一种在任何时刻在页面上查找元素的方式。可以使用Page.locator()方法创建定位器。

详细了解定位器。

方法​

all​

添加于：v1.29 locator.all

当定位器指向元素列表时，此方法返回一个定位器数组，分别指向各自的元素。

备注

Locator.all() 不会等待元素匹配定位器，而是立即返回页面中当前存在的任何内容。

当元素列表动态变化时，Locator.all() 将产生不可预测且不稳定的结果。

当元素列表稳定但动态加载时，在调用 Locator.all() 之前，等待完整列表加载完成。

用法

for (Locator li : page.getByRole("listitem").all())
  li.click();

返回值

allInnerTexts​

添加于：v1.14 locator.allInnerTexts

返回所有匹配节点的 node.innerText 值数组。

断言文本

如果需要在页面上断言文本，建议使用 assertThat(locator).hasText() 并搭配 setUseInnerText 选项，以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法​

String[] texts = page.getByRole(AriaRole.LINK).allInnerTexts();

返回值​

allTextContents​

新增于：v1.14 locator.allTextContents

返回所有匹配节点的 node.textContent 值组成的数组。

断言文本

如果需要在页面上断言文本，建议使用 assertThat(locator).hasText() 以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法​

String[] texts = page.getByRole(AriaRole.LINK).allTextContents();

返回值​

and​

新增于：v1.34 locator.and

创建一个定位器，该定位器匹配当前定位器和传入的定位器。

用法​

以下示例查找具有特定标题的按钮。

Locator button = page.getByRole(AriaRole.BUTTON).and(page.getByTitle("Subscribe"));

参数​

  • locator Locator# 要匹配的其他定位器。

返回值​

ariaSnapshot​

新增于：v1.49 locator.ariaSnapshot

捕获给定元素的 ARIA 快照。详细了解 ARIA 快照 以及对应的断言 assertThat(locator).matchesAriaSnapshot()。

用法

page.getByRole(AriaRole.LINK).ariaSnapshot();

参数

返回值

详细信息​

此方法捕获给定元素的 ARIA 快照。快照是一个字符串，代表该元素及其子元素的状态。该快照可用于在测试中断言元素的状态，或与未来的状态进行比较。

ARIA 快照使用 YAML 标记语言表示：

  • 对象的键是元素的角色和可选的可访问名称。
  • 值可以是文本内容或子元素数组。
  • 通用静态文本可以用 text 键表示。

以下是 HTML 标记和相应的 ARIA 快照：

<ul aria-label="Links">
  <li><a href="/">Home</a></li>
  <li><a href="/about">About</a></li>
<ul>
- list "Links":
  - listitem:
    - link "Home"
  - listitem:
    - link "About"

blur​

新增于：v1.28 locator.blur

在元素上调用 blur。

用法​

Locator.blur();
Locator.blur(options);

参数​

返回值​

boundingBox​

添加于：v1.14 locator.boundingBox

此方法返回与定位器匹配的元素的边界框，如果元素不可见，则返回 null。边界框是相对于主框架视口计算的，通常与浏览器窗口相同。

用法

BoundingBox box = page.getByRole(AriaRole.BUTTON).boundingBox();
page.mouse().click(box.x + box.width / 2, box.y + box.height / 2);

参数

返回值

  • null | BoundingBox#

    • x double

      元素的 x 坐标（以像素为单位）。

    • y double

      元素的 y 坐标（以像素为单位）。

    • width double

      元素的宽度（以像素为单位）。

    • height double

      元素的高度（以像素为单位）。

详细信息

与 Element.getBoundingClientRect 类似，滚动会影响返回的边界框。这意味着 x 和 / 或 y 可能为负数。

与 Element.getBoundingClientRect 不同，来自子框架的元素返回相对于主框架的边界框。

假设页面是静态的，使用边界框坐标来执行输入是安全的。例如，以下代码片段应点击元素的中心。

check​

添加于：v1.14 locator.check

确保复选框或单选按钮元素已被选中。

用法

page.getByRole(AriaRole.CHECKBOX).check();

参数

  • options Locator.CheckOptions（可选）

    • setForce [布尔值]（可选）#

      是否绕过可操作性检查。默认为 false。

    • setNoWaitAfter [布尔值]（可选）#

      已弃用

      此选项无效。

      此选项无效。

    • setPosition Position（可选）#

      • setX [双精度浮点数]

      • setY [双精度浮点数]

      相对于元素内边距框左上角使用的一个点。如果未指定，则使用元素的某个可见点。

    • setTimeout [双精度浮点数]（可选）#

      最大时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

    • setTrial [布尔值]（可选）#

      设置此参数后，此方法仅执行可操作性检查并跳过操作。默认为 false。这在等待元素准备好进行操作但不执行操作时很有用。

返回值

详细信息

执行以下步骤：

  1. 确保该元素是复选框或单选输入框。否则，此方法将抛出异常。如果该元素已经被选中，此方法将立即返回。
  2. 等待对该元素的可操作性检查，除非设置了setForce选项。
  3. 如有需要，将元素滚动到可见区域。
  4. 使用Page.mouse()点击元素中心。
  5. 确保该元素现在已被选中。否则，此方法将抛出异常。

如果在操作过程中的任何时刻，该元素从 DOM 中分离，此方法将抛出异常。

如果在指定的setTimeout时间内，所有步骤组合未完成，此方法将抛出TimeoutError。传递零超时将禁用此功能。

clear​

新增于：v1.28 locator.clear

清空输入字段。

用法

page.getByRole(AriaRole.TEXTBOX).clear();

参数​

  • options Locator.ClearOptions（可选）

    • setForce [布尔值]（可选）#

      是否绕过可操作性检查。默认为 false。

    • setNoWaitAfter [布尔值]（可选）#

      已弃用

      此选项无效。

      此选项无效。

    • setTimeout [双精度浮点数]（可选）#

      最大时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

返回值​

详细信息​

此方法等待可操作性检查，聚焦元素，清除其内容，并在清除后触发 input 事件。

如果目标元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法将抛出错误。但是，如果该元素位于具有关联 control 的 <label> 元素内，则将改为清除该控件。

click​

添加于：v1.14 locator.click

点击一个元素。

用法

点击一个按钮：

page.getByRole(AriaRole.BUTTON).click();

在画布上的特定位置按住 Shift 键并右键单击：

page.locator("canvas").click(new Locator.ClickOptions()
  .setButton(MouseButton.RIGHT)
  .setModifiers(Arrays.asList(KeyboardModifier.SHIFT))
  .setPosition(23, 32));

参数

  • options Locator.ClickOptions（可选）

    • setButton enum MouseButton { LEFT, RIGHT, MIDDLE }（可选）#

      默认值为 left。

    • setClickCount int（可选）#

      默认值为 1。参见 UIEvent.detail。

    • setDelay double（可选）#

      mousedown 和 mouseup 之间等待的时间（毫秒）。默认值为 0。

    • setForce boolean（可选）#

      是否绕过 可操作性 检查。默认值为 false。

    • setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }>（可选）#

      要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前的修饰键。如果未指定，则使用当前按下的修饰键。“ControlOrMeta” 在 Windows 和 Linux 上解析为 “Control”，在 macOS 上解析为 “Meta”。

    • setNoWaitAfter boolean（可选）#

      已弃用

      此选项将来默认值将为 true。

      启动导航的操作会等待这些导航发生以及页面开始加载。你可以通过设置此标志选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认值为 false。

    • setPosition Position（可选）#

      相对于元素内边距框左上角使用的一个点。如果未指定，则使用元素的某个可见点。

    • setTimeout double（可选）#

      最大时间（毫秒）。默认值为 30000（30 秒）。传递 0 以禁用超时。默认值可以通过使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

    • setTrial boolean（可选）#

      设置后，此方法仅执行 可操作性 检查并跳过操作。默认值为 false。这对于等待元素准备好进行操作而不实际执行操作很有用。请注意，无论 trial 如何，都会按下键盘 modifiers，以便测试仅在按下这些键时才可见的元素。

返回值

详细信息

此方法通过执行以下步骤点击元素：

  1. 等待对元素进行可操作性检查，除非设置了setForce选项。
  2. 如有需要，将元素滚动到可见区域。
  3. 使用Page.mouse()在元素中心或指定的setPosition处点击。
  4. 等待发起的导航成功或失败，除非设置了setNoWaitAfter选项。

如果在操作过程中的任何时刻元素从 DOM 中分离，此方法将抛出异常。

如果在指定的setTimeout时间内所有步骤未完成，此方法将抛出TimeoutError。传递零超时将禁用此功能。

contentFrame​

新增于：v1.43 locator.contentFrame

返回一个FrameLocator对象，指向与此定位器相同的 iframe。

当你在某个地方获得了一个Locator对象，之后想要与框架内的内容进行交互时，此方法很有用。

对于反向操作，请使用FrameLocator.owner()。

用法

Locator locator = page.locator("iframe[name=\"embedded\"]");
// ...
FrameLocator frameLocator = locator.contentFrame();
frameLocator.getByRole(AriaRole.BUTTON).click();

返回值

count​

新增于：v1.14 locator.count

返回与定位器匹配的元素数量。

断言数量

如果需要断言页面上的元素数量，建议使用 assertThat(locator).hasCount() 以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法

int count = page.getByRole(AriaRole.LISTITEM).count();

返回值

dblclick​

新增于：v1.14 locator.dblclick

双击一个元素。

用法

Locator.dblclick();
Locator.dblclick(options);

参数

  • options Locator.DblclickOptions（可选）

    • setButton enum MouseButton { LEFT, RIGHT, MIDDLE }（可选）#

      默认值为 left。

    • setDelay double（可选）#

      mousedown 和 mouseup 之间等待的时间，单位为毫秒。默认值为 0。

    • setForce boolean（可选）#

      是否绕过可操作性检查。默认值为 false。

    • setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }>（可选）#

      要按下的修饰键。确保在操作过程中只按下这些修饰键，然后恢复当前的修饰键状态。如果未指定，则使用当前按下的修饰键。“ControlOrMeta” 在 Windows 和 Linux 上解析为 “Control”，在 macOS 上解析为 “Meta”。

    • setNoWaitAfter boolean（可选）#

      已弃用

      此选项无效。

      此选项无效。

    • setPosition Position（可选）#

      相对于元素内边距框左上角使用的一个点。如果未指定，则使用元素的某个可见点。

    • setTimeout double（可选）#

      最大时间，单位为毫秒。默认值为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

    • setTrial boolean（可选）#

      设置此参数时，此方法仅执行可操作性检查并跳过操作。默认值为 false。这在等待元素准备好执行操作但不实际执行操作时很有用。请注意，无论 trial 设置如何，都会按下键盘 modifiers，以便测试仅在按下这些键时才可见的元素。

返回值

详细信息

此方法通过执行以下步骤双击元素：

  1. 等待对元素进行可操作性检查，除非设置了setForce选项。
  2. 如有需要，将元素滚动到可见区域。
  3. 使用Page.mouse()在元素中心或指定的setPosition处双击。

如果在操作过程中元素在任何时刻从 DOM 中分离，此方法将抛出异常。

如果在指定的setTimeout内所有步骤组合未完成，此方法将抛出TimeoutError。传递零超时将禁用此功能。

备注

element.dblclick() 会派发两个 click 事件和一个 dblclick 事件。

dispatchEvent​

新增于：v1.14 locator.dispatchEvent

以编程方式在匹配的元素上派发事件。

用法

locator.dispatchEvent("click");

参数

返回值

详细信息​

上述代码片段在元素上派发 click 事件。无论元素的可见性状态如何，都会派发 click 事件。这等效于调用 element.click()。

在底层，它会根据给定的 type 创建一个事件实例，使用 eventInit 属性对其进行初始化，然后在元素上派发该事件。事件默认是 composed、cancelable 且会冒泡的。

由于 eventInit 是特定于事件的，请参考以下事件文档以获取初始属性列表：

如果你希望将实时对象传递到事件中，也可以指定 JSHandle 作为属性值：

JSHandle dataTransfer = page.evaluateHandle("() => new DataTransfer()");
Map<String, Object> arg = new HashMap<>();
arg.put("dataTransfer", dataTransfer);
locator.dispatchEvent("dragstart", arg);

dragTo​

添加于：v1.18 locator.dragTo

将源元素拖向目标元素并放下。

用法

Locator source = page.locator("#source");
Locator target = page.locator("#target");

source.dragTo(target);
// 或者指定相对于元素左上角的精确位置：
source.dragTo(target, new Locator.DragToOptions()
  .setSourcePosition(34, 7).setTargetPosition(10, 20));

参数

  • target Locator#

    要拖放至的元素的定位器（Locator）。

  • options Locator.DragToOptions（可选）

    • setForce boolean（可选）#

      是否绕过可操作性检查。默认为 false。

    • setNoWaitAfter boolean（可选）#

      已弃用

      此选项无效。

      此选项无效。

    • setSourcePosition SourcePosition（可选）#

      相对于元素内边距框左上角的此点，点击源元素。如果未指定，则使用元素的某个可见点。

    • setTargetPosition TargetPosition（可选）#

      相对于元素内边距框左上角的此点，在目标元素上放下。如果未指定，则使用元素的某个可见点。

    • setTimeout double（可选）#

      最大时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

    • setTrial boolean（可选）#

      设置此参数后，此方法仅执行可操作性检查并跳过操作。默认为 false。这在等待元素准备好进行操作但不执行操作时很有用。

返回值

详细信息

此方法将定位器拖动到另一个目标定位器或目标位置。它首先会移动到源元素，执行 mousedown，然后移动到目标元素或位置并执行 mouseup。

evaluate​

添加于：v1.14 locator.evaluate

在页面中执行 JavaScript 代码，并将匹配的元素作为参数传入。

用法

向 expression 传递参数：

Object result = page.getByTestId("myId").evaluate("(element, [x, y]) => {\n" +
  "  return element.textContent + ' ' + x * y;\n" +
  "}", Arrays.asList(7, 8));
System.out.println(result); // 打印 "myId text 56"

参数​

  • expression String# 在浏览器上下文中要计算的 JavaScript 表达式。如果表达式计算结果为函数，则会自动调用该函数。
  • arg EvaluationArgument（可选）# 要传递给 expression 的可选参数。
  • options Locator.EvaluateOptions（可选）
    • setTimeout double（可选）# 计算前等待定位器的最长时间（毫秒）。请注意，定位器解析后，计算本身不受此超时限制。默认为 30000（30 秒）。传入 0 可禁用超时。

返回值​

详细信息​

返回 expression 的返回值，调用时将匹配的元素作为第一个参数，arg 作为第二个参数。

如果 expression 返回一个 Promise，此方法将等待该 Promise 解决并返回其值。

如果 expression 抛出异常或被拒绝，此方法也会抛出异常。

evaluateAll​

新增于：v1.14 locator.evaluateAll

在页面中执行 JavaScript 代码，并将所有匹配的元素作为参数传入。

用法

Locator locator = page.locator("div");
boolean moreThanTen = (boolean) locator.evaluateAll("(divs, min) => divs.length > min", 10);

参数

  • expression String# 在浏览器上下文中要计算的 JavaScript 表达式。如果该表达式计算结果为一个函数，则会自动调用该函数。
  • arg EvaluationArgument（可选）# 要传递给 expression 的可选参数。

返回值

详细信息

返回 expression 的返回值，调用时会将所有匹配元素组成的数组作为第一个参数，将 arg 作为第二个参数传入。

如果 expression 返回一个 Promise，此方法将等待该 Promise 解决并返回其值。

如果 expression 抛出异常或被拒绝，则此方法也会抛出异常。

evaluateHandle​

添加于：v1.14 locator.evaluateHandle

在页面中执行 JavaScript 代码，将匹配到的元素作为参数传入，并返回一个包含结果的 JSHandle。

用法

Locator.evaluateHandle(expression);
Locator.evaluateHandle(expression, arg, options);

参数

  • expression String#

    要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算结果为一个函数，则该函数会自动调用。

  • arg EvaluationArgument（可选）#

    传递给 expression 的可选参数。

  • options Locator.EvaluateHandleOptions（可选）

    • setTimeout double（可选）#

      计算前等待定位器的最长时间（毫秒）。请注意，定位器解析后，计算本身不受此超时限制。默认为 30000（30 秒）。传入 0 可禁用超时。

返回值

详细信息

返回 expression 的返回值作为 JSHandle，调用时将匹配的元素作为第一个参数，将 arg 作为第二个参数。

Locator.evaluate() 和 Locator.evaluateHandle() 之间的唯一区别在于，Locator.evaluateHandle() 返回 JSHandle。

如果 expression 返回一个 Promise，此方法将等待该 Promise 解决并返回其值。

如果 expression 抛出异常或被拒绝，此方法也会抛出异常。

更多详细信息，请参阅 Page.evaluateHandle()。

fill​

新增于：v1.14 locator.fill

为输入字段设置一个值。

用法

page.getByRole(AriaRole.TEXTBOX).fill("example value");

参数​

  • value String# 要为 <input>、<textarea> 或 [contenteditable] 元素设置的值。
  • options Locator.FillOptions（可选）

返回值​

详细信息

此方法会等待 可操作性 检查，聚焦元素，填充内容，并在填充后触发 input 事件。请注意，你可以传入空字符串来清空输入字段。

如果目标元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法将抛出错误。但是，如果该元素位于具有关联 控件 的 <label> 元素内，则会填充该控件。

要发送细粒度的键盘事件，请使用 Locator.pressSequentially()。

filter​

添加于：v1.22 locator.filter

此方法根据选项缩小现有定位器的范围，例如按文本进行筛选。它可以链式调用以进行多次筛选。

用法

Locator rowLocator = page.locator("tr");
// ...
rowLocator
    .filter(new Locator.FilterOptions().setHasText("text in column 1"))
    .filter(new Locator.FilterOptions().setHas(
        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("column 2 button"))
    ))
    .screenshot();

参数

  • options Locator.FilterOptions（可选）

    • setHas Locator（可选）#

      将该方法的结果范围缩小到包含与这个相对定位器匹配的元素。例如，有 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。

      内部定位器 必须相对于 外部定位器，并且从外部定位器匹配的位置开始查询，而不是从文档根开始。例如，在 <article><content><div>Playwright</div></content></article> 中，你可以找到有 div 的 content。但是，查找有 article div 的 content 会失败，因为内部定位器必须是相对的，并且不应使用 content 之外的任何元素。

      请注意，外部和内部定位器必须属于同一框架。内部定位器不得包含 FrameLocator。

    • setHasNot Locator（可选）新增于：v1.33#

      匹配不包含与内部定位器匹配的元素的元素。内部定位器是相对于外部定位器进行查询的。例如，没有 div 的 article 匹配 <article><span>Playwright</span></article>。

      请注意，外部和内部定位器必须属于同一框架。内部定位器不得包含 FrameLocator。

    • setHasNotText String | Pattern（可选）新增于：v1.33#

      匹配在内部某个位置（可能在子元素或后代元素中）不包含指定文本的元素。当传入 [字符串] 时，匹配不区分大小写，并搜索子字符串。

    • setHasText String | Pattern（可选）#

      匹配在内部某个位置（可能在子元素或后代元素中）包含指定文本的元素。当传入 [字符串] 时，匹配不区分大小写，并搜索子字符串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

    • setVisible boolean（可选）新增于：v1.51#

      仅匹配可见或不可见的元素。

返回值

first​

添加于：v1.14 locator.first

返回定位到第一个匹配元素的定位器。

用法

Locator.first();

返回值

focus​

添加于：v1.14 locator.focus

在匹配元素上调用 focus。

用法

Locator.focus();
Locator.focus(options);

参数

返回值

frameLocator​

添加于：v1.17 locator.frameLocator

在处理 iframe 时，可以创建一个框架定位器，它将进入 iframe 并允许在该 iframe 中定位元素：

用法

Locator locator = page.frameLocator("iframe").getByText("Submit");
locator.click();

参数

  • selector String#

    解析 DOM 元素时使用的选择器。

返回值

getAttribute​

新增于：v1.14 locator.getAttribute

返回匹配元素的属性值。

断言属性

如果需要断言元素的属性，建议使用 assertThat(locator).hasAttribute() 以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法

Locator.getAttribute(name);
Locator.getAttribute(name, options);

参数

返回值

getByAltText​

新增于：v1.27 locator.getByAltText

允许通过元素的替代文本（alt text）定位元素。

用法

例如，此方法将通过替代文本“Playwright logo”找到图像：

<img alt='Playwright logo'>
page.getByAltText("Playwright logo").click();

参数

  • text String | Pattern#

    用于定位元素的文本。

  • options Locator.GetByAltTextOptions（可选）

    • setExact boolean（可选）#

      是否查找精确匹配项：区分大小写且为全字符串匹配。默认为 false。通过正则表达式定位时将忽略此选项。请注意，精确匹配仍会修剪空白字符。

返回值

getByLabel​

新增于：v1.27 locator.getByLabel

允许通过关联的 <label> 或 aria-labelledby 元素的文本，或通过 aria-label 属性来定位输入元素。

用法

例如，此方法将在以下 DOM 中按标签“Username”和“Password”查找输入框：

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">
page.getByLabel("Username").fill("john");
page.getByLabel("Password").fill("secret");

参数

  • text String | Pattern#

    用于定位元素的文本。

  • options Locator.GetByLabelOptions（可选）

    • setExact boolean（可选）#

      是否查找精确匹配项：区分大小写且为全字符串匹配。默认为 false。通过正则表达式定位时将忽略此选项。请注意，精确匹配仍会修剪空白字符。

返回值

getByPlaceholder​

新增于：v1.27 locator.getByPlaceholder

允许通过占位符文本定位输入元素。

用法

例如，考虑以下 DOM 结构。

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

你可以在通过占位符文本定位到输入框后填充内容：

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

参数​

  • text String | Pattern# 用于定位元素的文本。
  • options Locator.GetByPlaceholderOptions（可选）
    • setExact boolean（可选）# 是否查找完全匹配项：区分大小写且为全字符串匹配。默认为 false。通过正则表达式定位时将忽略此选项。请注意，完全匹配仍会修剪空白字符。

返回值​

getByRole​

新增于：v1.27 locator.getByRole

允许通过元素的 ARIA 角色、ARIA 属性 和 可访问名称 来定位元素。

用法​

考虑以下 DOM 结构。

<h3>注册</h3>
<label>
  <input type="checkbox" /> 订阅
</label>
<br/>
<button>提交</button>

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

assertThat(page
    .getByRole(AriaRole.HEADING,
               new Page.GetByRoleOptions().setName("注册")))
    .isVisible();

page.getByRole(AriaRole.CHECKBOX,
               new Page.GetByRoleOptions().setName("订阅"))
    .check();

page.getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName(
                   Pattern.compile("提交", Pattern.CASE_INSENSITIVE)))
    .click();

参数

  • role enum AriaRole { ALERT, ALERTDIALOG, APPLICATION, ARTICLE, BANNER, BLOCKQUOTE, BUTTON, CAPTION, CELL, CHECKBOX, CODE, COLUMNHEADER, COMBOBOX, COMPLEMENTARY, CONTENTINFO, DEFINITION, DELETION, DIALOG, DIRECTORY, DOCUMENT, EMPHASIS, FEED, FIGURE, FORM, GENERIC, GRID, GRIDCELL, GROUP, HEADING, IMG, INSERTION, LINK, LIST, LISTBOX, LISTITEM, LOG, MAIN, MARQUEE, MATH, METER, MENU, MENUBAR, MENUITEM, MENUITEMCHECKBOX, MENUITEMRADIO, NAVIGATION, NONE, NOTE, OPTION, PARAGRAPH, PRESENTATION, PROGRESSBAR, RADIO, RADIOGROUP, REGION, ROW, ROWGROUP, ROWHEADER, SCROLLBAR, SEARCH, SEARCHBOX, SEPARATOR, SLIDER, SPINBUTTON, STATUS, STRONG, SUBSCRIPT, SUPERSCRIPT, SWITCH, TAB, TABLE, TABLIST, TABPANEL, TERM, TEXTBOX, TIME, TIMER, TOOLBAR, TOOLTIP, TREE, TREEGRID, TREEITEM }#

    必需的 ARIA 角色。

  • options Locator.GetByRoleOptions (可选)

    • setChecked boolean (可选)#

      通常由 aria-checked 或原生 <input type=checkbox> 控件设置的属性。

      了解更多关于 aria-checked 的信息。

    • setDisabled boolean (可选)#

      通常由 aria-disabled 或 disabled 设置的属性。

      备注

      与大多数其他属性不同，disabled 会通过 DOM 层级继承。了解更多关于 aria-disabled 的信息。

    • setExact boolean (可选) 新增于：v1.28#

      setName 是否完全匹配：区分大小写且匹配整个字符串。默认为 false。当 setName 是正则表达式时，此选项将被忽略。请注意，完全匹配仍会修剪空白字符。

    • setExpanded boolean (可选)#

      通常由 aria-expanded 设置的属性。

      了解更多关于 aria-expanded 的信息。

    • setIncludeHidden boolean (可选)#

      控制是否匹配隐藏元素的选项。默认情况下，根据 ARIA 定义，角色选择器仅匹配非隐藏元素。

      了解更多关于 aria-hidden 的信息。

    • setLevel int (可选)#

      通常用于 heading、listitem、row、treeitem 角色的数字属性，<h1>-<h6> 元素有默认值。

      了解更多关于 aria-level 的信息。

    • setName String | Pattern (可选)#

      用于匹配 可访问名称 的选项。默认情况下，匹配不区分大小写并搜索子字符串，使用 setExact 来控制此行为。

      了解更多关于 可访问名称 的信息。

    • setPressed boolean (可选)#

      通常由 aria-pressed 设置的属性。

      了解更多关于 aria-pressed 的信息。

    • setSelected boolean (可选)#

      通常由 aria-selected 设置的属性。

      了解更多关于 aria-selected 的信息。

返回值

详细信息

角色选择器不会替代可访问性审计和一致性测试，而是提供有关 ARIA 指南的早期反馈。

许多 HTML 元素都有一个隐式的定义角色，角色选择器可以识别这些角色。你可以在此处找到所有支持的角色。ARIA 指南不建议通过将 role 和 / 或 aria-* 属性设置为默认值来重复隐式角色和属性。

getByTestId​

新增于：v1.27 locator.getByTestId

通过测试 ID 定位元素。

用法

考虑以下 DOM 结构。

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

你可以通过其测试 ID 定位该元素：

page.getByTestId("directions").click();

参数

返回值

详细信息

默认情况下，data-testid 属性用作测试 ID。如有必要，可使用 Selectors.setTestIdAttribute() 配置不同的测试 ID 属性。

getByText​

添加于：v1.27 locator.getByText

允许定位包含给定文本的元素。

另请参阅 Locator.filter()，它允许通过其他条件（如可访问角色）进行匹配，然后按文本内容进行筛选。

用法

考虑以下 DOM 结构：

<div>Hello <span>world</span></div>
<div>Hello</div>

你可以通过文本子串、精确字符串或正则表达式进行定位：

// 匹配 <span>
page.getByText("world");

// 匹配第一个 <div>
page.getByText("Hello world");

// 匹配第二个 <div>
page.getByText("Hello", new Page.GetByTextOptions().setExact(true));

// 匹配两个 <div>
page.getByText(Pattern.compile("Hello"));

// 匹配第二个 <div>
page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE));

参数

  • text String | Pattern#

    用于定位元素的文本。

  • options Locator.GetByTextOptions (可选)

    • setExact boolean (可选)#

      是否查找精确匹配项：区分大小写且为全字符串匹配。默认为 false。通过正则表达式定位时将忽略此选项。请注意，精确匹配仍会修剪空白字符。

返回值

详情​

即使是精确匹配，按文本匹配也总会对空白字符进行规范化处理。例如，将多个空格合并为一个，将换行符转换为空格，并忽略前导和尾随的空白字符。

类型为 button 和 submit 的输入元素是通过其 value 而不是文本内容进行匹配的。例如，通过文本 "登录" 定位会匹配 <input type=button value="登录">。

getByTitle​

添加于：v1.27 locator.getByTitle

允许通过元素的 title 属性来定位元素。

用法​

考虑以下 DOM 结构。

<span title='问题数量'>25 个问题</span>

你可以在通过标题文本定位到元素后，检查问题数量：

assertThat(page.getByTitle("问题数量")).hasText("25 个问题");

参数​

  • text String | Pattern#

    用于定位元素的文本。

  • options Locator.GetByTitleOptions（可选）

    • setExact boolean（可选）#

      是否查找精确匹配项：区分大小写且为全字符串匹配。默认为 false。在通过正则表达式定位时会忽略此选项。请注意，精确匹配仍然会去除空白字符。

返回值​

highlight​

添加于：v1.20 locator.highlight

在屏幕上突出显示相应的元素。这对调试很有用，不要提交使用 Locator.highlight() 的代码。

用法

Locator.highlight();

返回值

hover​

添加于：v1.14 locator.hover

悬停在匹配的元素上。

用法

page.getByRole(AriaRole.LINK).hover();

参数

  • options Locator.HoverOptions （可选）

    • setForce [布尔值]（可选）#

      是否绕过可操作性检查。默认为 false。

    • setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }>（可选）#

      要按下的修饰键。确保在操作过程中只按下这些修饰键，然后恢复当前的修饰键。如果未指定，则使用当前按下的修饰键。“ControlOrMeta” 在 Windows 和 Linux 上解析为 “Control”，在 macOS 上解析为 “Meta”。

    • setNoWaitAfter [布尔值]（可选） 新增于：v1.28#

      已弃用

      此选项无效。

      此选项无效。

    • setPosition Position（可选）#

      • setX [双精度浮点数]

      • setY [双精度浮点数]

      相对于元素内边距框左上角使用的一个点。如果未指定，则使用元素的某个可见点。

    • setTimeout [双精度浮点数]（可选）#

      最大时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

    • setTrial [布尔值]（可选）#

      设置此参数后，此方法仅执行可操作性检查并跳过操作。默认为 false。这在等待元素准备好执行操作但不实际执行操作时很有用。请注意，无论 trial 设置如何，都会按下键盘 modifiers，以便测试仅在按下这些键时才可见的元素。

返回值

详细信息

此方法通过执行以下步骤将鼠标悬停在元素上：

  1. 等待对元素执行可操作性检查，除非设置了setForce选项。
  2. 如有需要，将元素滚动到可见区域。
  3. 使用Page.mouse()将鼠标悬停在元素中心，或指定的setPosition位置。

如果在操作过程中元素从 DOM 中分离，此方法将抛出异常。

如果在指定的setTimeout时间内所有步骤未完成，此方法将抛出TimeoutError。传递零超时将禁用此功能。

innerHTML​

新增于：v1.14 locator.innerHTML

返回element.innerHTML。

用法

Locator.innerHTML();
Locator.innerHTML(options);

参数

返回值

innerText​

新增于：v1.14 locator.innerText

返回 element.innerText。

断言文本

如果需要断言页面上的文本，建议使用 assertThat(locator).hasText() 并搭配 setUseInnerText 选项，以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法

Locator.innerText();
Locator.innerText(options);

参数

返回值

inputValue​

添加于：v1.14 locator.inputValue

返回匹配的 <input>、<textarea> 或 <select> 元素的值。

断言值

如果需要断言输入值，建议使用 assertThat(locator).hasValue() 以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法

String value = page.getByRole(AriaRole.TEXTBOX).inputValue();

参数

返回值

详细信息

如果元素不是输入框、文本域或选择框，则会抛出异常。但是，如果该元素位于具有关联 control 的 <label> 元素内，则返回该控件的值。

isChecked​

新增于：v1.14 locator.isChecked

返回元素是否被选中。如果该元素不是复选框或单选输入框，则会抛出异常。

断言选中状态

如果需要断言复选框已被选中，建议使用 assertThat(locator).isChecked() 以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法

boolean checked = page.getByRole(AriaRole.CHECKBOX).isChecked();

参数

返回值

isDisabled​

新增于：v1.14 locator.isDisabled

返回元素是否被禁用，与 enabled 相反。

断言禁用状态

如果需要断言元素已被禁用，建议使用 assertThat(locator).isDisabled() 以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法​

boolean disabled = page.getByRole(AriaRole.BUTTON).isDisabled();

参数​

返回值​

isEditable​

新增于：v1.14 locator.isEditable

返回元素是否可编辑（editable）。如果目标元素不是 <input>、<textarea>、<select>、[contenteditable]，且没有允许 [aria-readonly] 的角色，则此方法会抛出错误。

断言可编辑状态

如果需要断言元素是否可编辑，建议使用 assertThat(locator).isEditable() 以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法​

boolean editable = page.getByRole(AriaRole.TEXTBOX).isEditable();

参数

返回值

isEnabled​

新增于：v1.14 locator.isEnabled

返回元素是否已启用。

断言启用状态

如果需要断言元素已启用，建议使用 assertThat(locator).isEnabled() 以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法

boolean enabled = page.getByRole(AriaRole.BUTTON).isEnabled();

参数

返回值

isHidden​

新增于：v1.14 locator.isHidden

返回元素是否隐藏，与 visible 相反。

断言可见性

如果需要断言元素是隐藏的，建议使用 assertThat(locator).isHidden() 以避免不稳定情况。更多详细信息，请参阅 断言指南。

用法

boolean hidden = page.getByRole(AriaRole.BUTTON).isHidden();

参数

  • options Locator.IsHiddenOptions（可选）

    • setTimeout double（可选）#

      已弃用

      此选项将被忽略。Locator.isHidden() 不会等待元素变为隐藏状态，而是立即返回。

返回值

isVisible​

新增于：v1.14 locator.isVisible

返回元素是否可见。

断言可见性

如果需要断言元素可见，建议使用 assertThat(locator).isVisible()，以避免测试不稳定。更多详细信息，请参阅 断言指南。

用法

boolean visible = page.getByRole(AriaRole.BUTTON).isVisible();

参数

  • options Locator.IsVisibleOptions (可选)

    • setTimeout double (可选)#

      已弃用

      此选项将被忽略。Locator.isVisible() 不会等待元素变为可见，而是立即返回。

返回值

last​

新增于：v1.14 locator.last

返回定位到最后一个匹配元素的定位器。

用法

Locator banana = page.getByRole(AriaRole.LISTITEM).last();

返回值

locator​

添加于：v1.14 locator.locator

该方法在定位器的子树中查找与指定选择器匹配的元素。它还接受过滤选项，类似于 Locator.filter() 方法。

详细了解定位器。

用法

Locator.locator(selectorOrLocator);
Locator.locator(selectorOrLocator, options);

参数

  • selectorOrLocator String | Locator#

    解析 DOM 元素时使用的选择器或定位器（Locator）。

  • options Locator.LocatorOptions（可选）

    • setHas Locator（可选）#

      将方法的结果范围缩小到包含与该相对定位器匹配的元素。例如，有 text=Playwright 的 article 与 <article><div>Playwright</div></article> 匹配。

      内部定位器必须相对于外部定位器，并且从外部定位器匹配的位置开始查询，而不是从文档根开始。例如，在 <article><content><div>Playwright</div></content></article> 中，你可以找到有 div 的 content。但是，查找有 article div 的 content 会失败，因为内部定位器必须是相对的，并且不应使用 content 之外的任何元素。

      请注意，外部和内部定位器必须属于同一框架。内部定位器不得包含 FrameLocator。

    • setHasNot Locator（可选） 新增于：v1.33#

      匹配不包含与内部定位器匹配的元素。内部定位器是相对于外部定位器进行查询的。例如，没有 div 的 article 与 <article><span>Playwright</span></article> 匹配。

      请注意，外部和内部定位器必须属于同一框架。内部定位器不得包含 FrameLocator。

    • setHasNotText String | Pattern（可选） 新增于：v1.33#

      匹配内部（可能在子元素或后代元素中）不包含指定文本的元素。当传入 [字符串] 时，匹配不区分大小写，并搜索子字符串。

    • setHasText String | Pattern（可选）#

      匹配内部（可能在子元素或后代元素中）包含指定文本的元素。当传入 [字符串] 时，匹配不区分大小写，并搜索子字符串。例如，"Playwright" 与 <article><div>Playwright</div></article> 匹配。

返回值

nth​

添加于：v1.14 locator.nth

返回定位器，指向第 n 个匹配元素。索引从 0 开始，nth(0) 选择第一个元素。

用法

Locator banana = page.getByRole(AriaRole.LISTITEM).nth(2);

参数

返回值

or​

添加于：v1.33 locator.or

创建一个定位器，匹配两个定位器中至少一个所匹配的所有元素。

请注意，当两个定位器都匹配某些内容时，结果定位器将有多个匹配项，这可能会导致 定位器严格性 冲突。

用法​

假设有这样一个场景：你想要点击 “新建邮件” 按钮，但有时会弹出一个安全设置对话框。在这种情况下，你可以等待 “新建邮件” 按钮或对话框出现，然后采取相应的行动。

备注

如果 “新建邮件” 按钮和安全对话框同时出现在屏幕上，or 定位器会匹配到它们两者，这可能会抛出 "严格模式违规" 错误。在这种情况下，你可以使用 Locator.first() 只匹配其中一个。

Locator newEmail = page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("New"));
Locator dialog = page.getByText("Confirm security settings");
assertThat(newEmail.or(dialog).first()).isVisible();
if (dialog.isVisible())
  page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Dismiss")).click();
newEmail.click();

参数​

  • locator Locator#

    要匹配的备用定位器。

返回值​

page​

添加于：v1.19 locator.page

此定位器所属的页面。

用法​

Locator.page();

返回值​

press​

添加于：v1.14 locator.press

聚焦匹配的元素并按下组合键。

用法​

page.getByRole(AriaRole.TEXTBOX).press("Backspace");

参数​

  • key String# 要按下的键名或要生成的字符，例如 ArrowLeft 或 a。
  • options Locator.PressOptions（可选）
    • setDelay double（可选）# keydown 和 keyup 之间等待的时间（毫秒）。默认为 0。
    • setNoWaitAfter boolean（可选）#
      已弃用

      此选项在未来将默认为 true。

      启动导航的操作会等待这些导航发生以及页面开始加载。你可以通过设置此标志选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。
    • setTimeout double（可选）# 最大时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

返回值​

详细信息​

聚焦元素，然后使用 Keyboard.down() 和 Keyboard.up()。

key 可以指定预期的 keyboardEvent.key 值，或指定生成文本的单个字符。key 值的全集可在 此处 找到。键的示例如下：

F1 - F12、Digit0 - Digit9、KeyA - KeyZ、Backquote、Minus、Equal、Backslash、Backspace、Tab、Delete、Escape、ArrowDown、End、Enter、Home、Insert、PageDown、PageUp、ArrowRight、ArrowUp 等。

还支持以下修饰快捷键：Shift、Control、Alt、Meta、ShiftLeft、ControlOrMeta。ControlOrMeta 在 Windows 和 Linux 上解析为 Control，在 macOS 上解析为 Meta。

按住 Shift 将输入与 key 对应的大写文本。

如果 key 是单个字符，则区分大小写，因此值 a 和 A 将生成不同的相应文本。

也支持诸如 key: "Control+o"、key: "Control++ 或 key: "Control+Shift+T" 之类的快捷键。当与修饰符一起指定时，按下后续键时，修饰符将被按下并保持按下状态。

pressSequentially​

新增于：v1.38 locator.pressSequentially

:::提示

在大多数情况下，你应该使用 Locator.fill() 替代。只有当页面上有特殊的键盘处理时，你才需要逐个按键。 :::

聚焦元素，然后为文本中的每个字符发送 keydown、keypress/input 和 keyup 事件。

要按下特殊键，如 Control 或 ArrowDown，请使用 Locator.press()。

用法

locator.pressSequentially("Hello"); // 立即输入
locator.pressSequentially("World", new Locator.pressSequentiallyOptions().setDelay(100)); // 输入速度较慢，类似用户输入

在文本字段中输入内容然后提交表单的示例：

Locator locator = page.getByLabel("Password");
locator.pressSequentially("my password");
locator.press("Enter");

参数

  • text String#

    要依次输入到聚焦元素中的字符串。

  • options Locator.PressSequentiallyOptions（可选）

返回值

screenshot​

新增于：v1.14 locator.screenshot

对与定位器匹配的元素进行截图。

用法

page.getByRole(AriaRole.LINK).screenshot();

禁用动画并将截图保存到文件：

page.getByRole(AriaRole.LINK).screenshot(new Locator.ScreenshotOptions()
   .setAnimations(ScreenshotAnimations.DISABLED)
   .setPath(Paths.get("example.png")));

参数

  • options Locator.ScreenshotOptions（可选）

    • setAnimations enum ScreenshotAnimations { DISABLED, ALLOW }（可选）#

      设置为"disabled"时，将停止CSS动画、CSS过渡和Web动画。动画会根据其持续时间得到不同的处理：

      • 有限动画将快进到完成状态，因此它们将触发transitionend事件。
      • 无限动画将取消到初始状态，然后在截图后重新播放。

      默认值为"allow"，即不触动动画。

    • setCaret enum ScreenshotCaret { HIDE, INITIAL }（可选）#

      设置为"hide"时，截图将隐藏文本插入符号。设置为"initial"时，文本插入符号的行为将不会改变。默认值为"hide"。

    • setMask List<Locator>（可选）#

      指定在进行截图时应被遮罩的定位器。被遮罩的元素将覆盖一个粉色框#FF00FF（可通过setMaskColor自定义），该框将完全覆盖其边界框。遮罩也应用于不可见元素，若要禁用此行为，请参阅仅匹配可见元素。

    • setMaskColor String（可选） 新增于：v1.35#

      以CSS颜色格式指定被遮罩元素的覆盖框颜色。默认颜色为粉色#FF00FF。

    • setOmitBackground boolean（可选）#

      隐藏默认的白色背景，并允许捕获具有透明度的截图。不适用于jpeg图像。默认值为false。

    • setPath Path（可选）#

      保存图像的文件路径。截图类型将从文件扩展名推断得出。如果setPath是相对路径，则将相对于当前工作目录进行解析。如果未提供路径，则图像不会保存到磁盘。

    • setQuality int（可选）#

      图像质量，取值范围为0 - 100。不适用于png图像。

    • setScale enum ScreenshotScale { CSS, DEVICE }（可选）#

      设置为"css"时，截图在页面上每个CSS像素对应一个物理像素。对于高DPI设备，这将使截图保持较小尺寸。使用"device"选项将在每个设备像素对应一个物理像素，因此高DPI设备的截图将是原来的两倍甚至更大。

      默认值为"device"。

    • setStyle String（可选） 新增于：v1.41#

      进行截图时要应用的样式表文本。在这里，您可以隐藏动态元素、使元素不可见或更改其属性，以帮助您创建可重复的截图。此样式表会穿透影子DOM并应用于内部框架。

    • setTimeout double（可选）#

      最大时间（毫秒）。默认值为30000（30秒）。传入0可禁用超时。默认值可以通过使用BrowserContext.setDefaultTimeout()或Page.setDefaultTimeout()方法更改。

    • setType enum ScreenshotType { PNG, JPEG }（可选）#

      指定截图类型，默认为png。

返回值

  • [byte[]]#

详细信息

此方法会截取页面的屏幕截图，并根据与定位器匹配的特定元素的大小和位置进行裁剪。如果该元素被其他元素覆盖，那么在屏幕截图中实际上将看不到它。如果该元素是一个可滚动的容器，那么在屏幕截图中只会显示当前已滚动的内容。

此方法会等待 可操作性检查，然后在截取屏幕截图之前将元素滚动到可见区域。如果该元素从 DOM 中分离，此方法将抛出错误。

返回捕获到的屏幕截图的缓冲区。

scrollIntoViewIfNeeded​

添加于：v1.14 locator.scrollIntoViewIfNeeded

此方法会等待 可操作性检查，然后尝试将元素滚动到可见区域，除非根据 IntersectionObserver 的 ratio 定义，该元素已完全可见。

有关滚动的其他方法，请参阅 滚动操作。

用法

Locator.scrollIntoViewIfNeeded();
Locator.scrollIntoViewIfNeeded(options);

参数

返回值

selectOption​

新增于：v1.14 locator.selectOption

在 <select> 中选择一个或多个选项。

用法

<select multiple>
  <option value="red">红色</option>
  <option value="green">绿色</option>
  <option value="blue">蓝色</option>
</select>
// 选择匹配值或标签的单个选项
element.selectOption("blue");
// 选择匹配标签的单个选项
element.selectOption(new SelectOption().setLabel("蓝色"));
// 选择蓝色、红色和第二个选项
element.selectOption(new String[] {"red", "green", "blue"});

参数​

  • values null | String | ElementHandle | String | SelectOption | ElementHandle | SelectOption[]#

    • setValue String（可选）

      通过 option.value 进行匹配。可选。

    • setLabel String（可选）

      通过 option.label 进行匹配。可选。

    • setIndex int（可选）

      通过索引进行匹配。可选。

    要选择的选项。如果 <select> 有 multiple 属性，所有匹配的选项都会被选中，否则只有第一个匹配传入选项之一的选项会被选中。字符串值会同时匹配值和标签。如果所有指定的属性都匹配，则认为该选项匹配。
  • options Locator.SelectOptionOptions（可选）

返回值

详细信息

此方法会等待可操作性检查，等待所有指定的选项出现在 <select> 元素中，然后选择这些选项。

如果目标元素不是 <select> 元素，此方法将抛出错误。但是，如果该元素位于具有关联 control 的 <label> 元素内，则将改用该控件。

返回已成功选择的选项值数组。

一旦所有提供的选项都被选中，就会触发 change 和 input 事件。

selectText​

新增于：v1.14 locator.selectText

此方法会等待可操作性检查，然后聚焦到该元素并选中其所有文本内容。

如果该元素位于具有关联 control 的 <label> 元素内，则聚焦并选中该控件中的文本。

用法

Locator.selectText();
Locator.selectText(options);

参数

  • options Locator.SelectTextOptions（可选）

返回值

setChecked​

新增于：v1.15 locator.setChecked

设置复选框或单选按钮元素的状态。

用法

page.getByRole(AriaRole.CHECKBOX).setChecked(true);

参数

  • checked boolean#

    是否选中或取消选中复选框。

  • options Locator.SetCheckedOptions (可选)

    • setForce boolean (可选)#

      是否绕过可操作性检查。默认为 false。

    • setNoWaitAfter boolean (可选)#

      已弃用

      此选项无效。

      此选项无效。

    • setPosition Position (可选)#

      相对于元素内边距框左上角使用的一个点。如果未指定，则使用元素的某个可见点。

    • setTimeout double (可选)#

      最大时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

    • setTrial boolean (可选)#

      设置此参数后，此方法仅执行可操作性检查并跳过操作。默认为 false。这对于等待元素准备好执行操作但不实际执行操作很有用。

返回值

详细信息

此方法通过执行以下步骤来选中或取消选中一个元素：

  1. 确保匹配的元素是复选框或单选输入框。否则，此方法将抛出异常。
  2. 如果该元素已经处于正确的选中状态，此方法将立即返回。
  3. 等待对匹配元素的可操作性检查，除非设置了setForce选项。如果在检查过程中元素被分离，整个操作将重试。
  4. 如有需要，将元素滚动到可见区域。
  5. 使用Page.mouse()点击元素中心。
  6. 确保该元素现在已被选中或取消选中。否则，此方法将抛出异常。

如果在指定的setTimeout时间内所有步骤尚未完成，此方法将抛出TimeoutError。传入零超时将禁用此功能。

setInputFiles​

新增于：v1.14 locator.setInputFiles

将单个或多个文件上传到 <input type=file> 中。对于带有 [webkitdirectory] 属性的输入框，仅支持单个目录路径。

使用方法​

// 选择单个文件
page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

// 选择多个文件
page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

// 选择一个目录
page.getByLabel("Upload directory").setInputFiles(Paths.get("mydir"));

// 移除所有选定的文件
page.getByLabel("Upload file").setInputFiles(new Path[0]);

// 从内存中上传缓冲区
page.getByLabel("Upload file").setInputFiles(new FilePayload(
  "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

参数​

  • files Path | Path | FilePayload | FilePayload[]#

    • setName String

      文件名

    • setMimeType String

      文件类型

    • setBuffer [byte[]]

      文件内容

  • options Locator.SetInputFilesOptions（可选）

返回值

详细信息

将文件输入的值设置为这些文件路径或文件。如果某些 filePaths 是相对路径，则它们将相对于当前工作目录进行解析。对于空数组，将清除选定的文件。

此方法要求 Locator 指向一个 input 元素。但是，如果该元素位于具有关联 control 的 <label> 元素内，则会改为定位该控件。

tap​

添加于：v1.14 locator.tap

对与定位器匹配的元素执行点击手势。有关通过手动调度触摸事件模拟其他手势的示例，请参阅 模拟传统触摸事件 页面。

用法

Locator.tap();
Locator.tap(options);

参数

  • options Locator.TapOptions（可选）

    • setForce [布尔值]（可选）#

      是否绕过可操作性检查。默认为 false。

    • setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }>（可选）#

      要按下的修饰键。确保在操作过程中只按下这些修饰键，然后恢复当前的修饰键。如果未指定，则使用当前按下的修饰键。“ControlOrMeta” 在 Windows 和 Linux 上解析为 “Control”，在 macOS 上解析为 “Meta”。

    • setNoWaitAfter [布尔值]（可选）#

      已弃用

      此选项无效。

      此选项无效。

    • setPosition Position（可选）#

      • setX [双精度浮点数]

      • setY [双精度浮点数]

      相对于元素内边距框左上角使用的一个点。如果未指定，则使用元素的某个可见点。

    • setTimeout [双精度浮点数]（可选）#

      最大时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

    • setTrial [布尔值]（可选）#

      设置此参数后，此方法仅执行可操作性检查并跳过操作。默认为 false。这对于等待元素准备好进行操作但不执行操作很有用。请注意，无论 trial 如何，都会按下键盘 modifiers，以便测试仅在按下这些键时才可见的元素。

返回值

详细信息

此方法通过执行以下步骤点击元素：

  1. 等待对元素进行可操作性检查，除非设置了setForce选项。
  2. 如有需要，将元素滚动到可见区域。
  3. 使用Page.touchscreen()点击元素中心，或指定的setPosition。

如果在操作过程中元素在任何时刻从 DOM 中分离，此方法将抛出异常。

如果在指定的setTimeout内所有步骤组合未完成，此方法将抛出TimeoutError。传入零超时将禁用此功能。

备注

element.tap()要求浏览器上下文的hasTouch选项设置为 true。

textContent​

新增于：v1.14 locator.textContent

返回node.textContent。

断言文本

如果需要在页面上断言文本，建议使用assertThat(locator).hasText()以避免不稳定情况。更多详细信息，请参阅断言指南。

用法

Locator.textContent();
Locator.textContent(options);

参数

返回值

uncheck​

添加于：v1.14 locator.uncheck

确保复选框或单选按钮元素未被选中。

用法

page.getByRole(AriaRole.CHECKBOX).uncheck();

参数

  • options Locator.UncheckOptions （可选）

    • setForce [布尔值]（可选）#

      是否绕过可操作性检查。默认为 false。

    • setNoWaitAfter [布尔值]（可选）#

      已弃用

      此选项无效。

      此选项无效。

    • setPosition Position （可选）#

      • setX [双精度浮点数]

      • setY [双精度浮点数]

      相对于元素内边距框左上角使用的一个点。如果未指定，则使用元素的某个可见点。

    • setTimeout [双精度浮点数]（可选）#

      最大时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

    • setTrial [布尔值]（可选）#

      设置此参数时，此方法仅执行可操作性检查并跳过操作。默认为 false。这对于等待元素准备好进行操作但不实际执行操作很有用。

返回值

详细信息

此方法通过执行以下步骤取消选中元素：

  1. 确保该元素是复选框或单选输入框。如果不是，此方法将抛出异常。如果该元素已经未选中，此方法将立即返回。
  2. 等待对该元素进行可操作性检查，除非设置了setForce选项。
  3. 如有需要，将元素滚动到可见区域。
  4. 使用Page.mouse()点击元素中心。
  5. 确保该元素现在已取消选中。如果没有，此方法将抛出异常。

如果在操作过程中的任何时刻，元素从 DOM 中分离，此方法将抛出异常。

如果在指定的setTimeout时间内，所有步骤组合未完成，此方法将抛出TimeoutError。传递零超时将禁用此功能。

waitFor​

新增于：v1.16 locator.waitFor

当定位器指定的元素满足setState选项时返回。

如果目标元素已经满足条件，该方法将立即返回。否则，最多等待setTimeout毫秒，直到条件满足。

用法

Locator orderSent = page.locator("#order-sent");
orderSent.waitFor();

参数​

  • options Locator.WaitForOptions（可选）

    • setState enum WaitForSelectorState { ATTACHED, DETACHED, VISIBLE, HIDDEN }（可选）#

      默认值为 'visible'。可以是以下值之一：

      • 'attached' - 等待元素出现在 DOM 中。
      • 'detached' - 等待元素从 DOM 中移除。
      • 'visible' - 等待元素具有非空的边界框且没有 visibility:hidden。注意，没有任何内容或 display:none 的元素具有空的边界框，不被视为可见。
      • 'hidden' - 等待元素从 DOM 中移除，或具有空的边界框或 visibility:hidden。这与 'visible' 选项相反。

    • setTimeout double（可选）#

      最大时间（毫秒）。默认值为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。

返回值​

已弃用​

elementHandle​

添加于：v1.14 locator.elementHandle
不推荐

始终优先使用 Locator 和网页断言，而不是 ElementHandle，因为后者本质上具有竞态性。

将给定的定位器解析为第一个匹配的 DOM 元素。如果没有匹配的元素，则等待出现一个。如果有多个元素匹配该定位器，则抛出异常。

用法

Locator.elementHandle();
Locator.elementHandle(options);

参数

返回值

elementHandles​

添加于：v1.14 locator.elementHandles
不推荐

始终优先使用 Locator 和网页断言，而不是 ElementHandle，因为后者本质上具有竞态性。

将给定的定位器解析为所有匹配的 DOM 元素。如果没有匹配的元素，则返回一个空列表。

用法

Locator.elementHandles();

返回值

type​

新增于：v1.14 locator.type
已弃用

在大多数情况下，你应该使用 Locator.fill() 替代。只有当页面上有特殊的键盘处理逻辑时，你才需要逐个按键，这种情况下请使用 Locator.pressSequentially()。

聚焦元素，然后为文本中的每个字符发送 keydown、keypress/input 和 keyup 事件。

要按下特殊键，如 Control 或 ArrowDown，请使用 Locator.press()。

用法

参数

  • text String#

    要输入到聚焦元素中的文本。

  • options Locator.TypeOptions（可选）

返回值