Locator

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

了解更多关于定位器的信息.

方法

all

添加于: v1.29

locator.all

当定位器指向元素列表时，这将返回一个定位器数组，指向它们各自的元素。

注意

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

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

当元素列表稳定但动态加载时，请等待完整列表加载完成后再调用 locator.all()。

用法

同步
异步

for li in page.get_by_role('listitem').all():
  li.click();

for li in await page.get_by_role('listitem').all():
  await li.click();

返回值

List[Locator]#

all_inner_texts

添加于: v1.14

locator.all_inner_texts

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

断言文本

如果需要在页面上断言文本，请优先使用 expect(locator).to_have_text() 并使用 use_inner_text 选项以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

同步
异步

texts = page.get_by_role("link").all_inner_texts()

texts = await page.get_by_role("link").all_inner_texts()

返回值

List[str]#

all_text_contents

添加于: v1.14

locator.all_text_contents

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

断言文本

如果需要在页面上断言文本，请优先使用 expect(locator).to_have_text() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

同步
异步

texts = page.get_by_role("link").all_text_contents()

texts = await page.get_by_role("link").all_text_contents()

返回值

List[str]#

and_

添加于: v1.34

locator.and_

创建一个定位器，该定位器同时匹配此定位器和参数定位器。

用法

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

同步
异步

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

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

参数

locator Locator #

要匹配的附加定位器。

返回值

Locator #

aria_snapshot

添加于: v1.49

locator.aria_snapshot

捕获给定元素的 aria 快照。阅读更多关于 aria 快照和 expect(locator).to_match_aria_snapshot() 以了解相应的断言。

用法

同步
异步

page.get_by_role("link").aria_snapshot()

await page.get_by_role("link").aria_snapshot()

参数

timeout float (可选)#

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

返回值

str #

详情

此方法捕获给定元素的 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(**kwargs)

参数

timeout float (可选)#

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

返回值

NoneType #

bounding_box

添加于: v1.14

locator.bounding_box

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

用法

同步
异步

box = page.get_by_role("button").bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

box = await page.get_by_role("button").bounding_box()
await page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

参数

timeout float (可选)#

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

返回值

NoneType | Dict#
- x float
  
  元素在像素中的 x 坐标。
- y float
  
  元素在像素中的 y 坐标。
- width float
  
  元素在像素中的宽度。
- height float
  
  元素在像素中的高度。

详情

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

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

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

check

添加于: v1.14

locator.check

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

用法

同步
异步

page.get_by_role("checkbox").check()

await page.get_by_role("checkbox").check()

参数

force bool (可选)#

是否绕过可操作性检查。默认为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。
timeout float (可选)#

最大时间（毫秒）。默认为 30000 (30 秒)。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)#

设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于等待元素准备好进行操作而无需执行操作。

返回值

NoneType #

详情

执行以下步骤

确保元素是复选框或单选输入框。如果不是，此方法将抛出错误。如果元素已被选中，此方法将立即返回。
等待元素上的可操作性检查，除非设置了 force 选项。
如果需要，将元素滚动到视图中。
使用 page.mouse 在元素的中心单击。
确保现在已选中该元素。如果不是，此方法将抛出错误。

如果在操作期间的任何时刻元素从 DOM 中分离，此方法将抛出错误。

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

clear

添加于: v1.28

locator.clear

清除输入字段。

用法

同步
异步

page.get_by_role("textbox").clear()

await page.get_by_role("textbox").clear()

参数

force bool (可选)#

是否绕过可操作性检查。默认为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
timeout float (可选)#

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

返回值

NoneType #

详情

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

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

click

添加于: v1.14

locator.click

点击一个元素。

用法

点击按钮

同步
异步

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

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

在画布上的特定位置进行 Shift+右键单击

同步
异步

page.locator("canvas").click(
    button="right", modifiers=["Shift"], position={"x": 23, "y": 32}
)

await page.locator("canvas").click(
    button="right", modifiers=["Shift"], position={"x": 23, "y": 32}
)

参数

button "left" | "right" | "middle" (可选)#

默认为 left。
click_count int (可选)#

默认为 1。请参阅 UIEvent.detail。
delay float (可选)#

mousedown 和 mouseup 之间等待的时间（毫秒）。默认为 0。
force bool (可选)#

是否绕过可操作性检查。默认为 false。
modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

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

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

启动导航的操作正在等待这些导航发生并等待页面开始加载。您可以通过设置此标志来选择不等待。您只需要在特殊情况下使用此选项，例如导航到无法访问的页面。默认为 false。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。
timeout float (可选)#

最大时间（毫秒）。默认为 30000 (30 秒)。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)#

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

返回值

NoneType #

详情

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

等待元素上的可操作性检查，除非设置了 force 选项。
如果需要，将元素滚动到视图中。
使用 page.mouse 在元素的中心或指定的 position 单击。
等待启动的导航成功或失败，除非设置了 no_wait_after 选项。

如果在操作期间的任何时刻元素从 DOM 中分离，此方法将抛出错误。

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

count

添加于: v1.14

locator.count

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

断言计数

如果需要在页面上断言元素数量，请优先使用 expect(locator).to_have_count() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

同步
异步

count = page.get_by_role("listitem").count()

count = await page.get_by_role("listitem").count()

返回值

int #

dblclick

添加于: v1.14

locator.dblclick

双击一个元素。

用法

locator.dblclick()
locator.dblclick(**kwargs)

参数

button "left" | "right" | "middle" (可选)#

默认为 left。
delay float (可选)#

mousedown 和 mouseup 之间等待的时间（毫秒）。默认为 0。
force bool (可选)#

是否绕过可操作性检查。默认为 false。
modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

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

已弃用
此选项无效。

此选项无效。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。
timeout float (可选)#

最大时间（毫秒）。默认为 30000 (30 秒)。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)#

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

返回值

NoneType #

详情

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

等待元素上的可操作性检查，除非设置了 force 选项。
如果需要，将元素滚动到视图中。
使用 page.mouse 在元素的中心或指定的 position 双击。

如果在操作期间的任何时刻元素从 DOM 中分离，此方法将抛出错误。

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

注意

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

dispatch_event

添加于: v1.14

locator.dispatch_event

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

用法

同步
异步

locator.dispatch_event("click")

await locator.dispatch_event("click")

参数

type str #

DOM 事件类型："click"、"dragstart" 等。
event_init EvaluationArgument (可选)#

可选的特定于事件的初始化属性。
timeout float (可选)#

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

返回值

NoneType #

详情

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

在底层，它基于给定的 type 创建事件实例，使用 event_init 属性初始化它，并在元素上派发它。事件默认是 composed、cancelable 和冒泡的。

由于 event_init 是特定于事件的，请参阅事件文档以获取初始属性列表

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

同步
异步

data_transfer = page.evaluate_handle("new DataTransfer()")
locator.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

data_transfer = await page.evaluate_handle("new DataTransfer()")
await locator.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

drag_to

添加于: v1.18

locator.drag_to

将源元素拖动到目标元素并放下。

用法

同步
异步

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

source.drag_to(target)
# or specify exact positions relative to the top-left corners of the elements:
source.drag_to(
  target,
  source_position={"x": 34, "y": 7},
  target_position={"x": 10, "y": 20}
)

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

await source.drag_to(target)
# or specify exact positions relative to the top-left corners of the elements:
await source.drag_to(
  target,
  source_position={"x": 34, "y": 7},
  target_position={"x": 10, "y": 20}
)

参数

target Locator #

要拖动到的元素的定位器。
force bool (可选)#

是否绕过可操作性检查。默认为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
source_position Dict (可选)#
- x float
- y float
单击源元素上相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。
target_position Dict (可选)#
- x float
- y float
在目标元素上相对于元素内边距框左上角的点放下。如果未指定，则使用元素的某个可见点。
timeout float (可选)#

最大时间（毫秒）。默认为 30000 (30 秒)。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)#

设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于等待元素准备好进行操作而无需执行操作。

返回值

NoneType #

详情

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

evaluate

添加于: v1.14

locator.evaluate

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

用法

同步
异步

tweets = page.locator(".tweet .retweets")
assert tweets.evaluate("node => node.innerText") == "10 retweets"

tweets = page.locator(".tweet .retweets")
assert await tweets.evaluate("node => node.innerText") == "10 retweets"

参数

expression str #

要在浏览器上下文中求值的 JavaScript 表达式。如果表达式求值为函数，则会自动调用该函数。
arg EvaluationArgument (可选)#

传递给 expression 的可选参数。
timeout float (可选)#

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

返回值

可序列化 #

详情

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

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

如果 expression 抛出错误或 rejected，此方法也会抛出错误。

evaluate_all

添加于: v1.14

locator.evaluate_all

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

用法

同步
异步

locator = page.locator("div")
more_than_ten = locator.evaluate_all("(divs, min) => divs.length > min", 10)

locator = page.locator("div")
more_than_ten = await locator.evaluate_all("(divs, min) => divs.length > min", 10)

参数

expression str #

要在浏览器上下文中求值的 JavaScript 表达式。如果表达式求值为函数，则会自动调用该函数。
arg EvaluationArgument (可选)#

传递给 expression 的可选参数。

返回值

可序列化 #

详情

返回 expression 的返回值，并以所有匹配元素的数组作为第一个参数，arg 作为第二个参数调用。

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

如果 expression 抛出错误或 rejected，此方法也会抛出错误。

evaluate_handle

添加于: v1.14

locator.evaluate_handle

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

用法

locator.evaluate_handle(expression)
locator.evaluate_handle(expression, **kwargs)

参数

expression str #

要在浏览器上下文中求值的 JavaScript 表达式。如果表达式求值为函数，则会自动调用该函数。
arg EvaluationArgument (可选)#

传递给 expression 的可选参数。
timeout float (可选)#

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

返回值

JSHandle #

详情

返回 expression 的返回值，以 JSHandle 的形式返回，并以匹配的元素作为第一个参数，arg 作为第二个参数调用。

locator.evaluate() 和 locator.evaluate_handle() 之间的唯一区别在于 locator.evaluate_handle() 返回 JSHandle。

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

如果 expression 抛出错误或 rejected，此方法也会抛出错误。

有关更多详细信息，请参阅 page.evaluate_handle()。

fill

添加于: v1.14

locator.fill

为输入字段设置值。

用法

同步
异步

page.get_by_role("textbox").fill("example value")

await page.get_by_role("textbox").fill("example value")

参数

value str #

要为 <input>、<textarea> 或 [contenteditable] 元素设置的值。
force bool (可选)#

是否绕过可操作性检查。默认为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
timeout float (可选)#

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

返回值

NoneType #

详情

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

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

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

filter

新增于版本: v1.22

locator.filter

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

用法

同步
异步

row_locator = page.locator("tr")
# ...
row_locator.filter(has_text="text in column 1").filter(
    has=page.get_by_role("button", name="column 2 button")
).screenshot()

row_locator = page.locator("tr")
# ...
await row_locator.filter(has_text="text in column 1").filter(
    has=page.get_by_role("button", name="column 2 button")
).screenshot()

参数

has Locator (可选)#

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

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

请注意，外部和内部定位器必须属于同一 frame。内部定位器不得包含 FrameLocator。
has_not Locator (可选)新增于版本: v1.33#

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

请注意，外部和内部定位器必须属于同一 frame。内部定位器不得包含 FrameLocator。
has_not_text str | Pattern (可选)新增于版本: v1.33#

匹配在内部某处（可能在子元素或后代元素中）不包含指定文本的元素。当传递 [string] 时，匹配不区分大小写并搜索子字符串。
has_text str | Pattern (可选)#

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

返回值

Locator #

focus

添加于: v1.14

locator.focus

在匹配的元素上调用 focus。

用法

locator.focus()
locator.focus(**kwargs)

参数

timeout float (可选)#

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

返回值

NoneType #

frame_locator

新增于版本: v1.17

locator.frame_locator

当使用 iframe 时，您可以创建一个 frame 定位器，它将进入 iframe 并允许在 iframe 中定位元素

用法

同步
异步

locator = page.frame_locator("iframe").get_by_text("Submit")
locator.click()

locator = page.frame_locator("iframe").get_by_text("Submit")
await locator.click()

参数

selector str #

用于解析 DOM 元素的选择器。

返回值

FrameLocator #

get_attribute

添加于: v1.14

locator.get_attribute

返回匹配元素的属性值。

断言属性

如果您需要断言元素的属性，请优先使用 expect(locator).to_have_attribute() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

locator.get_attribute(name)
locator.get_attribute(name, **kwargs)

参数

name str #

要获取其值的属性名称。
timeout float (可选)#

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

返回值

NoneType | str #

get_by_alt_text

新增于版本: v1.27

locator.get_by_alt_text

允许通过元素的 alt 文本定位元素。

用法

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

<img alt='Playwright logo'>

同步
异步

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

await page.get_by_alt_text("Playwright logo").click()

参数

text str | Pattern #

用于定位元素的文本。
exact bool (可选)#

是否查找完全匹配项：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

get_by_label

新增于版本: v1.27

locator.get_by_label

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

用法

例如，此方法将在以下 DOM 中通过标签“Username”和“Password”找到输入框

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">

同步
异步

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

await page.get_by_label("Username").fill("john")
await page.get_by_label("Password").fill("secret")

参数

text str | Pattern #

用于定位元素的文本。
exact bool (可选)#

是否查找完全匹配项：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

get_by_placeholder

新增于版本: v1.27

locator.get_by_placeholder

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

用法

例如，考虑以下 DOM 结构。

<input type="email" placeholder="[email protected]" />

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

同步
异步

page.get_by_placeholder("[email protected]").fill("[email protected]")

await page.get_by_placeholder("[email protected]").fill("[email protected]")

参数

text str | Pattern #

用于定位元素的文本。
exact bool (可选)#

是否查找完全匹配项：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

get_by_role

新增于版本: v1.27

locator.get_by_role

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

用法

考虑以下 DOM 结构。

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

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

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

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

参数

role "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 角色。
checked bool (可选)#

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

了解更多关于 aria-checked 的信息。
disabled bool (可选)#

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

注意
与大多数其他属性不同，disabled 是通过 DOM 层次结构继承的。了解更多关于 aria-disabled 的信息。
exact bool (可选)添加于: v1.28#

name 是否完全匹配：区分大小写且全字符串匹配。默认为 false。当 name 是正则表达式时忽略。请注意，完全匹配仍然会修剪空格。
expanded bool (可选)#

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

了解更多关于 aria-expanded 的信息。
include_hidden bool (可选)#

控制是否匹配隐藏元素的选项。默认情况下，只有非隐藏元素（如 ARIA 定义）才会被角色选择器匹配。

了解更多关于 aria-hidden 的信息。
level int (可选)#

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

了解更多关于 aria-level 的信息。
name str | Pattern (可选)#

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

了解更多关于可访问名称的信息。
pressed bool (可选)#

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

了解更多关于 aria-pressed 的信息。
selected bool (可选)#

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

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

返回值

Locator #

详情

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

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

get_by_test_id

新增于版本: v1.27

locator.get_by_test_id

按测试 ID 定位元素。

用法

考虑以下 DOM 结构。

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

您可以通过元素的测试 ID 定位该元素

同步
异步

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

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

参数

test_id str | Pattern #

用于定位元素的 ID。

返回值

Locator #

详情

默认情况下，data-testid 属性用作测试 ID。如果需要配置不同的测试 ID 属性，请使用 selectors.set_test_id_attribute()。

get_by_text

新增于版本: v1.27

locator.get_by_text

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

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

用法

考虑以下 DOM 结构

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

您可以按文本子字符串、精确字符串或正则表达式进行定位

同步
异步

# Matches <span>
page.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

# Matches <span>
page.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

参数

text str | Pattern #

用于定位元素的文本。
exact bool (可选)#

是否查找完全匹配项：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

详情

即使使用完全匹配，按文本匹配始终会规范化空格。例如，它将多个空格变成一个空格，将换行符变成空格，并忽略前导和尾随空格。

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

get_by_title

新增于版本: v1.27

locator.get_by_title

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

用法

考虑以下 DOM 结构。

<span title='Issues count'>25 issues</span>

您可以在通过标题文本定位问题计数后检查它

同步
异步

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

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

参数

text str | Pattern #

用于定位元素的文本。
exact bool (可选)#

是否查找完全匹配项：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

highlight

新增于版本: v1.20

locator.highlight

在屏幕上高亮显示相应的元素。用于调试，请勿提交使用 locator.highlight() 的代码。

用法

locator.highlight()

返回值

NoneType #

hover

添加于: v1.14

locator.hover

悬停在匹配的元素之上。

用法

同步
异步

page.get_by_role("link").hover()

await page.get_by_role("link").hover()

参数

force bool (可选)#

是否绕过可操作性检查。默认为 false。
modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前的修饰键。如果未指定，则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。
no_wait_after bool (可选)添加于: v1.28#

已弃用
此选项无效。

此选项无效。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。
timeout float (可选)#

最大时间（毫秒）。默认为 30000 (30 秒)。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)#

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

返回值

NoneType #

详情

此方法通过执行以下步骤悬停在元素之上

等待元素上的可操作性检查，除非设置了 force 选项。
如果需要，将元素滚动到视图中。
使用 page.mouse 悬停在元素的中心或指定的 position 上。

如果在操作期间的任何时刻元素从 DOM 中分离，此方法将抛出错误。

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

inner_html

添加于: v1.14

locator.inner_html

返回 element.innerHTML。

用法

locator.inner_html()
locator.inner_html(**kwargs)

参数

timeout float (可选)#

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

返回值

str #

inner_text

添加于: v1.14

locator.inner_text

返回 element.innerText。

断言文本

如果需要在页面上断言文本，请优先使用 expect(locator).to_have_text() 并使用 use_inner_text 选项以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

locator.inner_text()
locator.inner_text(**kwargs)

参数

timeout float (可选)#

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

返回值

str #

input_value

添加于: v1.14

locator.input_value

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

断言值

如果您需要断言输入值，请优先使用 expect(locator).to_have_value() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

同步
异步

value = page.get_by_role("textbox").input_value()

value = await page.get_by_role("textbox").input_value()

参数

timeout float (可选)#

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

返回值

str #

详情

如果元素不是 input、textarea 或 select，则抛出错误。但是，如果元素位于具有关联 control 的 <label> 元素内，则返回控件的值。

is_checked

添加于: v1.14

locator.is_checked

返回元素是否被选中。如果元素不是复选框或单选输入框，则抛出错误。

断言选中状态

如果您需要断言复选框是否被选中，请优先使用 expect(locator).to_be_checked() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

同步
异步

checked = page.get_by_role("checkbox").is_checked()

checked = await page.get_by_role("checkbox").is_checked()

参数

timeout float (可选)#

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

返回值

bool #

is_disabled

添加于: v1.14

locator.is_disabled

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

断言禁用状态

如果您需要断言元素是否被禁用，请优先使用 expect(locator).to_be_disabled() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

同步
异步

disabled = page.get_by_role("button").is_disabled()

disabled = await page.get_by_role("button").is_disabled()

参数

timeout float (可选)#

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

返回值

bool #

is_editable

添加于: v1.14

locator.is_editable

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

断言可编辑状态

如果您需要断言元素是可编辑的，请优先使用 expect(locator).to_be_editable() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

同步
异步

editable = page.get_by_role("textbox").is_editable()

editable = await page.get_by_role("textbox").is_editable()

参数

timeout float (可选)#

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

返回值

bool #

is_enabled

添加于: v1.14

locator.is_enabled

返回元素是否启用。

断言启用状态

如果您需要断言元素是启用的，请优先使用 expect(locator).to_be_enabled() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

同步
异步

enabled = page.get_by_role("button").is_enabled()

enabled = await page.get_by_role("button").is_enabled()

参数

timeout float (可选)#

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

返回值

bool #

is_hidden

添加于: v1.14

locator.is_hidden

返回元素是否隐藏，与可见状态相反。

断言可见性

如果您需要断言元素是隐藏的，请优先使用 expect(locator).to_be_hidden() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

同步
异步

hidden = page.get_by_role("button").is_hidden()

hidden = await page.get_by_role("button").is_hidden()

参数

timeout float (可选)#

已弃用
此选项将被忽略。locator.is_hidden() 不会等待元素变为隐藏状态，并立即返回。

返回值

bool #

is_visible

添加于: v1.14

locator.is_visible

返回元素是否可见。

断言可见性

如果您需要断言元素是可见的，请优先使用 expect(locator).to_be_visible() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

同步
异步

visible = page.get_by_role("button").is_visible()

visible = await page.get_by_role("button").is_visible()

参数

timeout float (可选)#

已弃用
此选项将被忽略。locator.is_visible() 不会等待元素变为可见状态，并立即返回。

返回值

bool #

locator

添加于: v1.14

locator.locator

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

了解更多关于定位器的信息.

用法

locator.locator(selector_or_locator)
locator.locator(selector_or_locator, **kwargs)

参数

selector_or_locator str | Locator #

用于解析 DOM 元素的选择器或定位器。
has Locator (可选)#

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

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

请注意，外部和内部定位器必须属于同一 frame。内部定位器不得包含 FrameLocator。
has_not Locator (可选)新增于版本: v1.33#

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

请注意，外部和内部定位器必须属于同一 frame。内部定位器不得包含 FrameLocator。
has_not_text str | Pattern (可选)新增于版本: v1.33#

匹配在内部某处（可能在子元素或后代元素中）不包含指定文本的元素。当传递 [string] 时，匹配不区分大小写并搜索子字符串。
has_text str | Pattern (可选)#

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

返回值

Locator #

nth

添加于: v1.14

locator.nth

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

用法

同步
异步

banana = page.get_by_role("listitem").nth(2)

banana = await page.get_by_role("listitem").nth(2)

参数

index int #

返回值

Locator #

or_

新增于版本: v1.33

locator.or_

创建一个定位器，匹配与两个定位器中的一个或两个都匹配的所有元素。

请注意，当两个定位器都匹配某些内容时，生成的定位器将具有多个匹配项，这可能会导致定位器严格性违规。

用法

考虑这样一种情况：您想单击“新邮件”按钮，但有时会出现安全设置对话框。在这种情况下，您可以等待“新邮件”按钮或对话框，并采取相应的措施。

注意

如果“新邮件”按钮和安全对话框都出现在屏幕上，“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()

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

参数

locator Locator #

要匹配的备用定位器。

返回值

Locator #

press

添加于: v1.14

locator.press

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

用法

同步
异步

page.get_by_role("textbox").press("Backspace")

await page.get_by_role("textbox").press("Backspace")

参数

key str #

要按下的键的名称或要生成的字符，例如 ArrowLeft 或 a。
delay float (可选)#

keydown 和 keyup 之间等待的时间，以毫秒为单位。默认为 0。
no_wait_after bool (可选)#

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

启动导航的操作正在等待这些导航发生并等待页面开始加载。您可以通过设置此标志来选择不等待。您只需要在特殊情况下使用此选项，例如导航到无法访问的页面。默认为 false。
timeout float (可选)#

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

返回值

NoneType #

详情

聚焦元素，然后使用 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" 之类的快捷方式。当使用修饰符指定时，在按下后续键时，修饰符会被按下并保持按住状态。

press_sequentially

添加于版本: v1.38

locator.press_sequentially

提示

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

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

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

用法

同步
异步

locator.press_sequentially("hello") # types instantly
locator.press_sequentially("world", delay=100) # types slower, like a user

await locator.press_sequentially("hello") # types instantly
await locator.press_sequentially("world", delay=100) # types slower, like a user

将文本键入到文本字段中，然后提交表单的示例

同步
异步

locator = page.get_by_label("Password")
locator.press_sequentially("my password")
locator.press("Enter")

locator = page.get_by_label("Password")
await locator.press_sequentially("my password")
await locator.press("Enter")

参数

text str #

要顺序按下到聚焦元素中的字符字符串。
delay float (可选)#

按键之间等待的时间，以毫秒为单位。默认为 0。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
timeout float (可选)#

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

返回值

NoneType #

screenshot

添加于: v1.14

locator.screenshot

拍摄与定位器匹配的元素的屏幕截图。

用法

同步
异步

page.get_by_role("link").screenshot()

await page.get_by_role("link").screenshot()

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

同步
异步

page.get_by_role("link").screenshot(animations="disabled", path="link.png")

await page.get_by_role("link").screenshot(animations="disabled", path="link.png")

参数

animations "disabled" | "allow" (可选)#

设置为 "disabled" 时，停止 CSS 动画、CSS 过渡和 Web 动画。动画根据其持续时间获得不同的处理
- 有限动画将快进到完成，因此它们将触发 transitionend 事件。
- 无限动画将被取消到初始状态，然后在屏幕截图后重新播放。
默认为 "allow"，保持动画不变。
caret "hide" | "initial" (可选)#

设置为 "hide" 时，屏幕截图将隐藏文本光标。设置为 "initial" 时，文本光标行为将不会更改。默认为 "hide"。
mask List[Locator] (可选)#

指定在拍摄屏幕截图时应被遮罩的定位器。遮罩的元素将覆盖一个粉红色框 #FF00FF (由 mask_color 自定义)，该框完全覆盖其边界框。
mask_color str (可选)添加于版本: v1.35#

指定遮罩元素的覆盖框的颜色，采用 CSS 颜色格式。默认颜色为粉红色 #FF00FF。
omit_background bool (可选)#

隐藏默认白色背景并允许捕获具有透明度的屏幕截图。不适用于 jpeg 图像。默认为 false。
path Union[str, pathlib.Path] (可选)#

保存图像的文件路径。屏幕截图类型将从文件扩展名推断。如果 path 是相对路径，则相对于当前工作目录解析。如果未提供路径，则图像不会保存到磁盘。
quality int (可选)#

图像质量，介于 0-100 之间。不适用于 png 图像。
scale "css" | "device" (可选)#

设置为 "css" 时，屏幕截图的每个 css 像素将有一个像素。对于高 dpi 设备，这将使屏幕截图保持较小。使用 "device" 选项将为每个设备像素生成一个像素，因此高 dpi 设备的屏幕截图将是两倍甚至更大。

默认为 "device"。
style str (可选)添加于版本: v1.41#

在制作屏幕截图时应用的样式表的文本。您可以在此处隐藏动态元素、使元素不可见或更改其属性，以帮助您创建可重复的屏幕截图。此样式表穿透 Shadow DOM 并应用于内部框架。
timeout float (可选)#

最大时间（毫秒）。默认为 30000 (30 秒)。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
type "png" | "jpeg" (可选)#

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

返回值

bytes #

详情

此方法捕获页面的屏幕截图，裁剪为与定位器匹配的特定元素的大小和位置。如果元素被其他元素覆盖，则它实际上不会在屏幕截图中可见。如果元素是可滚动容器，则只有当前滚动的内容将在屏幕截图中可见。

此方法等待可操作性检查，然后在拍摄屏幕截图之前将元素滚动到视图中。如果元素与 DOM 脱离，则该方法会抛出错误。

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

scroll_into_view_if_needed

添加于: v1.14

locator.scroll_into_view_if_needed

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

有关滚动的替代方法，请参阅滚动。

用法

locator.scroll_into_view_if_needed()
locator.scroll_into_view_if_needed(**kwargs)

参数

timeout float (可选)#

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

返回值

NoneType #

select_option

添加于: v1.14

locator.select_option

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

用法

<select multiple>
  <option value="red">Red</div>
  <option value="green">Green</div>
  <option value="blue">Blue</div>
</select>

同步
异步

# single selection matching the value or label
element.select_option("blue")
# single selection matching the label
element.select_option(label="blue")
# multiple selection for blue, red and second option
element.select_option(value=["red", "green", "blue"])

# single selection matching the value or label
await element.select_option("blue")
# single selection matching the label
await element.select_option(label="blue")
# multiple selection for blue, red and second option
await element.select_option(value=["red", "green", "blue"])

参数

force bool (可选)#

是否绕过可操作性检查。默认为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
timeout float (可选)#

最大时间（毫秒）。默认为 30000 (30 秒)。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
element ElementHandle | List[ElementHandle] (可选)#

要选择的选项元素。可选。
index int | List[int] (可选)#

要按索引选择的选项。可选。
value str | List[str] (可选)#

要按值选择的选项。如果 <select> 具有 multiple 属性，则会选择所有给定的选项，否则仅选择与传递的选项之一匹配的第一个选项。可选。
label str | List[str] (可选)#

要按标签选择的选项。如果 <select> 具有 multiple 属性，则会选择所有给定的选项，否则仅选择与传递的选项之一匹配的第一个选项。可选。

返回值

List[str]#

详情

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

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

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

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

select_text

添加于: v1.14

locator.select_text

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

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

用法

locator.select_text()
locator.select_text(**kwargs)

参数

force bool (可选)#

是否绕过可操作性检查。默认为 false。
timeout float (可选)#

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

返回值

NoneType #

set_checked

添加于版本: v1.15

locator.set_checked

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

用法

同步
异步

page.get_by_role("checkbox").set_checked(True)

await page.get_by_role("checkbox").set_checked(True)

参数

checked bool #

是否选中或取消选中复选框。
force bool (可选)#

是否绕过可操作性检查。默认为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。
timeout float (可选)#

最大时间（毫秒）。默认为 30000 (30 秒)。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)#

设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于等待元素准备好进行操作而无需执行操作。

返回值

NoneType #

详情

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

确保匹配的元素是复选框或单选输入框。否则，此方法将抛出异常。
如果元素已具有正确的选中状态，则此方法立即返回。
等待匹配元素上的可操作性检查，除非设置了 force 选项。如果元素在检查期间分离，则会重试整个操作。
如果需要，将元素滚动到视图中。
使用 page.mouse 在元素的中心单击。
确保元素现在已选中或未选中。否则，此方法将抛出异常。

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

set_input_files

添加于: v1.14

locator.set_input_files

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

用法

同步
异步

# Select one file
page.get_by_label("Upload file").set_input_files('myfile.pdf')

# Select multiple files
page.get_by_label("Upload files").set_input_files(['file1.txt', 'file2.txt'])

# Select a directory
page.get_by_label("Upload directory").set_input_files('mydir')

# Remove all the selected files
page.get_by_label("Upload file").set_input_files([])

# Upload buffer from memory
page.get_by_label("Upload file").set_input_files(
    files=[
        {"name": "test.txt", "mimeType": "text/plain", "buffer": b"this is a test"}
    ],
)

# Select one file
await page.get_by_label("Upload file").set_input_files('myfile.pdf')

# Select multiple files
await page.get_by_label("Upload files").set_input_files(['file1.txt', 'file2.txt'])

# Select a directory
await page.get_by_label("Upload directory").set_input_files('mydir')

# Remove all the selected files
await page.get_by_label("Upload file").set_input_files([])

# Upload buffer from memory
await page.get_by_label("Upload file").set_input_files(
    files=[
        {"name": "test.txt", "mimeType": "text/plain", "buffer": b"this is a test"}
    ],
)

参数

files Union[str, pathlib.Path] | List[Union[str, pathlib.Path]] | Dict | List[Dict]#
- name str
  
  文件名
- mimeType str
  
  文件类型
- buffer bytes
  
  文件内容
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
timeout float (可选)#

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

返回值

NoneType #

详情

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

此方法期望 Locator 指向一个 input 元素。但是，如果元素位于具有关联 control 的 <label> 元素内，则目标将改为该控件。

tap

添加于: v1.14

locator.tap

对与定位器匹配的元素执行点击手势。

用法

locator.tap()
locator.tap(**kwargs)

参数

force bool (可选)#

是否绕过可操作性检查。默认为 false。
modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

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

已弃用
此选项无效。

此选项无效。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。
timeout float (可选)#

最大时间（毫秒）。默认为 30000 (30 秒)。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)#

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

返回值

NoneType #

详情

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

等待元素上的可操作性检查，除非设置了force选项。
如果需要，将元素滚动到视图中。
使用page.touchscreen点击元素的中心，或指定的position。

如果在操作期间的任何时刻元素从 DOM 中分离，此方法将抛出错误。

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

注意

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

text_content

添加于: v1.14

locator.text_content

返回 node.textContent。

断言文本

如果需要在页面上断言文本，请优先使用 expect(locator).to_have_text() 以避免不稳定性。有关更多详细信息，请参阅断言指南。

用法

locator.text_content()
locator.text_content(**kwargs)

参数

timeout float (可选)#

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

返回值

NoneType | str #

uncheck

添加于: v1.14

locator.uncheck

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

用法

同步
异步

page.get_by_role("checkbox").uncheck()

await page.get_by_role("checkbox").uncheck()

参数

force bool (可选)#

是否绕过可操作性检查。默认为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。
timeout float (可选)#

最大时间（毫秒）。默认为 30000 (30 秒)。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)#

设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于等待元素准备好进行操作而无需执行操作。

返回值

NoneType #

详情

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

确保元素是复选框或单选输入框。如果不是，此方法将抛出错误。如果元素已取消选中，此方法将立即返回。
等待元素上的可操作性检查，除非设置了force选项。
如果需要，将元素滚动到视图中。
使用 page.mouse 在元素的中心单击。
确保元素现在未被选中。如果不是，此方法将抛出错误。

如果在操作期间的任何时刻元素从 DOM 中分离，此方法将抛出错误。

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

wait_for

添加于: v1.16

locator.wait_for

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

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

用法

同步
异步

order_sent = page.locator("#order-sent")
order_sent.wait_for()

order_sent = page.locator("#order-sent")
await order_sent.wait_for()

参数

state "attached" | "detached" | "visible" | "hidden" (可选)#

默认为 'visible'。可以是以下之一
- 'attached' - 等待元素出现在 DOM 中。
- 'detached' - 等待元素不出现在 DOM 中。
- 'visible' - 等待元素具有非空的边界框且没有 visibility:hidden。请注意，没有任何内容或 display:none 的元素具有空的边界框，并且不被认为是可见的。
- 'hidden' - 等待元素从 DOM 中分离，或具有空的边界框或 visibility:hidden。这与 'visible' 选项相反。
timeout float (可选)#

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

返回值

NoneType #

属性

content_frame

添加于: v1.43

locator.content_frame

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

当您在某处获得了一个 Locator 对象，并且稍后想要与框架内的内容进行交互时，此功能很有用。

对于反向操作，请使用 frame_locator.owner。

用法

同步
异步

locator = page.locator("iframe[name=\"embedded\"]")
# ...
frame_locator = locator.content_frame
frame_locator.get_by_role("button").click()

locator = page.locator("iframe[name=\"embedded\"]")
# ...
frame_locator = locator.content_frame
await frame_locator.get_by_role("button").click()

返回值

FrameLocator #

first

添加于: v1.14

locator.first

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

用法

locator.first

返回值

Locator #

last

添加于: v1.14

locator.last

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

用法

同步
异步

banana = page.get_by_role("listitem").last

banana = await page.get_by_role("listitem").last

返回值

Locator #

page

添加于: v1.19

locator.page

此定位器所属的页面。

用法

locator.page

返回值

Page #

已弃用

element_handle

添加于: v1.14

locator.element_handle

不推荐使用

始终首选使用 Locator 和 Web 断言，而不是 ElementHandle，因为后者本质上是竞态的。

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

用法

locator.element_handle()
locator.element_handle(**kwargs)

参数

timeout float (可选)#

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

返回值

ElementHandle #

element_handles

添加于: v1.14

locator.element_handles

不推荐使用

始终首选使用 Locator 和 Web 断言，而不是 ElementHandle，因为后者本质上是竞态的。

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

用法

locator.element_handles()

返回值

List[ElementHandle]#

type

添加于: v1.14

locator.type

已弃用

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

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

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

用法

参数

text str #

要键入到焦点元素中的文本。
delay float (可选)#

按键之间等待的时间，以毫秒为单位。默认为 0。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
timeout float (可选)#

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

返回值

NoneType #

方法​

all​

all_inner_texts​

all_text_contents​

and_​

aria_snapshot​

blur​

bounding_box​

check​

clear​

click​

count​

dblclick​

dispatch_event​

drag_to​

evaluate​

evaluate_all​

evaluate_handle​

fill​

filter​

focus​

frame_locator​

get_attribute​

get_by_alt_text​

get_by_label​

get_by_placeholder​

get_by_role​

get_by_test_id​

get_by_text​

get_by_title​

highlight​

hover​

inner_html​

inner_text​

input_value​

is_checked​

is_disabled​

is_editable​

is_enabled​

is_hidden​

is_visible​

locator​

nth​

or_​

press​

press_sequentially​

screenshot​

scroll_into_view_if_needed​

select_option​

select_text​

set_checked​

set_input_files​

tap​

text_content​

uncheck​

wait_for​

属性​

content_frame​

first​

last​

page​

已弃用​

element_handle​

element_handles​

type​

方法

all

all_inner_texts

all_text_contents

and_

aria_snapshot

blur

bounding_box

check

clear

click

count

dblclick

dispatch_event

drag_to

evaluate

evaluate_all

evaluate_handle

fill

filter

focus

frame_locator

get_attribute

get_by_alt_text

get_by_label

get_by_placeholder

get_by_role

get_by_test_id

get_by_text

get_by_title

highlight

hover

inner_html

inner_text

input_value

is_checked

is_disabled

is_editable

is_enabled

is_hidden

is_visible

locator

nth

or_

press

press_sequentially

screenshot

scroll_into_view_if_needed

select_option

select_text

set_checked

set_input_files

tap

text_content

uncheck

wait_for

属性

content_frame

first

last

page

已弃用

element_handle

element_handles

type