跳转到主要内容

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

返回


all_inner_texts

新增于:v1.14 locator.all_inner_texts

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

断言文本

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

用法

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

返回


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

返回


and_

新增于: v1.34 locator.and_

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

用法

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

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

参数

  • locator Locator#

    要匹配的附加定位器。

返回


aria_snapshot

新增于: v1.49 locator.aria_snapshot

捕获给定元素的 aria 快照。阅读有关 aria 快照以及相应的断言 expect(locator).to_match_aria_snapshot() 的更多信息。

用法

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

参数

返回

详情

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

参数

返回


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)

参数

返回

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

参数

  • force bool (可选)#

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

  • no_wait_after bool (可选)#

    已弃用

    此选项无效。

    此选项无效。

  • position Dict (可选)#

    相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。

  • timeout float (可选)#

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

  • trial bool (可选)#

    设置后,此方法仅执行 可操作性 检查并跳过操作。默认为 false。在不执行操作的情况下等待元素准备好进行操作很有用。

返回

详情

执行以下步骤

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

如果在操作期间元素从 DOM 分离,此方法将抛出异常。

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


clear

新增于: v1.28 locator.clear

清除输入字段。

用法

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

参数

返回

详情

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

如果目标元素不是<input><textarea>[contenteditable]元素,此方法将抛出错误。但是,如果元素位于具有关联control<label>元素内,则会清除该控制。


click

新增于:v1.14 locator.click

点击元素。

用法

点击按钮

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

在画布上的特定位置 Shift-右键单击

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 (可选)#

    mousedownmouseup 之间等待的时间(毫秒)。默认为 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 (可选)#

    相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。

  • timeout float (可选)#

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

  • trial bool (可选)#

    设置后,此方法只执行可操作性检查并跳过操作。默认为 false。在不执行操作的情况下等待元素准备好操作非常有用。请注意,无论 trial 如何,键盘 modifiers 都将被按下,以便测试仅在按下这些键时才可见的元素。

返回

详情

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

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

如果在操作期间元素从 DOM 分离,此方法将抛出异常。

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


count

新增于:v1.14 locator.count

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

断言计数

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

用法

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

返回


dblclick

新增于:v1.14 locator.dblclick

双击元素。

用法

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

参数

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

    默认为 left

  • delay float (可选)#

    mousedownmouseup 之间等待的时间(毫秒)。默认为 0。

  • force bool (可选)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

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

  • no_wait_after bool (可选)#

    已弃用

    此选项无效。

    此选项无效。

  • position Dict (可选)#

    相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。

  • timeout float (可选)#

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

  • trial bool (可选)#

    设置后,此方法只执行可操作性检查并跳过操作。默认为 false。在不执行操作的情况下等待元素准备好操作非常有用。请注意,无论 trial 如何,键盘 modifiers 都将被按下,以便测试仅在按下这些键时才可见的元素。

返回

详情

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

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

如果在操作期间元素从 DOM 分离,此方法将抛出异常。

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

注意

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


describe

新增于: v1.53 locator.describe

描述定位器,描述用于跟踪查看器和报告。返回指向相同元素的定位器。

用法

button = page.get_by_test_id("btn-sub").describe("Subscribe button")
button.click()

参数

  • description str#

    定位器描述。

返回


dispatch_event

新增于:v1.14 locator.dispatch_event

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

用法

locator.dispatch_event("click")

参数

返回

详情

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

在底层,它根据给定的 type 创建一个事件实例,用 event_init 属性初始化它,并在元素上分派它。事件默认是 composedcancelable 和冒泡的。

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

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

data_transfer = page.evaluate_handle("new DataTransfer()")
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}
)

参数

  • target Locator#

    要拖动到的元素的定位器。

  • force bool (可选)#

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

  • no_wait_after bool (可选)#

    已弃用

    此选项无效。

    此选项无效。

  • source_position Dict (可选)#

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

  • target_position Dict (可选)#

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

  • timeout float (可选)#

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

  • trial bool (可选)#

    设置后,此方法仅执行 可操作性 检查并跳过操作。默认为 false。在不执行操作的情况下等待元素准备好进行操作很有用。

返回

详情

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


evaluate

新增于:v1.14 locator.evaluate

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

用法

将参数传递给 expression

result = page.get_by_testid("myId").evaluate("(element, [x, y]) => element.textContent + ' ' + x * y", [7, 8])
print(result) # prints "myId text 56"

参数

  • expression str#

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

  • arg EvaluationArgument (可选)#

    传递给 expression 的可选参数。

  • timeout float (可选)#

    在求值之前等待定位器的最长时间(毫秒)。请注意,定位器解析后,求值本身不受超时限制。默认为 30000(30 秒)。传递 0 以禁用超时。

返回

详情

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

如果 expression 返回 Promise,此方法将等待 Promise 解析并返回其值。

如果 expression 抛出或拒绝,此方法将抛出。


evaluate_all

新增于:v1.14 locator.evaluate_all

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

用法

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

参数

  • expression str#

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

  • arg EvaluationArgument (可选)#

    传递给 expression 的可选参数。

返回

详情

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

如果 expression 返回 Promise,此方法将等待 Promise 解析并返回其值。

如果 expression 抛出或拒绝,此方法将抛出。


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 以禁用超时。

返回

详情

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

locator.evaluate()locator.evaluate_handle() 之间唯一的区别是 locator.evaluate_handle() 返回 JSHandle

如果 expression 返回 Promise,此方法将等待 Promise 解析并返回其值。

如果 expression 抛出或拒绝,此方法将抛出。

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


fill

新增于:v1.14 locator.fill

设置输入字段的值。

用法

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

参数

返回

详情

此方法等待可操作性检查,聚焦元素,填充它,并在填充后触发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()

参数

  • has Locator (可选)#

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

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

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

  • has_not Locator (可选)新增于:v1.33#

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

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

  • has_not_text str | Pattern (可选)新增于:v1.33#

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

  • has_text str | Pattern (可选)#

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

  • visible bool (可选)添加于: v1.51#

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

返回


focus

新增于:v1.14 locator.focus

在匹配的元素上调用 focus

用法

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

参数

返回


frame_locator

新增于: v1.17 locator.frame_locator

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

用法

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

参数

  • selector str#

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

返回


get_attribute

新增于:v1.14 locator.get_attribute

返回匹配元素的属性值。

断言属性

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

用法

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

参数

返回


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

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。

返回


get_by_label

新增于:v1.27 locator.get_by_label

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

用法

例如,此方法将在以下 DOM 中通过标签“用户名”和“密码”找到输入

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

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。

返回


get_by_placeholder

新增于:v1.27 locator.get_by_placeholder

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

用法

例如,考虑以下 DOM 结构。

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

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

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

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。

返回


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

参数

  • 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-disableddisabled 设置的属性。

    注意

    与大多数其他属性不同,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 (可选)#

    通常用于角色 headinglistitemrowtreeitem 的数字属性,<h1>-<h6> 元素具有默认值。

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

  • name str | Pattern (可选)#

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

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

  • pressed bool (可选)#

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

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

  • selected bool (可选)#

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

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

返回

详情

角色选择器 不替代 可访问性审计和合规性测试,而是提供有关 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()

参数

返回

详情

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


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

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。

返回

详情

按文本匹配始终会规范化空格,即使是精确匹配也是如此。例如,它会将多个空格转换为一个空格,将换行符转换为空格,并忽略前导和尾随空格。

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


get_by_title

新增于:v1.27 locator.get_by_title

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

用法

考虑以下 DOM 结构。

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

您可以通过 title 文本定位它后检查问题数量

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

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。

返回


highlight

新增于: v1.20 locator.highlight

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

用法

locator.highlight()

返回


hover

新增于:v1.14 locator.hover

将鼠标悬停在匹配的元素上。

用法

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 (可选)#

    相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。

  • timeout float (可选)#

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

  • trial bool (可选)#

    设置后,此方法只执行可操作性检查并跳过操作。默认为 false。在不执行操作的情况下等待元素准备好操作非常有用。请注意,无论 trial 如何,键盘 modifiers 都将被按下,以便测试仅在按下这些键时才可见的元素。

返回

详情

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

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

如果在操作期间元素从 DOM 分离,此方法将抛出异常。

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


inner_html

新增于:v1.14 locator.inner_html

返回 `element.innerHTML`

用法

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

参数

返回


inner_text

新增于:v1.14 locator.inner_text

返回 element.innerText

断言文本

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

用法

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

参数

返回


input_value

新增于:v1.14 locator.input_value

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

断言值

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

用法

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

参数

返回

详情

如果元素不是输入框、文本区域或选择框,则抛出错误。但是,如果元素位于具有关联控制<label>元素内,则返回控制的值。


is_checked

新增于:v1.14 locator.is_checked

返回元素是否已选中。如果元素不是复选框或单选输入,则抛出异常。

断言选中状态

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

用法

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

参数

返回


is_disabled

新增于:v1.14 locator.is_disabled

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

断言禁用状态

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

用法

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

参数

返回


is_editable

新增于:v1.14 locator.is_editable

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

断言可编辑状态

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

用法

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

参数

返回


is_enabled

新增于:v1.14 locator.is_enabled

返回元素是否 启用

断言启用状态

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

用法

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

参数

返回


is_hidden

新增于:v1.14 locator.is_hidden

返回元素是否隐藏,与 可见 相反。

断言可见性

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

用法

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

参数

  • timeout float (可选)#

    已弃用

    此选项被忽略。locator.is_hidden() 不会等待元素变为隐藏并立即返回。

返回


is_visible

新增于:v1.14 locator.is_visible

返回元素是否可见

断言可见性

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

用法

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

参数

返回


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 (可选)#

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

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

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

  • has_not Locator (可选)新增于:v1.33#

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

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

  • has_not_text str | Pattern (可选)新增于:v1.33#

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

  • has_text str | Pattern (可选)#

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

返回


nth

新增于:v1.14 locator.nth

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

用法

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

参数

返回


or_

新增于:v1.33 locator.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()

参数

  • locator Locator#

    要匹配的替代定位器。

返回


press

新增于:v1.14 locator.press

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

用法

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

参数

  • key str#

    要按下的键的名称或要生成的字符,例如 ArrowLefta

  • delay float (可选)#

    keydownkeyup 之间等待的时间(毫秒)。默认为 0。

  • no_wait_after bool (可选)#

    已弃用

    此选项将来默认为 true

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

  • timeout float (可选)#

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

返回

详情

聚焦元素,然后使用 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 等。

还支持以下修改快捷方式:ShiftControlAltMetaShiftLeftControlOrMetaControlOrMeta 在 Windows 和 Linux 上解析为 Control,在 macOS 上解析为 Meta

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

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

也支持快捷键,例如 key: "Control+o"key: "Control++key: "Control+Shift+T"。当与修饰符一起指定时,修饰符在按下后续键时被按下并保持。


press_sequentially

新增于: v1.38 locator.press_sequentially
提示

在大多数情况下,您应该改用 locator.fill()。只有当页面上有特殊的键盘处理时,您才需要一个接一个地按键。

聚焦元素,然后为文本中的每个字符发送一个 keydownkeypress/inputkeyup 事件。

要按特殊键,例如 ControlArrowDown,请使用 locator.press()

用法

locator.press_sequentially("hello") # types instantly
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")

参数

  • text str#

    要顺序按入聚焦元素的字符字符串。

  • delay float (可选)#

    按键之间等待的时间,以毫秒为单位。默认为 0。

  • no_wait_after bool (可选)#

    已弃用

    此选项无效。

    此选项无效。

  • timeout float (可选)#

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

返回


screenshot

新增于:v1.14 locator.screenshot

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

用法

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

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

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 列表[定位符] (可选)#

    指定截屏时需要遮罩的定位符。被遮罩的元素将被一个粉色方框#FF00FF覆盖(可通过mask_color自定义),完全覆盖其边界框。遮罩也适用于不可见元素,请参阅仅匹配可见元素以禁用此功能。

  • mask_color str (可选)添加于:v1.35#

    指定遮盖元素的覆盖框颜色,采用 CSS 颜色格式。默认颜色为粉红色 #FF00FF

  • omit_background 布尔值 (可选)#

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

  • path 联合[字符串, pathlib.Path] (可选)#

    保存图像的文件路径。截图类型将根据文件扩展名推断。如果path是相对路径,则它相对于当前工作目录解析。如果没有提供路径,图像将不会保存到磁盘。

  • quality 整数 (可选)#

    图像质量,介于 0-100 之间。不适用于 png 图像。

  • scale "css" | "device" (可选)#

    设置为"css"时,截图中页面的每个CSS像素将对应一个物理像素。对于高DPI设备,这将使截图文件较小。使用"device"选项将使每个设备像素对应一个物理像素,因此高DPI设备的截图将是两倍甚至更大。

    默认为 "device"

  • style str (可选)新增于: v1.41#

    截屏时应用的样式表文本。您可以在此处隐藏动态元素,使元素不可见或更改其属性以帮助您创建可重复的截图。此样式表会穿透 Shadow DOM 并应用于内部框架。

  • timeout 浮点数 (可选)#

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

  • type "png" | "jpeg" (可选)#

    指定截图类型,默认为 png

返回

详情

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

此方法等待可操作性检查,然后在截图之前将元素滚动到视图中。如果元素从 DOM 中分离,该方法将抛出错误。

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


scroll_into_view_if_needed

新增于:v1.14 locator.scroll_into_view_if_needed

此方法等待可操作性检查,然后尝试将元素滚动到视图中,除非它根据IntersectionObserverratio定义为完全可见。

有关其他滚动方式,请参阅滚动

用法

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

参数

返回


select_option

新增于:v1.14 locator.select_option

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

用法

<select multiple>
<option value="red">Red</option>
<option value="green">Green</option>
<option value="blue">Blue</option>
</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"])

参数

返回

详情

此方法等待可操作性检查,等待直到所有指定选项都存在于<select>元素中并选择这些选项。

如果目标元素不是<select>元素,此方法将抛出错误。但是,如果元素位于具有关联控件<label>元素内部,则将使用该控件代替。

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

一旦所有提供的选项都已选中,将触发 changeinput 事件。


select_text

新增于:v1.14 locator.select_text

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

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

用法

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

参数

返回


set_checked

新增于: v1.15 locator.set_checked

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

用法

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

参数

  • checked 布尔值#

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

  • force 布尔值 (可选)#

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

  • no_wait_after 布尔值 (可选)#

    已弃用

    此选项无效。

    此选项无效。

  • position 字典 (可选)#

    相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。

  • timeout 浮点数 (可选)#

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

  • trial 布尔值 (可选)#

    设置后,此方法仅执行 可操作性 检查并跳过操作。默认为 false。在不执行操作的情况下等待元素准备好进行操作很有用。

返回

详情

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

  1. 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出错误。
  2. 如果元素已经处于正确的选中状态,此方法将立即返回。
  3. 对匹配的元素执行可操作性检查,除非设置了force选项。如果在检查过程中元素被分离,整个操作将重试。
  4. 如果需要,将元素滚动到视图中。
  5. 使用 page.mouse 点击元素中心。
  6. 确保元素现在已选中或未选中。如果不是,此方法将抛出异常。

如果所有步骤在指定的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"}
],
)

参数

返回

详情

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

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


tap

新增于:v1.14 locator.tap

在匹配定位符的元素上执行轻触手势。有关通过手动分派触摸事件模拟其他手势的示例,请参阅模拟旧版触摸事件页面。

用法

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

参数

  • force 布尔值 (可选)#

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

  • modifiers 列表["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

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

  • no_wait_after 布尔值 (可选)#

    已弃用

    此选项无效。

    此选项无效。

  • position 字典 (可选)#

    相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。

  • timeout 浮点数 (可选)#

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

  • trial 布尔值 (可选)#

    设置后,此方法只执行可操作性检查并跳过操作。默认为 false。在不执行操作的情况下等待元素准备好操作非常有用。请注意,无论 trial 如何,键盘 modifiers 都将被按下,以便测试仅在按下这些键时才可见的元素。

返回

详情

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

  1. 对元素执行可操作性检查,除非设置了force选项。
  2. 如果需要,将元素滚动到视图中。
  3. 使用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)

参数

返回


uncheck

新增于:v1.14 locator.uncheck

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

用法

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

参数

  • force 布尔值 (可选)#

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

  • no_wait_after 布尔值 (可选)#

    已弃用

    此选项无效。

    此选项无效。

  • position 字典 (可选)#

    相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。

  • timeout 浮点数 (可选)#

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

  • trial 布尔值 (可选)#

    设置后,此方法仅执行 可操作性 检查并跳过操作。默认为 false。在不执行操作的情况下等待元素准备好进行操作很有用。

返回

详情

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

  1. 确保元素是复选框或单选输入。如果不是,此方法将抛出异常。如果元素已经未选中,此方法将立即返回。
  2. 对元素执行可操作性检查,除非设置了force选项。
  3. 如果需要,将元素滚动到视图中。
  4. 使用 page.mouse 点击元素中心。
  5. 确保元素现在未选中。如果不是,此方法将抛出异常。

如果在操作期间元素从 DOM 分离,此方法将抛出异常。

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


wait_for

添加于:v1.16 locator.wait_for

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

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

用法

order_sent = page.locator("#order-sent")
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 浮点数 (可选)#

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

返回


属性

content_frame

新增于: v1.43 locator.content_frame

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

当您在某处获得一个定位符对象,并且之后希望与框架内部的内容进行交互时,这非常有用。

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

用法

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

返回


first

新增于:v1.14 locator.first

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

用法

locator.first

返回


last

新增于:v1.14 locator.last

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

用法

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

返回


page

新增于:v1.19 locator.page

此定位器所属的页面。

用法

locator.page

返回


已弃用

element_handle

新增于:v1.14 locator.element_handle
不推荐

始终优先使用定位符和网页断言,而不是ElementHandle,因为后者本身就存在竞态条件。

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

用法

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

参数

返回


element_handles

新增于:v1.14 locator.element_handles
不推荐

始终优先使用定位符和网页断言,而不是ElementHandle,因为后者本身就存在竞态条件。

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

用法

locator.element_handles()

返回


type

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

在大多数情况下,您应该使用locator.fill()。只有当页面上存在特殊的键盘处理时,您才需要一个接一个地按下按键——在这种情况下,请使用locator.press_sequentially()

聚焦元素,然后为文本中的每个字符发送一个 keydownkeypress/inputkeyup 事件。

要按特殊键,例如 ControlArrowDown,请使用 locator.press()

用法

参数

返回