Locator
定位器是 Playwright 自动等待和可重试性的核心部分。简而言之,定位器表示在任何时刻查找页面上一个或多个元素的方式。可以使用 page.locator() 方法创建一个定位器。
方法
all
添加于: v1.29当定位器指向元素列表时,此属性返回一个定位器数组,指向各自的元素。
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();
返回
all_inner_texts
添加于: v1.14返回所有匹配节点的 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()
返回
all_text_contents
添加于: v1.14返回所有匹配节点的 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()
返回
and_
添加于: v1.34创建一个同时匹配此定位器和参数定位器的定位器。
用法
以下示例查找具有特定标题的按钮。
- 同步
- 异步
button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))
button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))
参数
返回
aria_snapshot
添加于: v1.49捕获给定元素的 aria 快照。阅读更多关于 aria 快照 和 expect(locator).to_match_aria_snapshot() 以获取相应的断言。
用法
- 同步
- 异步
page.get_by_role("link").aria_snapshot()
await page.get_by_role("link").aria_snapshot()
参数
-
为每个元素生成符号引用。捕获快照后,可以立即使用
aria-ref=<ref>
定位器在元素上执行操作。 -
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
详情
此方法捕获给定元素的 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在元素上调用 blur。
用法
locator.blur()
locator.blur(**kwargs)
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
bounding_box
添加于: v1.14此方法返回匹配定位器的元素的边界框,如果元素不可见则返回 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)
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
详情
滚动会影响返回的边界框,类似于 Element.getBoundingClientRect。这意味着 x
和/或 y
可能为负值。
子框架中的元素返回相对于主框架的边界框,不同于 Element.getBoundingClientRect。
假设页面是静态的,可以安全地使用边界框坐标执行输入操作。例如,以下代码片段应该会点击元素的中心。
check
添加于: v1.14确保复选框或单选按钮元素被选中。
用法
- 同步
- 异步
page.get_by_role("checkbox").check()
await page.get_by_role("checkbox").check()
参数
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
相对于元素内边距框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。 -
设置后,此方法仅执行 可操作性 检查并跳过实际操作。默认为
false
。当需要等待元素准备好执行操作但不想实际执行时很有用。
返回
详情
执行以下步骤
- 确保元素是复选框或单选输入。如果不是,此方法将抛出错误。如果元素已选中,此方法会立即返回。
- 等待对元素进行 可操作性 检查,除非设置了 force 选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 点击元素的中心。
- 确保元素现在已被选中。如果没有,此方法将抛出错误。
如果在执行操作的任何时候元素从 DOM 中分离,此方法将抛出错误。
如果所有步骤在指定的 timeout 超时时间内未完成,此方法将抛出 TimeoutError 错误。传入零超时禁用此功能。
clear
添加于: v1.28清空输入字段。
用法
- 同步
- 异步
page.get_by_role("textbox").clear()
await page.get_by_role("textbox").clear()
参数
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
详情
此方法等待 可操作性 检查,聚焦元素,清空它,并在清空后触发一个 input
事件。
如果目标元素不是 <input>
、<textarea>
或 [contenteditable]
元素,此方法将抛出错误。但是,如果元素位于具有关联 control 控件的 <label>
元素内部,则将清空该控件。
click
添加于: v1.14点击一个元素。
用法
点击一个按钮
- 同步
- 异步
page.get_by_role("button").click()
await page.get_by_role("button").click()
在 canvas 上的特定位置进行 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
。 -
默认为 1。参见 UIEvent.detail。
-
mousedown
和mouseup
之间等待的时间,单位为毫秒。默认为 0。 -
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后恢复当前修饰键。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
已弃用
此选项将来默认为
true
。启动导航的操作会等待这些导航发生以及页面开始加载。你可以通过设置此标志来选择不等待。你仅在导航到无法访问的页面等特殊情况下才需要此选项。默认为
false
。 -
相对于元素内边距框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。 -
设置后,此方法仅执行 可操作性 检查并跳过实际操作。默认为
false
。当需要等待元素准备好执行操作但不想实际执行时很有用。请注意,无论trial
设置如何,都会按下键盘modifiers
,以允许测试只有在按下这些键时才可见的元素。
返回
详情
此方法通过执行以下步骤点击元素
- 等待对元素进行 可操作性 检查,除非设置了 force 选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 点击元素的中心,或指定的 position 位置。
- 等待启动的导航成功或失败,除非设置了 no_wait_after 选项。
如果在执行操作的任何时候元素从 DOM 中分离,此方法将抛出错误。
如果所有步骤在指定的 timeout 超时时间内未完成,此方法将抛出 TimeoutError 错误。传入零超时禁用此功能。
count
添加于: v1.14返回匹配定位器的元素数量。
如果你需要断言页面上的元素数量,推荐使用 expect(locator).to_have_count() 以避免不稳定。详情请参阅 断言指南。
用法
- 同步
- 异步
count = page.get_by_role("listitem").count()
count = await page.get_by_role("listitem").count()
返回
dblclick
添加于: v1.14双击一个元素。
用法
locator.dblclick()
locator.dblclick(**kwargs)
参数
-
button
"left" | "right" | "middle" (可选)#默认为
left
。 -
mousedown
和mouseup
之间等待的时间,单位为毫秒。默认为 0。 -
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后恢复当前修饰键。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
已弃用
此选项无效。
此选项无效。
-
相对于元素内边距框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。 -
设置后,此方法仅执行 可操作性 检查并跳过实际操作。默认为
false
。当需要等待元素准备好执行操作但不想实际执行时很有用。请注意,无论trial
设置如何,都会按下键盘modifiers
,以允许测试只有在按下这些键时才可见的元素。
返回
详情
此方法通过执行以下步骤双击元素
- 等待对元素进行 可操作性 检查,除非设置了 force 选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 双击元素的中心,或指定的 position 位置。
如果在执行操作的任何时候元素从 DOM 中分离,此方法将抛出错误。
如果所有步骤在指定的 timeout 超时时间内未完成,此方法将抛出 TimeoutError 错误。传入零超时禁用此功能。
element.dblclick()
触发两个 click
事件和一个 dblclick
事件。
dispatch_event
添加于: v1.14以编程方式在匹配的元素上触发事件。
用法
- 同步
- 异步
locator.dispatch_event("click")
await locator.dispatch_event("click")
参数
-
DOM 事件类型:
"click"
,"dragstart"
等。 -
event_init
EvaluationArgument (可选)#可选的事件特定初始化属性。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
详情
上述代码片段在元素上触发 click
事件。无论元素的可见状态如何,都会触发 click
事件。这等同于调用 element.click()。
在底层实现上,它根据给定的 type 类型创建一个事件实例,使用 event_init 属性初始化它,并在元素上触发它。事件默认是 composed
、cancelable
和 `bubble` 的。
由于 event_init 是特定于事件的,请参阅事件文档以获取初始化属性列表
- DeviceMotionEvent
- DeviceOrientationEvent
- DragEvent
- Event
- FocusEvent
- KeyboardEvent
- MouseEvent
- PointerEvent
- TouchEvent
- WheelEvent
如果你希望将实时对象作为属性值传递到事件中,你也可以指定 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将源元素拖动到目标元素并释放它。
用法
- 同步
- 异步
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}
)
参数
-
要拖动到的元素的定位器。
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
点击源元素,相对于元素内边距框左上角的这个点。如果未指定,将使用元素的某个可见点。
-
释放到目标元素,相对于元素内边距框左上角的这个点。如果未指定,将使用元素的某个可见点。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。 -
设置后,此方法仅执行 可操作性 检查并跳过实际操作。默认为
false
。当需要等待元素准备好执行操作但不想实际执行时很有用。
返回
详情
此方法将定位符拖动到另一个目标定位符或目标位置。它将首先移动到源元素,执行一次 mousedown
,然后移动到目标元素或位置并执行一次 mouseup
。
evaluate
添加于: v1.14在页面中执行 JavaScript 代码,并将匹配到的元素作为参数。
用法
参数
-
要在浏览器上下文中执行的 JavaScript 表达式。如果表达式的值是一个函数,该函数将自动调用。
-
arg
EvaluationArgument (可选)#可选参数,用于传递给 expression。
-
在执行评估前等待定位符的最长时间(以毫秒为单位)。注意,在定位符解析后,评估本身不受超时限制。默认为
30000
(30 秒)。传递0
可禁用超时。
返回
详情
返回 expression 的返回值,调用时将匹配到的元素作为第一个参数,并将 arg 作为第二个参数。
如果 expression 返回一个 Promise,此方法将等待该 Promise 解析并返回其值。
如果 expression 抛出异常或被 reject,此方法将抛出异常。
evaluate_all
添加于: v1.14在页面中执行 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)
参数
-
要在浏览器上下文中执行的 JavaScript 表达式。如果表达式的值是一个函数,该函数将自动调用。
-
arg
EvaluationArgument (可选)#可选参数,用于传递给 expression。
返回
详情
返回 expression 的返回值,调用时将所有匹配到的元素的数组作为第一个参数,并将 arg 作为第二个参数。
如果 expression 返回一个 Promise,此方法将等待该 Promise 解析并返回其值。
如果 expression 抛出异常或被 reject,此方法将抛出异常。
evaluate_handle
添加于: v1.14在页面中执行 JavaScript 代码,并将匹配到的元素作为参数,并返回一个包含结果的 JSHandle。
用法
locator.evaluate_handle(expression)
locator.evaluate_handle(expression, **kwargs)
参数
-
要在浏览器上下文中执行的 JavaScript 表达式。如果表达式的值是一个函数,该函数将自动调用。
-
arg
EvaluationArgument (可选)#可选参数,用于传递给 expression。
-
在执行评估前等待定位符的最长时间(以毫秒为单位)。注意,在定位符解析后,评估本身不受超时限制。默认为
30000
(30 秒)。传递0
可禁用超时。
返回
详情
将 expression 的返回值作为 JSHandle 返回,调用时将匹配到的元素作为第一个参数,并将 arg 作为第二个参数。
locator.evaluate() 和 locator.evaluate_handle() 之间唯一的区别在于 locator.evaluate_handle() 返回 JSHandle。
如果 expression 返回一个 Promise,此方法将等待该 Promise 解析并返回其值。
如果 expression 抛出异常或被 reject,此方法将抛出异常。
请参阅 page.evaluate_handle() 获取更多详细信息。
fill
添加于: v1.14设置输入字段的值。
用法
- 同步
- 异步
page.get_by_role("textbox").fill("example value")
await page.get_by_role("textbox").fill("example value")
参数
-
要为
<input>
、<textarea>
或[contenteditable]
元素设置的值。 -
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
详情
此方法等待 可操作性 检查通过,聚焦到元素,填充它,并在填充后触发一个 input
事件。注意,你可以传入一个空字符串来清空输入字段。
如果目标元素不是 <input>
、<textarea>
或 [contenteditable]
元素,此方法将抛出错误。然而,如果元素位于具有关联 控件 的 <label>
元素内,将转而填充该控件。
要发送细粒度的键盘事件,请使用 locator.press_sequentially()。
filter
新增于: v1.22此方法根据选项缩小现有定位符的范围,例如按文本过滤。它可以链式调用进行多次过滤。
用法
- 同步
- 异步
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()
参数
-
将方法结果缩小到包含与此相对定位符匹配的元素的那些结果。例如,具有
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#匹配内部某处(可能在子元素或后代元素中)不包含指定文本的元素。当传入一个 [字符串] 时,匹配不区分大小写并搜索子字符串。
-
匹配内部某处(可能在子元素或后代元素中)包含指定文本的元素。当传入一个 [字符串] 时,匹配不区分大小写并搜索子字符串。例如,
"Playwright"
匹配<article><div>Playwright</div></article>
。 -
只匹配可见或不可见的元素。
返回
focus
添加于: v1.14在匹配到的元素上调用 focus 方法。
用法
locator.focus()
locator.focus(**kwargs)
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
frame_locator
新增于: v1.17使用 iframe 时,你可以创建一个框架定位符 (frame locator),该定位符将进入 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()
参数
返回
get_attribute
添加于: v1.14返回匹配到的元素的属性值。
如果你需要断言元素的属性,首选 expect(locator).to_have_attribute() 以避免不稳定。请参阅 断言指南 获取更多详细信息。
用法
locator.get_attribute(name)
locator.get_attribute(name, **kwargs)
参数
-
用于获取值的属性名称。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
get_by_alt_text
新增于: v1.27允许通过元素的 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()
参数
-
用于定位元素的文本。
-
是否进行精确匹配:区分大小写和整字符串匹配。默认为 false。通过正则表达式定位时忽略。注意,精确匹配仍然会去除空白字符。
返回
get_by_label
新增于: v1.27允许通过关联的 <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")
参数
-
用于定位元素的文本。
-
是否进行精确匹配:区分大小写和整字符串匹配。默认为 false。通过正则表达式定位时忽略。注意,精确匹配仍然会去除空白字符。
返回
get_by_placeholder
新增于: v1.27允许通过占位符文本定位输入元素。
用法
例如,考虑以下 DOM 结构。
<input type="email" placeholder="name@example.com" />
在通过占位符文本定位后,你可以填充输入框。
- 同步
- 异步
page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")
await page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")
参数
-
用于定位元素的文本。
-
是否进行精确匹配:区分大小写和整字符串匹配。默认为 false。通过正则表达式定位时忽略。注意,精确匹配仍然会去除空白字符。
返回
get_by_role
新增于: v1.27允许通过元素的 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 角色。
-
通常由
aria-checked
或原生<input type=checkbox>
控件设置的属性。了解更多关于
aria-checked
。 -
通常由
aria-disabled
或disabled
设置的属性。注意与大多数其他属性不同,
disabled
通过 DOM 层级继承。了解更多关于aria-disabled
。 -
name 是否精确匹配:区分大小写和整字符串匹配。默认为 false。当 name 是正则表达式时忽略。注意,精确匹配仍然会去除空白字符。
-
通常由
aria-expanded
设置的属性。了解更多关于
aria-expanded
。 -
控制是否匹配隐藏元素的选项。默认情况下,角色选择器只匹配非隐藏元素,如 ARIA 定义 的那样。
了解更多关于
aria-hidden
。 -
通常出现在角色
heading
、listitem
、row
、treeitem
的数字属性,<h1>-<h6>
元素有默认值。了解更多关于
aria-level
。 -
匹配 可访问名称 的选项。默认情况下,匹配不区分大小写并搜索子字符串,使用 exact 控制此行为。
了解更多关于 可访问名称。
-
通常由
aria-pressed
设置的属性。了解更多关于
aria-pressed
。 -
通常由
aria-selected
设置的属性。了解更多关于
aria-selected
。
返回
详情
角色选择器 不能取代 可访问性审计和一致性测试,而是提供关于 ARIA 指南的早期反馈。
许多 html 元素具有隐式 定义的角色,该角色会被角色选择器识别。你可以在此处找到所有 支持的角色。ARIA 指南 不推荐 通过将 role
和/或 aria-*
属性设置为默认值来重复隐式角色和属性。
get_by_test_id
新增于: v1.27通过测试 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()
参数
返回
详情
默认情况下,data-testid
属性被用作测试 ID。如有必要,使用 selectors.set_test_id_attribute() 配置不同的测试 ID 属性。
get_by_text
新增于: v1.27允许定位包含给定文本的元素。
另请参阅 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))
参数
-
用于定位元素的文本。
-
是否进行精确匹配:区分大小写和整字符串匹配。默认为 false。通过正则表达式定位时忽略。注意,精确匹配仍然会去除空白字符。
返回
详情
按文本匹配总是会标准化空白字符,即使是精确匹配。例如,它会将多个空格变成一个,将换行符变成空格,并忽略开头和结尾的空白字符。
类型为 button
和 submit
的输入元素按其 value
属性匹配,而不是按文本内容。例如,按文本 "Log in"
定位会匹配 <input type=button value="Log in">
。
get_by_title
新增于: v1.27允许通过元素的 title 属性定位元素。
用法
考虑以下 DOM 结构。
<span title='Issues count'>25 issues</span>
在通过 title 文本定位后,你可以检查 issues 计数。
- 同步
- 异步
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")
参数
-
用于定位元素的文本。
-
是否进行精确匹配:区分大小写和整字符串匹配。默认为 false。通过正则表达式定位时忽略。注意,精确匹配仍然会去除空白字符。
返回
highlight
新增于: v1.20在屏幕上高亮显示相应的元素。对调试很有用,不要提交使用 locator.highlight() 的代码。
用法
locator.highlight()
返回
hover
添加于: v1.14将鼠标悬停在匹配到的元素上。
用法
- 同步
- 异步
page.get_by_role("link").hover()
await page.get_by_role("link").hover()
参数
-
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后恢复当前修饰键。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
no_wait_after
bool (可选)添加于: v1.28#已弃用此选项无效。
此选项无效。
-
相对于元素内边距框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。 -
设置后,此方法仅执行 可操作性 检查并跳过实际操作。默认为
false
。当需要等待元素准备好执行操作但不想实际执行时很有用。请注意,无论trial
设置如何,都会按下键盘modifiers
,以允许测试只有在按下这些键时才可见的元素。
返回
详情
此方法通过执行以下步骤将鼠标悬停在元素上
- 等待对元素进行 可操作性 检查,除非设置了 force 选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 悬停在元素的中心,或指定的 位置。
如果在执行操作的任何时候元素从 DOM 中分离,此方法将抛出错误。
如果在指定的 超时 内未完成所有组合步骤,则此方法将抛出 TimeoutError。传入零超时值将禁用此功能。
inner_html
添加于: v1.14返回 element.innerHTML
的值。
用法
locator.inner_html()
locator.inner_html(**kwargs)
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
inner_text
添加于: v1.14返回 element.innerText
的值。
如果你需要断言页面上的文本,推荐使用 expect(locator).to_have_text() 并带有 use_inner_text 选项,以避免不稳定。详情请参阅 断言指南。
用法
locator.inner_text()
locator.inner_text(**kwargs)
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
input_value
添加于: v1.14返回匹配的 <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()
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
详情
如果元素不是 input、textarea 或 select,则抛出错误。但是,如果元素位于关联 control 的 <label>
元素内,则返回 control 的值。
is_checked
添加于: v1.14返回元素是否被选中。如果元素不是复选框或单选输入框,则抛出错误。
如果你需要断言复选框被选中,建议使用 expect(locator).to_be_checked()
,以避免不稳定。更多详情请参见断言指南。
用法
- 同步
- 异步
checked = page.get_by_role("checkbox").is_checked()
checked = await page.get_by_role("checkbox").is_checked()
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
is_disabled
添加于: v1.14返回元素是否被禁用,与enabled(启用)的状态相反。
如果你需要断言元素被禁用,建议使用 expect(locator).to_be_disabled()
,以避免不稳定。更多详情请参见断言指南。
用法
- 同步
- 异步
disabled = page.get_by_role("button").is_disabled()
disabled = await page.get_by_role("button").is_disabled()
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
is_editable
添加于: v1.14返回元素是否可编辑。如果目标元素不是 <input>
、<textarea>
、<select>
、[contenteditable]
且没有允许 [aria-readonly]
的角色,则此方法将抛出错误。
如果你需要断言元素可编辑,建议使用 expect(locator).to_be_editable()
,以避免不稳定。更多详情请参见断言指南。
用法
- 同步
- 异步
editable = page.get_by_role("textbox").is_editable()
editable = await page.get_by_role("textbox").is_editable()
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
is_enabled
添加于: v1.14返回元素是否启用。
如果你需要断言元素已启用,建议使用 expect(locator).to_be_enabled()
,以避免不稳定。更多详情请参见断言指南。
用法
- 同步
- 异步
enabled = page.get_by_role("button").is_enabled()
enabled = await page.get_by_role("button").is_enabled()
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
is_hidden
添加于: v1.14返回元素是否隐藏,与visible(可见)的状态相反。
如果你需要断言元素被隐藏,建议使用 expect(locator).to_be_hidden()
,以避免不稳定。更多详情请参见断言指南。
用法
- 同步
- 异步
hidden = page.get_by_role("button").is_hidden()
hidden = await page.get_by_role("button").is_hidden()
参数
-
已弃用
此选项将被忽略。locator.is_hidden() 不会等待元素变为隐藏状态,而是立即返回。
返回
is_visible
添加于: v1.14返回元素是否可见。
如果你需要断言元素可见,建议使用 expect(locator).to_be_visible()
,以避免不稳定。更多详情请参见断言指南。
用法
- 同步
- 异步
visible = page.get_by_role("button").is_visible()
visible = await page.get_by_role("button").is_visible()
参数
-
已弃用
此选项将被忽略。locator.is_visible() 不会等待元素变为可见状态,而是立即返回。
返回
locator
添加于: v1.14此方法在 locator 的子树中查找与指定选择器匹配的元素。它也接受过滤选项,类似于 locator.filter() 方法。
用法
locator.locator(selector_or_locator)
locator.locator(selector_or_locator, **kwargs)
参数
-
selector_or_locator
str | Locator#用于解析 DOM 元素的选择器或 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#匹配内部某处(可能在子元素或后代元素中)不包含指定文本的元素。当传入一个 [字符串] 时,匹配不区分大小写并搜索子字符串。
-
匹配内部某处(可能在子元素或后代元素中)包含指定文本的元素。当传入一个 [字符串] 时,匹配不区分大小写并搜索子字符串。例如,
"Playwright"
匹配<article><div>Playwright</div></article>
。
返回
nth
添加于: v1.14返回第 n 个匹配元素的 locator。它是基于零的,nth(0)
选择第一个元素。
用法
- 同步
- 异步
banana = page.get_by_role("listitem").nth(2)
banana = await page.get_by_role("listitem").nth(2)
参数
返回
or_
新增于: v1.33创建一个 locator,匹配两个 locator 中任意一个或同时匹配两个的元素。
请注意,当两个 locator 都匹配到某些元素时,结果 locator 将有多个匹配项,这可能会导致locator 严格模式冲突。
用法
考虑一个场景,你想点击“新邮件”按钮,但有时会弹出一个安全设置对话框。在这种情况下,你可以等待“新邮件”按钮或对话框,然后采取相应的操作。
如果“新邮件”按钮和安全对话框同时出现在屏幕上,“or” locator 将匹配它们两者,可能会抛出“严格模式冲突”错误。在这种情况下,你可以使用 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()
参数
返回
press
添加于: v1.14聚焦匹配的元素并按下组合键。
用法
- 同步
- 异步
page.get_by_role("textbox").press("Backspace")
await page.get_by_role("textbox").press("Backspace")
参数
-
要按下的键的名称或要生成的字符,例如
ArrowLeft
或a
。 -
keydown
和keyup
之间的等待时间,单位为毫秒。默认为 0。 -
已弃用
此选项将来默认为
true
。启动导航的操作会等待这些导航发生以及页面开始加载。你可以通过设置此标志来选择不等待。你仅在导航到无法访问的页面等特殊情况下才需要此选项。默认为
false
。 -
最大超时时间,单位为毫秒。默认为
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
等。
还支持以下修饰键快捷方式: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.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")
参数
-
要按顺序压入聚焦元素的字符串。
-
按键之间的等待时间,单位为毫秒。默认为 0。
-
已弃用
此选项无效。
此选项无效。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
screenshot
添加于: v1.14捕获与 locator 匹配的元素的屏幕截图。
用法
- 同步
- 异步
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 Animations。动画的处理方式取决于其持续时间:- 有限动画会快进到完成,因此会触发
transitionend
事件。 - 无限动画会被取消并回到初始状态,然后在截图后再次播放。
默认为
"allow"
,它保持动画不变。 - 有限动画会快进到完成,因此会触发
-
caret
"hide"
|"initial"
(可选)#设置为
"hide"
时,屏幕截图将隐藏文本插入符号。设置为"initial"
时,文本插入符号的行为不会改变。默认为"hide"
。 -
指定在捕获屏幕截图时应被遮罩的 locator。被遮罩的元素将覆盖一个粉色框
#FF00FF
(由mask_color
自定义),完全覆盖其边界框。遮罩也适用于不可见元素,请参见仅匹配可见元素以禁用此功能。 -
mask_color
str (可选)新增于: v1.35#指定被遮罩元素覆盖框的颜色,使用 CSS 颜色格式。默认颜色为粉色
#FF00FF
。 -
隐藏默认的白色背景,允许捕获具有透明度的屏幕截图。不适用于
jpeg
图像。默认为false
。 -
path
Union[str, pathlib.Path] (可选)#保存图像的文件路径。屏幕截图类型将从文件扩展名推断。如果
path
是相对路径,则相对于当前工作目录解析。如果未提供路径,则图像不会保存到磁盘。 -
图像质量,介于 0-100 之间。不适用于
png
图像。 -
scale
"css"
|"device"
(可选)#设置为
"css"
时,屏幕截图每个 CSS 像素将对应一个物理像素。对于高 DPI 设备,这将保持屏幕截图较小。使用"device"
选项将使每个设备像素对应一个物理像素,因此高 DPI 设备的屏幕截图将是两倍大甚至更大。默认为
"device"
。 -
捕获屏幕截图时要应用的样式表文本。你可以在这里隐藏动态元素、使元素不可见或更改其属性,以帮助创建可重复的屏幕截图。此样式表会穿透 Shadow DOM 并应用于内部框架。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。 -
type
"png"
|"jpeg"
(可选)#指定屏幕截图类型,默认为
png
。
返回
详情
此方法捕获页面的屏幕截图,裁剪到与 locator 匹配的特定元素的大小和位置。如果元素被其他元素覆盖,则在屏幕截图上将不可见。如果元素是可滚动的容器,则屏幕截图上仅显示当前滚动的内容。
此方法会等待可操作性检查通过,然后在捕获屏幕截图之前将元素滚动到视图中。如果元素从 DOM 分离,则方法会抛出错误。
返回包含捕获的屏幕截图的缓冲区。
scroll_into_view_if_needed
添加于: v1.14此方法会等待可操作性检查通过,然后尝试将元素滚动到视图中,除非它已完全可见 (由 IntersectionObserver 的 ratio
定义)。
有关其他滚动方式,请参见滚动。
用法
locator.scroll_into_view_if_needed()
locator.scroll_into_view_if_needed(**kwargs)
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
select_option
添加于: v1.14在 <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"])
# 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"])
参数
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。 -
element
ElementHandle | List[ElementHandle] (可选)#要选择的选项元素。可选。
-
按索引选择的选项。可选。
-
按值选择的选项。如果
<select>
具有multiple
属性,则选择所有给定选项;否则,仅选择与传入选项之一匹配的第一个选项。可选。 -
按标签选择的选项。如果
<select>
具有multiple
属性,则选择所有给定选项;否则,仅选择与传入选项之一匹配的第一个选项。可选。
返回
详情
此方法会等待可操作性检查,等待直到 <select>
元素中出现所有指定的选项,然后选择这些选项。
如果目标元素不是 <select>
元素,此方法会抛出错误。但是,如果元素位于带有关联控件的 <label>
元素内,则会改为使用该控件。
返回已成功选择的选项值数组。
在所有提供的选项都被选择后,触发 change
和 input
事件。
select_text
添加于: v1.14此方法会等待可操作性检查,然后聚焦元素并选择其所有文本内容。
如果元素位于带有关联控件的 <label>
元素内,则会改为聚焦并选择该控件中的文本。
用法
locator.select_text()
locator.select_text(**kwargs)
参数
-
是否绕过 可操作性 检查。默认为
false
。 -
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
set_checked
新增于: v1.15设置复选框或单选元素的状态。
用法
- 同步
- 异步
page.get_by_role("checkbox").set_checked(True)
await page.get_by_role("checkbox").set_checked(True)
参数
-
是否选中或取消选中复选框。
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
相对于元素内边距框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。 -
设置后,此方法仅执行 可操作性 检查并跳过实际操作。默认为
false
。当需要等待元素准备好执行操作但不想实际执行时很有用。
返回
详情
此方法通过执行以下步骤检查或取消选中元素
- 确保匹配的元素是复选框或单选输入框。如果不是,该方法会抛出错误。
- 如果元素已经处于正确的选中状态,该方法会立即返回。
- 等待对匹配元素的可操作性检查,除非设置了force选项。如果在检查过程中元素被分离,则整个操作会重试。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 点击元素的中心。
- 确保元素现在处于选中或未选中状态。如果不是,该方法会抛出错误。
当所有步骤的总耗时超出指定的timeout时,该方法会抛出TimeoutError。传递零作为 timeout 则会禁用此行为。
set_input_files
添加于: v1.14上传一个或多个文件到 <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]# -
已弃用
此选项无效。
此选项无效。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
详情
将文件输入的值设置为这些文件路径或文件。如果某些 filePaths
是相对路径,则它们会相对于当前工作目录解析。如果是空数组,则清除选定的文件。
此方法要求定位器指向一个输入元素。但是,如果该元素位于带有关联控件的 <label>
元素内,则会改为定位该控件。
tap
添加于: v1.14对与定位器匹配的元素执行轻触手势。有关通过手动分派触摸事件模拟其他手势的示例,请参阅模拟传统触摸事件页面。
用法
locator.tap()
locator.tap(**kwargs)
参数
-
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后恢复当前修饰键。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
已弃用
此选项无效。
此选项无效。
-
相对于元素内边距框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。 -
设置后,此方法仅执行 可操作性 检查并跳过实际操作。默认为
false
。当需要等待元素准备好执行操作但不想实际执行时很有用。请注意,无论trial
设置如何,都会按下键盘modifiers
,以允许测试只有在按下这些键时才可见的元素。
返回
详情
此方法通过执行以下步骤轻触元素
- 等待对元素的可操作性检查,除非设置了force选项。
- 如果需要,将元素滚动到视图中。
- 使用page.touchscreen轻触元素的中心,或指定的position。
如果在执行操作的任何时候元素从 DOM 中分离,此方法将抛出错误。
当所有步骤的总耗时超出指定的timeout时,该方法会抛出TimeoutError。传递零作为 timeout 则会禁用此行为。
element.tap()
要求浏览器上下文的 hasTouch
选项设置为 true。
text_content
添加于: v1.14如果你需要断言页面上的文本,推荐使用 expect(locator).to_have_text() 以避免不稳定。详情请参阅 断言指南。
用法
locator.text_content()
locator.text_content(**kwargs)
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
uncheck
添加于: v1.14确保复选框或单选元素未被选中。
用法
- 同步
- 异步
page.get_by_role("checkbox").uncheck()
await page.get_by_role("checkbox").uncheck()
参数
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
相对于元素内边距框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。 -
设置后,此方法仅执行 可操作性 检查并跳过实际操作。默认为
false
。当需要等待元素准备好执行操作但不想实际执行时很有用。
返回
详情
此方法通过执行以下步骤取消选中元素
- 确保元素是复选框或单选输入框。如果不是,该方法会抛出错误。如果元素已经未被选中,该方法会立即返回。
- 等待对元素的可操作性检查,除非设置了force选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 点击元素的中心。
- 确保元素现在未被选中。如果不是,该方法会抛出错误。
如果在执行操作的任何时候元素从 DOM 中分离,此方法将抛出错误。
当所有步骤的总耗时超出指定的timeout时,该方法会抛出TimeoutError。传递零作为 timeout 则会禁用此行为。
wait_for
新增于: v1.16当定位器指定的元素满足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'
选项相反。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
属性
content_frame
新增于: v1.43返回指向与此定位器相同的 iframe
的FrameLocator对象。
当您在某处获得一个定位器对象,并随后希望与框架内部的内容进行交互时非常有用。
对于反向操作,请使用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()
返回
first
添加于: v1.14返回指向第一个匹配元素的定位器。
用法
locator.first
返回
last
添加于: v1.14返回指向最后一个匹配元素的定位器。
用法
- 同步
- 异步
banana = page.get_by_role("listitem").last
banana = await page.get_by_role("listitem").last
返回
page
新增于: v1.19此定位器所属的页面。
用法
locator.page
返回
已弃用
element_handle
添加于: v1.14始终优先使用定位器和 Web 断言,而不是ElementHandle,因为后者天生存在竞态条件。
将给定定位器解析为第一个匹配的 DOM 元素。如果没有匹配的元素,则等待一个。如果多个元素匹配该定位器,则抛出错误。
用法
locator.element_handle()
locator.element_handle(**kwargs)
参数
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回
element_handles
添加于: v1.14始终优先使用定位器和 Web 断言,而不是ElementHandle,因为后者天生存在竞态条件。
将给定定位器解析为所有匹配的 DOM 元素。如果没有匹配的元素,则返回一个空列表。
用法
locator.element_handles()
返回
type
添加于: v1.14在大多数情况下,您应该改用locator.fill()。仅当页面有特殊的键盘处理时,才需要逐个按键,在这种情况下请使用locator.press_sequentially()。
聚焦元素,然后为文本中的每个字符发送一个 keydown
、keypress
/input
和 keyup
事件。
要按下特殊键,例如 Control
或 ArrowDown
,请使用 locator.press()
。
用法
参数
-
要输入到聚焦元素的文本。
-
按键之间的等待时间,单位为毫秒。默认为 0。
-
已弃用
此选项无效。
此选项无效。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传入0
表示禁用超时。默认值可以通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。
返回