Skip to main content

Assertions

Playwright 为您提供 Web-First 断言，其中包含用于创建断言的便捷方法，这些断言将等待并重试，直到满足预期条件。

考虑以下示例：

from playwright.sync_api import Page, expect

def test_status_becomes_submitted(page: Page) -> None:
    # ..
    page.locator("#submit-button").click()
    expect(page.locator(".status")).to_have_text("Submitted")

Playwright 将重新测试带有选择器 .status 的节点，直到获取的节点具有 "Submitted" 文本。它将不断重新获取节点并进行检查，直到满足条件或达到超时。您可以将此超时作为选项传递。

默认情况下，断言的超时设置为 5 秒。

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

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_be_checked(**kwargs) 的相反断言。

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

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_be_disabled(**kwargs) 的相反断言。

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

Added in: v1.20
  • editable <bool> Added in: v1.26#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_be_editable(**kwargs) 的相反断言。

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

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_be_empty(**kwargs) 的相反断言。

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

Added in: v1.20
  • enabled <bool> Added in: v1.26#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_be_enabled(**kwargs) 的相反断言。

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

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_be_focused(**kwargs) 的相反断言。

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

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_be_hidden(**kwargs) 的相反断言。

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

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • visible <bool> Added in: v1.26#
  • returns: <NoneType>#

expect(locator).to_be_visible(**kwargs) 的相反断言。

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

Added in: v1.20
  • expected <str|Pattern|List[str|Pattern]> 预期的子字符串或正则表达式或它们的列表。Added in: v1.18#
  • ignore_case <bool> 是否执行不区分大小写的匹配。如果指定了 ignore_case 选项，则它优先于相应的正则表达式标志。Added in: v1.23#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • use_inner_text <bool> 检索 DOM 节点文本时是否使用 element.innerText 而不是 element.textContent。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_contain_text(expected, **kwargs) 的相反断言。

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

Added in: v1.20
  • name <str> 属性名称。Added in: v1.18#
  • value <str|Pattern> 预期的属性值。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_have_attribute(name, value, **kwargs) 的相反断言。

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

Added in: v1.20

expect(locator).to_have_class(expected, **kwargs) 的相反断言。

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

Added in: v1.20
  • count <int> 预期的计数。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_have_count(count, **kwargs) 的相反断言。

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

Added in: v1.20
  • name <str> CSS 属性名称。Added in: v1.18#
  • value <str|Pattern> CSS 属性值。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_have_css(name, value, **kwargs) 的相反断言。

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

Added in: v1.20

expect(locator).to_have_id(id, **kwargs) 的相反断言。

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

Added in: v1.20
  • name <str> 属性名称。Added in: v1.18#
  • value <Any> 属性值。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_have_js_property(name, value, **kwargs) 的相反断言。

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

Added in: v1.20
  • expected <str|Pattern|List[str|Pattern]> 预期的子字符串或正则表达式或它们的列表。Added in: v1.18#
  • ignore_case <bool> 是否执行不区分大小写的匹配。如果指定了 ignore_case 选项，则它优先于相应的正则表达式标志。Added in: v1.23#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • use_inner_text <bool> 检索 DOM 节点文本时是否使用 element.innerText 而不是 element.textContent。Added in: v1.18#
  • returns: <NoneType>#

expect(locator).to_have_text(expected, **kwargs) 的相反断言。

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

Added in: v1.20

expect(locator).to_have_value(value, **kwargs) 的相反断言。

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

Added in: v1.23

expect(locator).to_have_values(values, **kwargs) 的相反断言。

expect(locator).to_be_checked(**kwargs)​

Added in: v1.20
  • checked <bool> Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

确保 Locator 指向已选中的输入。

from playwright.sync_api import expect

locator = page.get_by_label("Subscribe to newsletter")
expect(locator).to_be_checked()

expect(locator).to_be_disabled(**kwargs)​

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

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

expect(locator).to_be_editable(**kwargs)​

Added in: v1.20
  • editable <bool> Added in: v1.26#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

确保 Locator 指向可编辑元素。

from playwright.sync_api import expect

locator = page.get_by_role("textbox")
expect(locator).to_be_editable()

expect(locator).to_be_empty(**kwargs)​

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

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

from playwright.sync_api import expect

locator = page.locator("div.warning")
expect(locator).to_be_empty()

expect(locator).to_be_enabled(**kwargs)​

Added in: v1.20
  • enabled <bool> Added in: v1.26#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

确保 Locator 指向已启用的元素。

from playwright.sync_api import expect

locator = page.locator("button.submit")
expect(locator).to_be_enabled()

expect(locator).to_be_focused(**kwargs)​

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

确保 Locator 指向聚焦的 DOM 节点。

from playwright.sync_api import expect

locator = page.get_by_role("textbox")
expect(locator).to_be_focused()

expect(locator).to_be_hidden(**kwargs)​

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

确保 Locator 要么不解析为任何 DOM 节点，要么解析为 不可见 的节点。

from playwright.sync_api import expect

locator = page.locator('.my-element')
expect(locator).to_be_hidden()

expect(locator).to_be_visible(**kwargs)​

Added in: v1.20
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • visible <bool> Added in: v1.26#
  • returns: <NoneType>#

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

from playwright.sync_api import expect

locator = page.locator('.my-element')
expect(locator).to_be_visible()

expect(locator).to_contain_text(expected, **kwargs)​

Added in: v1.20
  • expected <str|Pattern|List[str|Pattern]> 预期的子字符串或正则表达式或它们的列表。Added in: v1.18#
  • ignore_case <bool> 是否执行不区分大小写的匹配。如果指定了 ignore_case 选项，则它优先于相应的正则表达式标志。Added in: v1.23#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • use_inner_text <bool> 检索 DOM 节点文本时是否使用 element.innerText 而不是 element.textContent。Added in: v1.18#
  • returns: <NoneType>#

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

如果您传递一个数组作为预期值，则期望如下：

  1. Locator 解析为元素列表。
  2. 此列表的 子集 中的元素分别包含预期数组中的文本。
  3. 匹配的元素子集与预期数组具有相同的顺序。
  4. 预期数组中的每个文本值都由列表中的某个元素匹配。

例如，考虑以下列表：

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

让我们看看如何使用断言：

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

expect(locator).to_have_attribute(name, value, **kwargs)​

Added in: v1.20
  • name <str> 属性名称。Added in: v1.18#
  • value <str|Pattern> 预期的属性值。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

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

from playwright.sync_api import expect

locator = page.locator("input")
expect(locator).to_have_attribute("type", "text")

expect(locator).to_have_class(expected, **kwargs)​

Added in: v1.20

确保 Locator 指向具有给定 CSS 类的元素。这需要完全匹配或使用宽松的正则表达式。

<div class='selected row' id='component'></div>
from playwright.sync_api import expect

locator = page.locator("#component")
expect(locator).to_have_class(re.compile(r"selected"))
expect(locator).to_have_class("selected row")

请注意，如果将数组作为预期值传递，则可以断言整个元素列表：

from playwright.sync_api import expect

locator = page.locator("list > .component")
expect(locator).to_have_class(["component", "component selected", "component"])

expect(locator).to_have_count(count, **kwargs)​

Added in: v1.20
  • count <int> 预期数量。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

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

from playwright.sync_api import expect

locator = page.locator("list > .component")
expect(locator).to_have_count(3)

expect(locator).to_have_css(name, value, **kwargs)​

Added in: v1.20
  • name <str> CSS 属性名称。Added in: v1.18#
  • value <str|Pattern> CSS 属性值。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

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

from playwright.sync_api import expect

locator = page.get_by_role("button")
expect(locator).to_have_css("display", "flex")

expect(locator).to_have_id(id, **kwargs)​

Added in: v1.20

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

from playwright.sync_api import expect

locator = page.get_by_role("textbox")
expect(locator).to_have_id("lastname")

expect(locator).to_have_js_property(name, value, **kwargs)​

Added in: v1.20
  • name <str> 属性名称。Added in: v1.18#
  • value <Any> 属性值。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

确保 Locator 指向具有给定 JavaScript 属性的元素。请注意，此属性可以是原始类型，也可以是普通的序列化 JavaScript 对象。

from playwright.sync_api import expect

locator = page.locator(".component")
expect(locator).to_have_js_property("loaded", True)

expect(locator).to_have_text(expected, **kwargs)​

Added in: v1.20
  • expected <str|Pattern|List[str|Pattern]> 预期的子字符串或正则表达式或它们的列表。Added in: v1.18#
  • ignore_case <bool> 是否执行不区分大小写的匹配。如果指定了 ignore_case 选项，则它优先于相应的正则表达式标志。Added in: v1.23#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • use_inner_text <bool> 检索 DOM 节点文本时是否使用 element.innerText 而不是 element.textContent。Added in: v1.18#
  • returns: <NoneType>#

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

如果您传递一个数组作为预期值，则期望如下：

  1. Locator 解析为元素列表。
  2. 元素数量等于数组中预期值的数量。
  3. 列表中的元素具有与预期数组值匹配的文本，按顺序一一对应。

例如，考虑以下列表：

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

让我们看看如何使用断言：

from playwright.sync_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"])

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

expect(locator).to_have_value(value, **kwargs)​

Added in: v1.20

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

expect(locator).to_have_values(values, **kwargs)​

Added in: v1.23

确保 Locator 指向多选/组合框（即具有 multiple 属性的 select），并且选定了指定的值。

例如，给定以下元素：

<select id="favorite-colors" multiple>
  <option value="R">Red</option>
  <option value="G">Green</option>
  <option value="B">Blue</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")])

expect(page).not_to_have_title(title_or_reg_exp, **kwargs)​

Added in: v1.20
  • title_or_reg_exp <str|Pattern> 预期标题或正则表达式。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(page).to_have_title(title_or_reg_exp, **kwargs) 的相反断言。

expect(page).not_to_have_url(url_or_reg_exp, **kwargs)​

Added in: v1.20
  • url_or_reg_exp <str|Pattern> 预期 URL 字符串或正则表达式。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

expect(page).to_have_url(url_or_reg_exp, **kwargs) 的相反断言。

expect(page).to_have_title(title_or_reg_exp, **kwargs)​

Added in: v1.20
  • title_or_reg_exp <str|Pattern> 预期标题或正则表达式。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

确保页面具有给定的标题。

import re
from playwright.sync_api import expect

# ...
expect(page).to_have_title(re.compile(r".*checkout"))

expect(page).to_have_url(url_or_reg_exp, **kwargs)​

Added in: v1.20
  • url_or_reg_exp <str|Pattern> 预期 URL 字符串或正则表达式。Added in: v1.18#
  • timeout <float> 重试断言的时间。Added in: v1.18#
  • returns: <NoneType>#

确保页面导航到给定的 URL。

import re
from playwright.sync_api import expect

# ...
expect(page).to_have_url(re.compile(".*checkout"))

expect(api_response).not_to_be_ok()​

Added in: v1.19

expect(api_response).to_be_ok() 的相反断言。

expect(api_response).to_be_ok()​

Added in: v1.18

确保响应状态代码在 200..299 范围内。

import re
from playwright.sync_api import expect

# ...
expect(response).to_be_ok()