LocatorAssertions
LocatorAssertions 类提供了断言方法,可用于对测试中的 Locator 状态进行断言。
¥The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.
- Sync
- Async
from playwright.sync_api import Page, expect
def test_status_becomes_submitted(page: Page) -> None:
# ..
page.get_by_role("button").click()
expect(page.locator(".status")).to_have_text("Submitted")
from playwright.async_api import Page, expect
async def test_status_becomes_submitted(page: Page) -> None:
# ..
await page.get_by_role("button").click()
await expect(page.locator(".status")).to_have_text("Submitted")
方法
¥Methods
not_to_be_attached
Added in: v1.33与 expect(locator).to_be_attached() 相反。
¥The opposite of expect(locator).to_be_attached().
用法
¥Usage
expect(locator).not_to_be_attached()
expect(locator).not_to_be_attached(**kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_be_checked
Added in: v1.20与 expect(locator).to_be_checked() 相反。
¥The opposite of expect(locator).to_be_checked().
用法
¥Usage
expect(locator).not_to_be_checked()
expect(locator).not_to_be_checked(**kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_be_disabled
Added in: v1.20与 expect(locator).to_be_disabled() 相反。
¥The opposite of expect(locator).to_be_disabled().
用法
¥Usage
expect(locator).not_to_be_disabled()
expect(locator).not_to_be_disabled(**kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_be_editable
Added in: v1.20与 expect(locator).to_be_editable() 相反。
¥The opposite of expect(locator).to_be_editable().
用法
¥Usage
expect(locator).not_to_be_editable()
expect(locator).not_to_be_editable(**kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_be_empty
Added in: v1.20与 expect(locator).to_be_empty() 相反。
¥The opposite of expect(locator).to_be_empty().
用法
¥Usage
expect(locator).not_to_be_empty()
expect(locator).not_to_be_empty(**kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_be_enabled
Added in: v1.20与 expect(locator).to_be_enabled() 相反。
¥The opposite of expect(locator).to_be_enabled().
用法
¥Usage
expect(locator).not_to_be_enabled()
expect(locator).not_to_be_enabled(**kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_be_focused
Added in: v1.20与 expect(locator).to_be_focused() 相反。
¥The opposite of expect(locator).to_be_focused().
用法
¥Usage
expect(locator).not_to_be_focused()
expect(locator).not_to_be_focused(**kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_be_hidden
Added in: v1.20与 expect(locator).to_be_hidden() 相反。
¥The opposite of expect(locator).to_be_hidden().
用法
¥Usage
expect(locator).not_to_be_hidden()
expect(locator).not_to_be_hidden(**kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_be_in_viewport
Added in: v1.31与 expect(locator).to_be_in_viewport() 相反。
¥The opposite of expect(locator).to_be_in_viewport().
用法
¥Usage
expect(locator).not_to_be_in_viewport()
expect(locator).not_to_be_in_viewport(**kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_be_visible
Added in: v1.20与 expect(locator).to_be_visible() 相反。
¥The opposite of expect(locator).to_be_visible().
用法
¥Usage
expect(locator).not_to_be_visible()
expect(locator).not_to_be_visible(**kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_contain_class
Added in: v1.52与 expect(locator).to_contain_class() 相反。
¥The opposite of expect(locator).to_contain_class().
用法
¥Usage
expect(locator).not_to_contain_class(expected)
expect(locator).not_to_contain_class(expected, **kwargs)
参数
¥Arguments
预期的类或 RegExp 或这些的列表。
¥Expected class or RegExp or a list of those.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_contain_text
Added in: v1.20与 expect(locator).to_contain_text() 相反。
¥The opposite of expect(locator).to_contain_text().
用法
¥Usage
expect(locator).not_to_contain_text(expected)
expect(locator).not_to_contain_text(expected, **kwargs)
参数
¥Arguments
预期的子字符串或正则表达式或这些的列表。
¥Expected substring or RegExp or a list of those.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
检索 DOM 节点文本时是否使用 element.innerText
而不是 element.textContent
。
¥Whether to use element.innerText
instead of element.textContent
when retrieving DOM node text.
返回
¥Returns
not_to_have_accessible_description
Added in: v1.44与 expect(locator).to_have_accessible_description() 相反。
¥The opposite of expect(locator).to_have_accessible_description().
用法
¥Usage
expect(locator).not_to_have_accessible_description(name)
expect(locator).not_to_have_accessible_description(name, **kwargs)
参数
¥Arguments
预期可访问描述。
¥Expected accessible description.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_accessible_error_message
Added in: v1.50与 expect(locator).to_have_accessible_error_message() 相反。
¥The opposite of expect(locator).to_have_accessible_error_message().
用法
¥Usage
expect(locator).not_to_have_accessible_error_message(error_message)
expect(locator).not_to_have_accessible_error_message(error_message, **kwargs)
参数
¥Arguments
预期可访问的错误消息。
¥Expected accessible error message.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_accessible_name
Added in: v1.44与 expect(locator).to_have_accessible_name() 相反。
¥The opposite of expect(locator).to_have_accessible_name().
用法
¥Usage
expect(locator).not_to_have_accessible_name(name)
expect(locator).not_to_have_accessible_name(name, **kwargs)
参数
¥Arguments
预期可访问名称。
¥Expected accessible name.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_attribute
Added in: v1.20与 expect(locator).to_have_attribute() 相反。
¥The opposite of expect(locator).to_have_attribute().
用法
¥Usage
expect(locator).not_to_have_attribute(name, value)
expect(locator).not_to_have_attribute(name, value, **kwargs)
参数
¥Arguments
属性名称。
¥Attribute name.
期望的属性值。
¥Expected attribute value.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_class
Added in: v1.20与 expect(locator).to_have_class() 相反。
¥The opposite of expect(locator).to_have_class().
用法
¥Usage
expect(locator).not_to_have_class(expected)
expect(locator).not_to_have_class(expected, **kwargs)
参数
¥Arguments
预期的类或 RegExp 或这些的列表。
¥Expected class or RegExp or a list of those.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_count
Added in: v1.20与 expect(locator).to_have_count() 相反。
¥The opposite of expect(locator).to_have_count().
用法
¥Usage
expect(locator).not_to_have_count(count)
expect(locator).not_to_have_count(count, **kwargs)
参数
¥Arguments
预期计数。
¥Expected count.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_css
Added in: v1.20与 expect(locator).to_have_css() 相反。
¥The opposite of expect(locator).to_have_css().
用法
¥Usage
expect(locator).not_to_have_css(name, value)
expect(locator).not_to_have_css(name, value, **kwargs)
参数
¥Arguments
CSS 属性名称。
¥CSS property name.
CSS 属性值。
¥CSS property value.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_id
Added in: v1.20与 expect(locator).to_have_id() 相反。
¥The opposite of expect(locator).to_have_id().
用法
¥Usage
expect(locator).not_to_have_id(id)
expect(locator).not_to_have_id(id, **kwargs)
参数
¥Arguments
元素 ID。
¥Element id.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_js_property
Added in: v1.20与 expect(locator).to_have_js_property() 相反。
¥The opposite of expect(locator).to_have_js_property().
用法
¥Usage
expect(locator).not_to_have_js_property(name, value)
expect(locator).not_to_have_js_property(name, value, **kwargs)
参数
¥Arguments
属性名称。
¥Property name.
属性值
¥Property value.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_role
Added in: v1.44与 expect(locator).to_have_role() 相反。
¥The opposite of expect(locator).to_have_role().
用法
¥Usage
expect(locator).not_to_have_role(role)
expect(locator).not_to_have_role(role, **kwargs)
参数
¥Arguments
-
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"#所需的咏叹调角色。
¥Required aria role.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_text
Added in: v1.20与 expect(locator).to_have_text() 相反。
¥The opposite of expect(locator).to_have_text().
用法
¥Usage
expect(locator).not_to_have_text(expected)
expect(locator).not_to_have_text(expected, **kwargs)
参数
¥Arguments
预期的字符串或正则表达式或它们的列表。
¥Expected string or RegExp or a list of those.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
检索 DOM 节点文本时是否使用 element.innerText
而不是 element.textContent
。
¥Whether to use element.innerText
instead of element.textContent
when retrieving DOM node text.
返回
¥Returns
not_to_have_value
Added in: v1.20与 expect(locator).to_have_value() 相反。
¥The opposite of expect(locator).to_have_value().
用法
¥Usage
expect(locator).not_to_have_value(value)
expect(locator).not_to_have_value(value, **kwargs)
参数
¥Arguments
期望值。
¥Expected value.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_have_values
Added in: v1.23与 expect(locator).to_have_values() 相反。
¥The opposite of expect(locator).to_have_values().
用法
¥Usage
expect(locator).not_to_have_values(values)
expect(locator).not_to_have_values(values, **kwargs)
参数
¥Arguments
当前选择的预期选项。
¥Expected options currently selected.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
not_to_match_aria_snapshot
Added in: v1.49与 expect(locator).to_match_aria_snapshot() 相反。
¥The opposite of expect(locator).to_match_aria_snapshot().
用法
¥Usage
expect(locator).not_to_match_aria_snapshot(expected)
expect(locator).not_to_match_aria_snapshot(expected, **kwargs)
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_be_attached
Added in: v1.33确保 Locator 指向 connected 指向 Document 或 ShadowRoot 的元素。
¥Ensures that Locator points to an element that is connected to a Document or a ShadowRoot.
用法
¥Usage
- Sync
- Async
expect(page.get_by_text("Hidden text")).to_be_attached()
await expect(page.get_by_text("Hidden text")).to_be_attached()
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_be_checked
Added in: v1.20确保 Locator 指向已检查的输入。
¥Ensures the Locator points to a checked input.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.get_by_label("Subscribe to newsletter")
expect(locator).to_be_checked()
from playwright.async_api import expect
locator = page.get_by_label("Subscribe to newsletter")
await expect(locator).to_be_checked()
参数
¥Arguments
提供要断言的状态。默认检查输入的断言。当 indeterminate 设置为 true 时,不能使用此选项。
¥Provides state to assert for. Asserts for input to be checked by default. This option can't be used when indeterminate is set to true.
断言元素处于不确定(混合)状态。仅支持复选框和单选按钮。当提供 checked 时,此选项不能为真。
¥Asserts that the element is in the indeterminate (mixed) state. Only supported for checkboxes and radio buttons. This option can't be true when checked is provided.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_be_disabled
Added in: v1.20确保 Locator 指向禁用的元素。如果元素具有 "disabled" 属性或通过 'aria-disabled' 禁用,则该元素将被禁用。请注意,只有 HTML button
、input
、select
、textarea
、option
、optgroup
等原生控制元素可以通过设置 "disabled" 属性来禁用。其他元素上的 "disabled" 属性将被浏览器忽略。
¥Ensures the Locator points to a disabled element. Element is disabled if it has "disabled" attribute or is disabled via 'aria-disabled'. Note that only native control elements such as HTML button
, input
, select
, textarea
, option
, optgroup
can be disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored by the browser.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator("button.submit")
expect(locator).to_be_disabled()
from playwright.async_api import expect
locator = page.locator("button.submit")
await expect(locator).to_be_disabled()
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_be_editable
Added in: v1.20确保 Locator 指向可编辑元素。
¥Ensures the Locator points to an editable element.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.get_by_role("textbox")
expect(locator).to_be_editable()
from playwright.async_api import expect
locator = page.get_by_role("textbox")
await expect(locator).to_be_editable()
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_be_empty
Added in: v1.20确保 Locator 指向空的可编辑元素或没有文本的 DOM 节点。
¥Ensures the Locator points to an empty editable element or to a DOM node that has no text.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator("div.warning")
expect(locator).to_be_empty()
from playwright.async_api import expect
locator = page.locator("div.warning")
await expect(locator).to_be_empty()
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_be_enabled
Added in: v1.20确保 Locator 指向启用的元素。
¥Ensures the Locator points to an enabled element.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator("button.submit")
expect(locator).to_be_enabled()
from playwright.async_api import expect
locator = page.locator("button.submit")
await expect(locator).to_be_enabled()
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_be_focused
Added in: v1.20确保 Locator 指向焦点 DOM 节点。
¥Ensures the Locator points to a focused DOM node.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.get_by_role("textbox")
expect(locator).to_be_focused()
from playwright.async_api import expect
locator = page.get_by_role("textbox")
await expect(locator).to_be_focused()
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_be_hidden
Added in: v1.20确保 Locator 不解析为任何 DOM 节点,或者解析为 non-visible 节点。
¥Ensures that Locator either does not resolve to any DOM node, or resolves to a non-visible one.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator('.my-element')
expect(locator).to_be_hidden()
from playwright.async_api import expect
locator = page.locator('.my-element')
await expect(locator).to_be_hidden()
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_be_in_viewport
Added in: v1.31根据 交集监视器 API,确保 Locator 指向与视口相交的元素。
¥Ensures the Locator points to an element that intersects viewport, according to the intersection observer API.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.get_by_role("button")
# Make sure at least some part of element intersects viewport.
expect(locator).to_be_in_viewport()
# Make sure element is fully outside of viewport.
expect(locator).not_to_be_in_viewport()
# Make sure that at least half of the element intersects viewport.
expect(locator).to_be_in_viewport(ratio=0.5)
from playwright.async_api import expect
locator = page.get_by_role("button")
# Make sure at least some part of element intersects viewport.
await expect(locator).to_be_in_viewport()
# Make sure element is fully outside of viewport.
await expect(locator).not_to_be_in_viewport()
# Make sure that at least half of the element intersects viewport.
await expect(locator).to_be_in_viewport(ratio=0.5)
参数
¥Arguments
元素与相交视口的最小比率。如果等于 0
,则元素应以任意正比率与视口相交。默认为 0
。
¥The minimal ratio of the element to intersect viewport. If equals to 0
, then element should intersect viewport at any positive ratio. Defaults to 0
.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_be_visible
Added in: v1.20确保 Locator 指向附加的 visible DOM 节点。
¥Ensures that Locator points to an attached and visible DOM node.
要检查列表中至少有一个元素可见,请使用 locator.first。
¥To check that at least one element from the list is visible, use locator.first.
用法
¥Usage
- Sync
- Async
# A specific element is visible.
expect(page.get_by_text("Welcome")).to_be_visible()
# At least one item in the list is visible.
expect(page.get_by_test_id("todo-item").first).to_be_visible()
# At least one of the two elements is visible, possibly both.
expect(
page.get_by_role("button", name="Sign in")
.or_(page.get_by_role("button", name="Sign up"))
.first
).to_be_visible()
# A specific element is visible.
await expect(page.get_by_text("Welcome")).to_be_visible()
# At least one item in the list is visible.
await expect(page.get_by_test_id("todo-item").first).to_be_visible()
# At least one of the two elements is visible, possibly both.
await expect(
page.get_by_role("button", name="Sign in")
.or_(page.get_by_role("button", name="Sign up"))
.first
).to_be_visible()
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_contain_class
Added in: v1.52确保 Locator 指向具有给定 CSS 类的元素。所有来自断言值的类(以空格分隔)必须以任意顺序出现在 Element.classList 中。
¥Ensures the Locator points to an element with given CSS classes. All classes from the asserted value, separated by spaces, must be present in the Element.classList in any order.
用法
¥Usage
<div class='middle selected row' id='component'></div>
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator("#component")
expect(locator).to_contain_class("middle selected row")
expect(locator).to_contain_class("selected")
expect(locator).to_contain_class("row middle")
from playwright.async_api import expect
locator = page.locator("#component")
await expect(locator).to_contain_class("middle selected row")
await expect(locator).to_contain_class("selected")
await expect(locator).to_contain_class("row middle")
传递数组时,该方法会断言所定位的元素列表与相应的预期类列表匹配。每个元素的 class 属性都会与数组中对应的类进行匹配:
¥When an array is passed, the method asserts that the list of elements located matches the corresponding list of expected class lists. Each element's class attribute is matched against the corresponding class in the array:
<div class='list'></div>
<div class='component inactive'></div>
<div class='component active'></div>
<div class='component inactive'></div>
</div>
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator("list > .component")
await expect(locator).to_contain_class(["inactive", "active", "inactive"])
from playwright.async_api import expect
locator = page.locator("list > .component")
await expect(locator).to_contain_class(["inactive", "active", "inactive"])
参数
¥Arguments
包含预期类名的字符串(以空格分隔),或用于断言多个元素的此类字符串列表。
¥A string containing expected class names, separated by spaces, or a list of such strings to assert multiple elements.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_contain_text
Added in: v1.20确保 Locator 指向包含给定文本的元素。计算元素的文本内容时将考虑所有嵌套元素。你也可以使用正则表达式作为值。
¥Ensures the Locator points to an element that contains the given text. All nested elements will be considered when computing the text content of the element. You can use regular expressions for the value as well.
用法
¥Usage
- Sync
- Async
import re
from playwright.sync_api import expect
locator = page.locator('.title')
expect(locator).to_contain_text("substring")
expect(locator).to_contain_text(re.compile(r"\d messages"))
import re
from playwright.async_api import expect
locator = page.locator('.title')
await expect(locator).to_contain_text("substring")
await expect(locator).to_contain_text(re.compile(r"\d messages"))
如果你传递一个数组作为期望值,则期望为:
¥If you pass an array as an expected value, the expectations are:
-
定位器解析为元素列表。
¥Locator resolves to a list of elements.
-
该列表子集中的元素分别包含预期数组中的文本。
¥Elements from a subset of this list contain text from the expected array, respectively.
-
匹配的元素子集与预期数组具有相同的顺序。
¥The matching subset of elements has the same order as the expected array.
-
预期数组中的每个文本值都与列表中的某个元素匹配。
¥Each text value from the expected array is matched by some element from the list.
例如,考虑以下列表:
¥For example, consider the following list:
<ul>
<li>Item Text 1</li>
<li>Item Text 2</li>
<li>Item Text 3</li>
</ul>
让我们看看如何使用断言:
¥Let's see how we can use the assertion:
- Sync
- Async
from playwright.sync_api import expect
# ✓ Contains the right items in the right order
expect(page.locator("ul > li")).to_contain_text(["Text 1", "Text 3", "Text 4"])
# ✖ Wrong order
expect(page.locator("ul > li")).to_contain_text(["Text 3", "Text 2"])
# ✖ No item contains this text
expect(page.locator("ul > li")).to_contain_text(["Some 33"])
# ✖ Locator points to the outer list element, not to the list items
expect(page.locator("ul")).to_contain_text(["Text 3"])
from playwright.async_api import expect
# ✓ Contains the right items in the right order
await expect(page.locator("ul > li")).to_contain_text(["Text 1", "Text 3", "Text 4"])
# ✖ Wrong order
await expect(page.locator("ul > li")).to_contain_text(["Text 3", "Text 2"])
# ✖ No item contains this text
await expect(page.locator("ul > li")).to_contain_text(["Some 33"])
# ✖ Locator points to the outer list element, not to the list items
await expect(page.locator("ul")).to_contain_text(["Text 3"])
参数
¥Arguments
预期的子字符串或正则表达式或这些的列表。
¥Expected substring or RegExp or a list of those.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
检索 DOM 节点文本时是否使用 element.innerText
而不是 element.textContent
。
¥Whether to use element.innerText
instead of element.textContent
when retrieving DOM node text.
返回
¥Returns
细节
¥Details
当 expected
参数是字符串时,Playwright 将在匹配之前规范实际文本和预期字符串中的空格和换行符。使用正则表达式时,实际文本将按原样进行匹配。
¥When expected
parameter is a string, Playwright will normalize whitespaces and line breaks both in the actual text and in the expected string before matching. When regular expression is used, the actual text is matched as is.
to_have_accessible_description
Added in: v1.44¥Ensures the Locator points to an element with a given accessible description.
用法
¥Usage
- Sync
- Async
locator = page.get_by_test_id("save-button")
expect(locator).to_have_accessible_description("Save results to disk")
locator = page.get_by_test_id("save-button")
await expect(locator).to_have_accessible_description("Save results to disk")
参数
¥Arguments
预期可访问描述。
¥Expected accessible description.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_accessible_error_message
Added in: v1.50确保 Locator 指向具有给定 咏叹调错误消息 的元素。
¥Ensures the Locator points to an element with a given aria errormessage.
用法
¥Usage
- Sync
- Async
locator = page.get_by_test_id("username-input")
expect(locator).to_have_accessible_error_message("Username is required.")
locator = page.get_by_test_id("username-input")
await expect(locator).to_have_accessible_error_message("Username is required.")
参数
¥Arguments
预期可访问的错误消息。
¥Expected accessible error message.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_accessible_name
Added in: v1.44¥Ensures the Locator points to an element with a given accessible name.
用法
¥Usage
- Sync
- Async
locator = page.get_by_test_id("save-button")
expect(locator).to_have_accessible_name("Save to disk")
locator = page.get_by_test_id("save-button")
await expect(locator).to_have_accessible_name("Save to disk")
参数
¥Arguments
预期可访问名称。
¥Expected accessible name.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_attribute
Added in: v1.20确保 Locator 指向具有给定属性的元素。
¥Ensures the Locator points to an element with given attribute.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator("input")
expect(locator).to_have_attribute("type", "text")
from playwright.async_api import expect
locator = page.locator("input")
await expect(locator).to_have_attribute("type", "text")
参数
¥Arguments
属性名称。
¥Attribute name.
期望的属性值。
¥Expected attribute value.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_class
Added in: v1.20确保 Locator 指向具有给定 CSS 类的元素。当提供字符串时,它必须与元素的 class
属性完全匹配。要匹配单个类,请使用 expect(locator).to_contain_class()。
¥Ensures the Locator points to an element with given CSS classes. When a string is provided, it must fully match the element's class
attribute. To match individual classes use expect(locator).to_contain_class().
用法
¥Usage
<div class='middle selected row' id='component'></div>
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator("#component")
expect(locator).to_have_class("middle selected row")
expect(locator).to_have_class(re.compile(r"(^|\\s)selected(\\s|$)"))
from playwright.async_api import expect
locator = page.locator("#component")
await expect(locator).to_have_class("middle selected row")
await expect(locator).to_have_class(re.compile(r"(^|\\s)selected(\\s|$)"))
当传递数组时,该方法断言所定位的元素列表与相应的预期类值列表匹配。每个元素的类属性都与数组中相应的字符串或正则表达式匹配:
¥When an array is passed, the method asserts that the list of elements located matches the corresponding list of expected class values. Each element's class attribute is matched against the corresponding string or regular expression in the array:
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator("list > .component")
expect(locator).to_have_class(["component", "component selected", "component"])
from playwright.async_api import expect
locator = page.locator("list > .component")
await expect(locator).to_have_class(["component", "component selected", "component"])
参数
¥Arguments
预期的类或 RegExp 或这些的列表。
¥Expected class or RegExp or a list of those.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_count
Added in: v1.20确保 Locator 解析为确切数量的 DOM 节点。
¥Ensures the Locator resolves to an exact number of DOM nodes.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator("list > .component")
expect(locator).to_have_count(3)
from playwright.async_api import expect
locator = page.locator("list > .component")
await expect(locator).to_have_count(3)
参数
¥Arguments
预期计数。
¥Expected count.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_css
Added in: v1.20确保 Locator 解析为具有给定计算 CSS 样式的元素。
¥Ensures the Locator resolves to an element with the given computed CSS style.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.get_by_role("button")
expect(locator).to_have_css("display", "flex")
from playwright.async_api import expect
locator = page.get_by_role("button")
await expect(locator).to_have_css("display", "flex")
参数
¥Arguments
CSS 属性名称。
¥CSS property name.
CSS 属性值。
¥CSS property value.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_id
Added in: v1.20确保 Locator 指向具有给定 DOM 节点 ID 的元素。
¥Ensures the Locator points to an element with the given DOM Node ID.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.get_by_role("textbox")
expect(locator).to_have_id("lastname")
from playwright.async_api import expect
locator = page.get_by_role("textbox")
await expect(locator).to_have_id("lastname")
参数
¥Arguments
元素 ID。
¥Element id.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_js_property
Added in: v1.20确保 Locator 指向具有给定 JavaScript 属性的元素。请注意,此属性可以是原始类型,也可以是普通的可序列化 JavaScript 对象。
¥Ensures the Locator points to an element with given JavaScript property. Note that this property can be of a primitive type as well as a plain serializable JavaScript object.
用法
¥Usage
- Sync
- Async
from playwright.sync_api import expect
locator = page.locator(".component")
expect(locator).to_have_js_property("loaded", True)
from playwright.async_api import expect
locator = page.locator(".component")
await expect(locator).to_have_js_property("loaded", True)
参数
¥Arguments
属性名称。
¥Property name.
属性值
¥Property value.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_role
Added in: v1.44确保 Locator 指向具有给定 ARIA 角色 的元素。
¥Ensures the Locator points to an element with a given ARIA role.
请注意,角色匹配为字符串,忽略 ARIA 角色层次结构。例如,在具有子类角色 "switch"
的元素上断言超类角色 "checkbox"
将失败。
¥Note that role is matched as a string, disregarding the ARIA role hierarchy. For example, asserting a superclass role "checkbox"
on an element with a subclass role "switch"
will fail.
用法
¥Usage
- Sync
- Async
locator = page.get_by_test_id("save-button")
expect(locator).to_have_role("button")
locator = page.get_by_test_id("save-button")
await expect(locator).to_have_role("button")
参数
¥Arguments
-
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"#所需的咏叹调角色。
¥Required aria role.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_text
Added in: v1.20确保 Locator 指向具有给定文本的元素。计算元素的文本内容时将考虑所有嵌套元素。你也可以使用正则表达式作为值。
¥Ensures the Locator points to an element with the given text. All nested elements will be considered when computing the text content of the element. You can use regular expressions for the value as well.
用法
¥Usage
- Sync
- Async
import re
from playwright.sync_api import expect
locator = page.locator(".title")
expect(locator).to_have_text(re.compile(r"Welcome, Test User"))
expect(locator).to_have_text(re.compile(r"Welcome, .*"))
import re
from playwright.async_api import expect
locator = page.locator(".title")
await expect(locator).to_have_text(re.compile(r"Welcome, Test User"))
await expect(locator).to_have_text(re.compile(r"Welcome, .*"))
如果你传递一个数组作为期望值,则期望为:
¥If you pass an array as an expected value, the expectations are:
-
定位器解析为元素列表。
¥Locator resolves to a list of elements.
-
元素的数量等于数组中期望值的数量。
¥The number of elements equals the number of expected values in the array.
-
列表中的元素具有按顺序一一匹配预期数组值的文本。
¥Elements from the list have text matching expected array values, one by one, in order.
例如,考虑以下列表:
¥For example, consider the following list:
<ul>
<li>Text 1</li>
<li>Text 2</li>
<li>Text 3</li>
</ul>
让我们看看如何使用断言:
¥Let's see how we can use the assertion:
- Sync
- Async
from playwright.sync_api import expect
# ✓ Has the right items in the right order
expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text 3"])
# ✖ Wrong order
expect(page.locator("ul > li")).to_have_text(["Text 3", "Text 2", "Text 1"])
# ✖ Last item does not match
expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text"])
# ✖ Locator points to the outer list element, not to the list items
expect(page.locator("ul")).to_have_text(["Text 1", "Text 2", "Text 3"])
from playwright.async_api import expect
# ✓ Has the right items in the right order
await expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text 3"])
# ✖ Wrong order
await expect(page.locator("ul > li")).to_have_text(["Text 3", "Text 2", "Text 1"])
# ✖ Last item does not match
await expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text"])
# ✖ Locator points to the outer list element, not to the list items
await expect(page.locator("ul")).to_have_text(["Text 1", "Text 2", "Text 3"])
参数
¥Arguments
预期的字符串或正则表达式或它们的列表。
¥Expected string or RegExp or a list of those.
是否进行不区分大小写的匹配。如果指定,ignore_case 选项优先于相应的正则表达式标志。
¥Whether to perform case-insensitive match. ignore_case option takes precedence over the corresponding regular expression flag if specified.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
检索 DOM 节点文本时是否使用 element.innerText
而不是 element.textContent
。
¥Whether to use element.innerText
instead of element.textContent
when retrieving DOM node text.
返回
¥Returns
细节
¥Details
当 expected
参数是字符串时,Playwright 将在匹配之前规范实际文本和预期字符串中的空格和换行符。使用正则表达式时,实际文本将按原样进行匹配。
¥When expected
parameter is a string, Playwright will normalize whitespaces and line breaks both in the actual text and in the expected string before matching. When regular expression is used, the actual text is matched as is.
to_have_value
Added in: v1.20确保 Locator 指向具有给定输入值的元素。你也可以使用正则表达式作为值。
¥Ensures the Locator points to an element with the given input value. You can use regular expressions for the value as well.
用法
¥Usage
- Sync
- Async
import re
from playwright.sync_api import expect
locator = page.locator("input[type=number]")
expect(locator).to_have_value(re.compile(r"[0-9]"))
import re
from playwright.async_api import expect
locator = page.locator("input[type=number]")
await expect(locator).to_have_value(re.compile(r"[0-9]"))
参数
¥Arguments
期望值。
¥Expected value.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_have_values
Added in: v1.23确保 Locator 指向多选/组合框(即具有 multiple
属性的 select
)并且选择指定的值。
¥Ensures the Locator points to multi-select/combobox (i.e. a select
with the multiple
attribute) and the specified values are selected.
用法
¥Usage
例如,给定以下元素:
¥For example, given the following element:
<select id="favorite-colors" multiple>
<option value="R">Red</option>
<option value="G">Green</option>
<option value="B">Blue</option>
</select>
- Sync
- Async
import re
from playwright.sync_api import expect
locator = page.locator("id=favorite-colors")
locator.select_option(["R", "G"])
expect(locator).to_have_values([re.compile(r"R"), re.compile(r"G")])
import re
from playwright.async_api import expect
locator = page.locator("id=favorite-colors")
await locator.select_option(["R", "G"])
await expect(locator).to_have_values([re.compile(r"R"), re.compile(r"G")])
参数
¥Arguments
当前选择的预期选项。
¥Expected options currently selected.
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns
to_match_aria_snapshot
Added in: v1.49断言目标元素与给定的 可访问性快照 匹配。
¥Asserts that the target element matches the given accessibility snapshot.
用法
¥Usage
- Sync
- Async
page.goto("https://demo.playwright.dev/todomvc/")
expect(page.locator('body')).to_match_aria_snapshot('''
- heading "todos"
- textbox "What needs to be done?"
''')
await page.goto("https://demo.playwright.dev/todomvc/")
await expect(page.locator('body')).to_match_aria_snapshot('''
- heading "todos"
- textbox "What needs to be done?"
''')
参数
¥Arguments
重试断言的时间(以毫秒为单位)。默认为 5000
。
¥Time to retry the assertion for in milliseconds. Defaults to 5000
.
返回
¥Returns