LocatorAssertions

LocatorAssertions 类提供了一组断言方法，可用于在测试中对 Locator 的状态进行断言。

同步
异步

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

方法

not_to_be_attached

新增于: v1.33

locatorAssertions.not_to_be_attached

与 expect(locator).to_be_attached() 相反。

用法

expect(locator).not_to_be_attached()
expect(locator).not_to_be_attached(**kwargs)

参数

attached bool (可选)#
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_be_checked

新增于: v1.20

locatorAssertions.not_to_be_checked

与 expect(locator).to_be_checked() 相反。

用法

expect(locator).not_to_be_checked()
expect(locator).not_to_be_checked(**kwargs)

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_be_disabled

新增于: v1.20

locatorAssertions.not_to_be_disabled

与 expect(locator).to_be_disabled() 相反。

用法

expect(locator).not_to_be_disabled()
expect(locator).not_to_be_disabled(**kwargs)

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_be_editable

新增于: v1.20

locatorAssertions.not_to_be_editable

与 expect(locator).to_be_editable() 相反。

用法

expect(locator).not_to_be_editable()
expect(locator).not_to_be_editable(**kwargs)

参数

editable bool (可选) 新增于: v1.26#
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_be_empty

新增于: v1.20

locatorAssertions.not_to_be_empty

与 expect(locator).to_be_empty() 相反。

用法

expect(locator).not_to_be_empty()
expect(locator).not_to_be_empty(**kwargs)

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_be_enabled

新增于: v1.20

locatorAssertions.not_to_be_enabled

与 expect(locator).to_be_enabled() 相反。

用法

expect(locator).not_to_be_enabled()
expect(locator).not_to_be_enabled(**kwargs)

参数

enabled bool (可选) 新增于: v1.26#
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_be_focused

新增于: v1.20

locatorAssertions.not_to_be_focused

与 expect(locator).to_be_focused() 相反。

用法

expect(locator).not_to_be_focused()
expect(locator).not_to_be_focused(**kwargs)

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_be_hidden

新增于: v1.20

locatorAssertions.not_to_be_hidden

与 expect(locator).to_be_hidden() 相反。

用法

expect(locator).not_to_be_hidden()
expect(locator).not_to_be_hidden(**kwargs)

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_be_in_viewport

新增于: v1.31

locatorAssertions.not_to_be_in_viewport

与 expect(locator).to_be_in_viewport() 相反。

用法

expect(locator).not_to_be_in_viewport()
expect(locator).not_to_be_in_viewport(**kwargs)

参数

ratio float (可选)#
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_be_visible

新增于: v1.20

locatorAssertions.not_to_be_visible

与 expect(locator).to_be_visible() 相反。

用法

expect(locator).not_to_be_visible()
expect(locator).not_to_be_visible(**kwargs)

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。
visible bool (可选) 新增于: v1.26#

返回值

NoneType #

not_to_contain_class

新增于: v1.52

locatorAssertions.not_to_contain_class

与 expect(locator).to_contain_class() 相反。

用法

expect(locator).not_to_contain_class(expected)
expect(locator).not_to_contain_class(expected, **kwargs)

参数

expected str | List[str]#

期望的类名或正则表达式，或这些的列表。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_contain_text

新增于: v1.20

locatorAssertions.not_to_contain_text

与 expect(locator).to_contain_text() 相反。

用法

expect(locator).not_to_contain_text(expected)
expect(locator).not_to_contain_text(expected, **kwargs)

参数

expected str | Pattern | List[str] | List[Pattern] | List[str | Pattern] 新增于: v1.18#

期望的子字符串或正则表达式，或这些的列表。
ignore_case bool (可选) 新增于: v1.23#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。
use_inner_text bool (可选) 新增于: v1.18#

获取 DOM 节点文本时是否使用 element.innerText 替代 element.textContent。

返回值

NoneType #

not_to_have_accessible_description

新增于: v1.44

locatorAssertions.not_to_have_accessible_description

与 expect(locator).to_have_accessible_description() 相反。

用法

expect(locator).not_to_have_accessible_description(name)
expect(locator).not_to_have_accessible_description(name, **kwargs)

参数

description str | Pattern #

期望的可访问描述。
ignore_case bool (可选)#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_accessible_error_message

新增于: v1.50

locatorAssertions.not_to_have_accessible_error_message

与 expect(locator).to_have_accessible_error_message() 相反。

用法

expect(locator).not_to_have_accessible_error_message(error_message)
expect(locator).not_to_have_accessible_error_message(error_message, **kwargs)

参数

error_message str | Pattern #

期望的可访问错误信息。
ignore_case bool (可选)#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_accessible_name

新增于: v1.44

locatorAssertions.not_to_have_accessible_name

与 expect(locator).to_have_accessible_name() 相反。

用法

expect(locator).not_to_have_accessible_name(name)
expect(locator).not_to_have_accessible_name(name, **kwargs)

参数

name str | Pattern #

期望的可访问名称。
ignore_case bool (可选)#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_attribute

新增于: v1.20

locatorAssertions.not_to_have_attribute

与 expect(locator).to_have_attribute() 相反。

用法

expect(locator).not_to_have_attribute(name, value)
expect(locator).not_to_have_attribute(name, value, **kwargs)

参数

name str 新增于: v1.18#

属性名。
value str | Pattern 新增于: v1.18#

期望的属性值。
ignore_case bool (可选) 新增于: v1.40#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_class

新增于: v1.20

locatorAssertions.not_to_have_class

与 expect(locator).to_have_class() 相反。

用法

expect(locator).not_to_have_class(expected)
expect(locator).not_to_have_class(expected, **kwargs)

参数

expected str | Pattern | List[str] | List[Pattern] | List[str | Pattern] 新增于: v1.18#

期望的类名、正则表达式或这些的列表。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_count

新增于: v1.20

locatorAssertions.not_to_have_count

与 expect(locator).to_have_count() 相反。

用法

expect(locator).not_to_have_count(count)
expect(locator).not_to_have_count(count, **kwargs)

参数

count int 新增于: v1.18#

期望的数量。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_css

新增于: v1.20

locatorAssertions.not_to_have_css

与 expect(locator).to_have_css() 相反。

用法

expect(locator).not_to_have_css(name, value)
expect(locator).not_to_have_css(name, value, **kwargs)

参数

name str 新增于: v1.18#

CSS 属性名。
value str | Pattern 新增于: v1.18#

CSS 属性值。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_id

新增于: v1.20

locatorAssertions.not_to_have_id

与 expect(locator).to_have_id() 相反。

用法

expect(locator).not_to_have_id(id)
expect(locator).not_to_have_id(id, **kwargs)

参数

id str | Pattern 新增于: v1.18#

元素 id。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_js_property

新增于: v1.20

locatorAssertions.not_to_have_js_property

与 expect(locator).to_have_js_property() 相反。

用法

expect(locator).not_to_have_js_property(name, value)
expect(locator).not_to_have_js_property(name, value, **kwargs)

参数

name str 新增于: v1.18#

属性名。
value Any 新增于: v1.18#

属性值。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_role

新增于: v1.44

locatorAssertions.not_to_have_role

与 expect(locator).to_have_role() 相反。

用法

expect(locator).not_to_have_role(role)
expect(locator).not_to_have_role(role, **kwargs)

参数

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 角色。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_text

新增于: v1.20

locatorAssertions.not_to_have_text

与 expect(locator).to_have_text() 相反。

用法

expect(locator).not_to_have_text(expected)
expect(locator).not_to_have_text(expected, **kwargs)

参数

expected str | Pattern | List[str] | List[Pattern] | List[str | Pattern] 新增于: v1.18#

期望的字符串、正则表达式或这些的列表。
ignore_case bool (可选) 新增于: v1.23#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。
use_inner_text bool (可选) 新增于: v1.18#

获取 DOM 节点文本时是否使用 element.innerText 替代 element.textContent。

返回值

NoneType #

not_to_have_value

新增于: v1.20

locatorAssertions.not_to_have_value

与 expect(locator).to_have_value() 相反。

用法

expect(locator).not_to_have_value(value)
expect(locator).not_to_have_value(value, **kwargs)

参数

value str | Pattern 新增于: v1.18#

期望的值。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_have_values

新增于: v1.23

locatorAssertions.not_to_have_values

与 expect(locator).to_have_values() 相反。

用法

expect(locator).not_to_have_values(values)
expect(locator).not_to_have_values(values, **kwargs)

参数

values List[str] | List[Pattern] | List[str | Pattern]#

当前被选中的期望选项。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

not_to_match_aria_snapshot

新增于: v1.49

locatorAssertions.not_to_match_aria_snapshot

与 expect(locator).to_match_aria_snapshot() 相反。

用法

expect(locator).not_to_match_aria_snapshot(expected)
expect(locator).not_to_match_aria_snapshot(expected, **kwargs)

参数

expected str #
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_be_attached

新增于: v1.33

locatorAssertions.to_be_attached

确保 Locator 指向一个已连接到 Document 或 ShadowRoot 的元素。

用法

同步
异步

expect(page.get_by_text("Hidden text")).to_be_attached()

await expect(page.get_by_text("Hidden text")).to_be_attached()

参数

attached bool (可选)#
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_be_checked

新增于: v1.20

locatorAssertions.to_be_checked

确保 Locator 指向一个已选中的 input 元素。

用法

同步
异步

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

参数

checked bool (可选) 新增于: v1.18#

提供要断言的状态。默认断言 input 被选中。当 indeterminate 设置为 true 时，此选项不能使用。
indeterminate bool (可选) 新增于: v1.50#

断言元素处于不确定（混合）状态。仅支持复选框和单选按钮。当 checked 已提供时，此选项不能为 true。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_be_disabled

新增于: v1.20

locatorAssertions.to_be_disabled

确保 Locator 指向一个被禁用的元素。元素如果有 "disabled" 属性或通过 'aria-disabled' 被禁用，则视为禁用。注意，只有原生控件元素如 HTML button、input、select、textarea、option、optgroup 可以通过设置 "disabled" 属性被禁用。其他元素上的 "disabled" 属性会被浏览器忽略。

用法

同步
异步

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

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_be_editable

新增于: v1.20

locatorAssertions.to_be_editable

确保 Locator 指向一个可编辑的元素。

用法

同步
异步

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

参数

editable bool (可选) 新增于: v1.26#
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_be_empty

新增于: v1.20

locatorAssertions.to_be_empty

确保 Locator 指向一个空的可编辑元素，或指向一个没有文本的 DOM 节点。

用法

同步
异步

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

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_be_enabled

新增于: v1.20

locatorAssertions.to_be_enabled

确保 Locator 指向一个可用的元素。

用法

同步
异步

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

参数

enabled bool (可选) 新增于: v1.26#
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_be_focused

新增于: v1.20

locatorAssertions.to_be_focused

确保 Locator 指向一个获得焦点的 DOM 节点。

用法

同步
异步

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

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_be_hidden

新增于: v1.20

locatorAssertions.to_be_hidden

确保 Locator 要么无法定位到任何 DOM 节点，要么定位到一个不可见的节点。

用法

同步
异步

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

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_be_in_viewport

新增于: v1.31

locatorAssertions.to_be_in_viewport

确保 Locator 指向的元素与视口相交，根据 intersection observer API。

用法

同步
异步

from playwright.sync_api import expect

locator = page.get_by_role("button")
# 确保元素至少有一部分与视口相交。
expect(locator).to_be_in_viewport()
# 确保元素完全在视口之外。
expect(locator).not_to_be_in_viewport()
# 确保元素至少有一半与视口相交。
expect(locator).to_be_in_viewport(ratio=0.5)

from playwright.async_api import expect

locator = page.get_by_role("button")
# 确保元素至少有一部分与视口相交。
await expect(locator).to_be_in_viewport()
# 确保元素完全在视口之外。
await expect(locator).not_to_be_in_viewport()
# 确保元素至少有一半与视口相交。
await expect(locator).to_be_in_viewport(ratio=0.5)

参数

ratio float (可选)#

元素与视口相交的最小比例。如果为 0，则元素只要有任意正比例与视口相交即可。默认值为 0。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_be_visible

新增于: v1.20

locatorAssertions.to_be_visible

确保 Locator 指向一个已连接且可见的 DOM 节点。

要检查列表中至少有一个元素可见，可以使用 locator.first。

用法

同步
异步

# 某个具体元素可见。
expect(page.get_by_text("Welcome")).to_be_visible()

# 列表中至少有一个元素可见。
expect(page.get_by_test_id("todo-item").first).to_be_visible()

# 两个元素中至少有一个可见，也可能都可见。
expect(
    page.get_by_role("button", name="Sign in")
    .or_(page.get_by_role("button", name="Sign up"))
    .first
).to_be_visible()

# 某个具体元素可见。
await expect(page.get_by_text("Welcome")).to_be_visible()

# 列表中至少有一个元素可见。
await expect(page.get_by_test_id("todo-item").first).to_be_visible()

# 两个元素中至少有一个可见，也可能都可见。
await expect(
    page.get_by_role("button", name="Sign in")
    .or_(page.get_by_role("button", name="Sign up"))
    .first
).to_be_visible()

参数

timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。
visible bool (可选) 新增于: v1.26#

返回值

NoneType #

to_contain_class

新增于: v1.52

locatorAssertions.to_contain_class

确保 Locator 指向的元素包含指定的 CSS 类。断言值中所有用空格分隔的类名，必须全部存在于 Element.classList 中，顺序不限。

用法

<div class='middle selected row' id='component'></div>

同步
异步

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 属性会与数组中对应的类名进行匹配：

<div class='list'></div>
  <div class='component inactive'></div>
  <div class='component active'></div>
  <div class='component inactive'></div>
</div>

同步
异步

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

参数

expected str | List[str]#

包含期望类名的字符串（用空格分隔），或这些字符串组成的数组，用于断言多个元素。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_contain_text

新增于: v1.20

locatorAssertions.to_contain_text

确保 Locator 指向的元素包含指定文本。计算元素文本内容时会考虑所有嵌套的子元素。你也可以使用正则表达式作为匹配值。

用法

同步
异步

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

如果你传入一个数组作为期望值，断言规则如下：

定位器会解析为一个元素列表。
该列表中的某个子集元素分别包含期望数组中的文本。
匹配的子集元素顺序与期望数组一致。
期望数组中的每个文本值都能被列表中的某个元素匹配到。

例如，考虑如下列表：

<ul>
  <li>Item Text 1</li>
  <li>Item Text 2</li>
  <li>Item Text 3</li>
</ul>

下面是断言的用法示例：

同步
异步

from playwright.sync_api import expect

# ✓ 包含正确的项且顺序正确
expect(page.locator("ul > li")).to_contain_text(["Text 1", "Text 3", "Text 4"])

# ✖ 顺序错误
expect(page.locator("ul > li")).to_contain_text(["Text 3", "Text 2"])

# ✖ 没有任何项包含该文本
expect(page.locator("ul > li")).to_contain_text(["Some 33"])

# ✖ 定位器指向的是外层 ul 元素，而不是列表项
expect(page.locator("ul")).to_contain_text(["Text 3"])

from playwright.async_api import expect

# ✓ 包含正确的项且顺序正确
await expect(page.locator("ul > li")).to_contain_text(["Text 1", "Text 3", "Text 4"])

# ✖ 顺序错误
await expect(page.locator("ul > li")).to_contain_text(["Text 3", "Text 2"])

# ✖ 没有任何项包含该文本
await expect(page.locator("ul > li")).to_contain_text(["Some 33"])

# ✖ 定位器指向的是外层 ul 元素，而不是列表项
await expect(page.locator("ul")).to_contain_text(["Text 3"])

参数

expected str | Pattern | List[str] | List[Pattern] | List[str | Pattern] 新增于: v1.18#

期望的子字符串、正则表达式，或这些的列表。
ignore_case bool (可选) 新增于: v1.23#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。
use_inner_text bool (可选) 新增于: v1.18#

获取 DOM 节点文本时是否使用 element.innerText 替代 element.textContent。

返回值

NoneType #

详情

当 expected 参数为字符串时，Playwright 会在匹配前对实际文本和期望字符串中的空白和换行进行归一化处理。当使用正则表达式时，实际文本会原样匹配。

to_have_accessible_description

新增于: v1.44

locatorAssertions.to_have_accessible_description

确保 Locator 指向的元素具有指定的可访问描述。

用法

同步
异步

locator = page.get_by_test_id("save-button")
expect(locator).to_have_accessible_description("将结果保存到磁盘")

locator = page.get_by_test_id("save-button")
await expect(locator).to_have_accessible_description("将结果保存到磁盘")

参数

description str | Pattern #

期望的可访问描述。
ignore_case bool (可选)#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_accessible_error_message

新增于: v1.50

locatorAssertions.to_have_accessible_error_message

确保 Locator 指向的元素具有指定的 aria errormessage。

用法

同步
异步

locator = page.get_by_test_id("username-input")
expect(locator).to_have_accessible_error_message("用户名为必填项。")

locator = page.get_by_test_id("username-input")
await expect(locator).to_have_accessible_error_message("用户名为必填项。")

参数

error_message str | Pattern #

期望的可访问错误信息。
ignore_case bool (可选)#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_accessible_name

新增于: v1.44

locatorAssertions.to_have_accessible_name

确保 Locator 指向的元素具有指定的可访问名称。

用法

同步
异步

locator = page.get_by_test_id("save-button")
expect(locator).to_have_accessible_name("保存到磁盘")

locator = page.get_by_test_id("save-button")
await expect(locator).to_have_accessible_name("保存到磁盘")

参数

name str | Pattern #

期望的可访问名称。
ignore_case bool (可选)#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_attribute

新增于: v1.20

locatorAssertions.to_have_attribute

确保 Locator 指向的元素具有指定属性。

用法

同步
异步

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

参数

name str 新增于: v1.18#

属性名。
value str | Pattern 新增于: v1.18#

期望的属性值。
ignore_case bool (可选) 新增于: v1.40#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_class

新增于: v1.20

locatorAssertions.to_have_class

确保 Locator 指向的元素具有指定的 CSS 类。当传入字符串时，必须与元素的 class 属性完全匹配。要匹配单个类名，请使用 expect(locator).to_contain_class()。

用法

<div class='middle selected row' id='component'></div>

同步
异步

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

当传入数组时，该方法会断言定位到的元素列表与期望的类名列表一一对应。每个元素的 class 属性会与数组中对应的字符串或正则表达式进行匹配：

同步
异步

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

参数

expected str | Pattern | List[str] | List[Pattern] | List[str | Pattern] 新增于: v1.18#

期望的类名、正则表达式或这些的列表。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_count

新增于: v1.20

locatorAssertions.to_have_count

确保 Locator 解析为精确数量的 DOM 节点。

用法

同步
异步

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)

参数

count int 新增于: v1.18#

期望的数量。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_css

新增于: v1.20

locatorAssertions.to_have_css

确保 Locator 解析为具有指定计算后 CSS 样式的元素。

用法

同步
异步

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

参数

name str 新增于: v1.18#

CSS 属性名。
value str | Pattern 新增于: v1.18#

CSS 属性值。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_id

新增于: v1.20

locatorAssertions.to_have_id

确保 Locator 指向具有指定 DOM 节点 ID 的元素。

用法

同步
异步

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

参数

id str | Pattern 新增于: v1.18#

元素 id。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_js_property

新增于: v1.20

locatorAssertions.to_have_js_property

确保 Locator 指向的元素具有指定的 JavaScript 属性。注意，该属性可以是基本类型，也可以是可序列化的普通 JavaScript 对象。

用法

同步
异步

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)

参数

name str 新增于: v1.18#

属性名。
value Any 新增于: v1.18#

属性值。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_role

新增于: v1.44

locatorAssertions.to_have_role

确保 Locator 指向具有指定 ARIA 角色的元素。

注意，角色匹配是字符串匹配，不考虑 ARIA 角色的继承关系。例如，如果元素的角色为 "switch"，断言其为父类角色 "checkbox" 会失败。

用法

同步
异步

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

参数

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 角色。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_text

新增于: v1.20

locatorAssertions.to_have_text

确保 Locator 指向的元素具有指定文本。计算元素文本内容时会考虑所有嵌套的子元素。你也可以使用正则表达式作为匹配值。

用法

同步
异步

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, .*"))

如果你传入一个数组作为期望值，断言规则如下：

定位器会解析为一个元素列表。
元素数量等于期望数组中的值数量。
列表中的元素文本与期望数组中的值一一对应且顺序一致。

例如，考虑如下列表：

<ul>
  <li>Text 1</li>
  <li>Text 2</li>
  <li>Text 3</li>
</ul>

下面是断言的用法示例：

同步
异步

from playwright.sync_api import expect

# ✓ 包含正确的项且顺序正确
expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text 3"])

# ✖ 顺序错误
expect(page.locator("ul > li")).to_have_text(["Text 3", "Text 2", "Text 1"])

# ✖ 最后一项不匹配
expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text"])

# ✖ 定位器指向的是外层 ul 元素，而不是列表项
expect(page.locator("ul")).to_have_text(["Text 1", "Text 2", "Text 3"])

from playwright.async_api import expect

# ✓ 包含正确的项且顺序正确
await expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text 3"])

# ✖ 顺序错误
await expect(page.locator("ul > li")).to_have_text(["Text 3", "Text 2", "Text 1"])

# ✖ 最后一项不匹配
await expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text"])

# ✖ 定位器指向的是外层 ul 元素，而不是列表项
await expect(page.locator("ul")).to_have_text(["Text 1", "Text 2", "Text 3"])

参数

expected str | Pattern | List[str] | List[Pattern] | List[str | Pattern] 新增于: v1.18#

期望的字符串、正则表达式，或这些的列表。
ignore_case bool (可选) 新增于: v1.23#

是否执行不区分大小写的匹配。ignore_case 选项优先于对应正则表达式的 flag。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。
use_inner_text bool (可选) 新增于: v1.18#

获取 DOM 节点文本时是否使用 element.innerText 替代 element.textContent。

返回值

NoneType #

详情

to_have_value

新增于: v1.20

locatorAssertions.to_have_value

确保 Locator 指向的元素具有指定的输入值。你也可以使用正则表达式作为匹配值。

用法

同步
异步

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

参数

value str | Pattern 新增于: v1.18#

期望的值。
timeout float (可选) 新增于: v1.18#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_have_values

新增于: v1.23

locatorAssertions.to_have_values

确保 Locator 指向一个多选下拉框/组合框（即带有 multiple 属性的 select 元素），并且选中了指定的值。

用法

例如，给定如下元素：

<select id="favorite-colors" multiple>
  <option value="R">红色</option>
  <option value="G">绿色</option>
  <option value="B">蓝色</option>
</select>

同步
异步

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

参数

values List[str] | List[Pattern] | List[str | Pattern]#

当前被选中的期望选项。
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

to_match_aria_snapshot

新增于: v1.49

locatorAssertions.to_match_aria_snapshot

断言目标元素与给定的可访问性快照一致。

用法

同步
异步

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

参数

expected str #
timeout float (可选)#

断言重试的时间，单位为毫秒。默认值为 5000。

返回值

NoneType #

方法​

not_to_be_attached​

not_to_be_checked​

not_to_be_disabled​

not_to_be_editable​

not_to_be_empty​

not_to_be_enabled​

not_to_be_focused​

not_to_be_hidden​

not_to_be_in_viewport​

not_to_be_visible​

not_to_contain_class​

not_to_contain_text​

not_to_have_accessible_description​

not_to_have_accessible_error_message​

not_to_have_accessible_name​

not_to_have_attribute​

not_to_have_class​

not_to_have_count​

not_to_have_css​

not_to_have_id​

not_to_have_js_property​

not_to_have_role​

not_to_have_text​

not_to_have_value​

not_to_have_values​

not_to_match_aria_snapshot​

to_be_attached​

to_be_checked​

to_be_disabled​

to_be_editable​

to_be_empty​

to_be_enabled​

to_be_focused​

to_be_hidden​

to_be_in_viewport​

to_be_visible​

to_contain_class​

to_contain_text​

to_have_accessible_description​

to_have_accessible_error_message​

to_have_accessible_name​

to_have_attribute​

to_have_class​

to_have_count​

to_have_css​

to_have_id​

to_have_js_property​

to_have_role​

to_have_text​

to_have_value​

to_have_values​

to_match_aria_snapshot​

方法

not_to_be_attached

not_to_be_checked

not_to_be_disabled

not_to_be_editable

not_to_be_empty

not_to_be_enabled

not_to_be_focused

not_to_be_hidden

not_to_be_in_viewport

not_to_be_visible

not_to_contain_class

not_to_contain_text

not_to_have_accessible_description

not_to_have_accessible_error_message

not_to_have_accessible_name

not_to_have_attribute

not_to_have_class

not_to_have_count

not_to_have_css

not_to_have_id

not_to_have_js_property

not_to_have_role

not_to_have_text

not_to_have_value

not_to_have_values

not_to_match_aria_snapshot

to_be_attached

to_be_checked

to_be_disabled

to_be_editable

to_be_empty

to_be_enabled

to_be_focused

to_be_hidden

to_be_in_viewport

to_be_visible

to_contain_class

to_contain_text

to_have_accessible_description

to_have_accessible_error_message

to_have_accessible_name

to_have_attribute

to_have_class

to_have_count

to_have_css

to_have_id

to_have_js_property

to_have_role

to_have_text

to_have_value

to_have_values

to_match_aria_snapshot