Playwright 中 expect 的详细用法指南
概述
在 Playwright 中，expect 是专门用于断言的工具（基于 Jest Expect），主要用于验证页面元素状态、文本内容、URL 等。它支持自动等待和丰富的匹配器，是 Playwright 测试的核心断言方式。
基本语法
expect 通常与定位器（Locator）或页面对象（Page）配合使用，语法为：
expect(定位器/页面对象).匹配器(期望值, 选项)
- 定位器（Locator）：如
page.locator("input")、page.get_by_text("登录")等，用于定位页面元素。 - 匹配器（Matcher）：如
to_be_visible()、to_have_text()等，定义断言的条件。
核心匹配器
1. 元素状态断言
验证元素是否可见、启用、选中、存在等。
| 匹配器 | 作用 | 示例 |
|---|---|---|
to_be_visible() |
元素可见（非 display: none 等） | expect(locator).to_be_visible() |
to_be_hidden() |
元素隐藏 | expect(locator).to_be_hidden() |
to_be_enabled() |
元素启用（非 disabled） | expect(button).to_be_enabled() |
to_be_disabled() |
元素禁用 | expect(input).to_be_disabled() |
to_be_checked() |
复选框 / 单选框被选中 | expect(checkbox).to_be_checked() |
to_be_selected() |
下拉选项被选中 | expect(option).to_be_selected() |
to_exist() |
元素存在于 DOM 中（无论是否可见） | expect(locator).to_exist() |
2. 文本与内容断言
验证元素的文本、输入框的值、属性等。
| 匹配器 | 作用 | 示例 |
|---|---|---|
to_have_text() |
元素文本完全匹配（支持正则） | expect(heading).to_have_text("首页") |
to_contain_text() |
元素文本包含指定内容（支持正则） | expect(p).to_contain_text("欢迎") |
to_have_value() |
输入框的值匹配（适合 input/textarea） | expect(input).to_have_value("test") |
to_have_attribute() |
元素属性匹配（如 href、class） | expect(link).to_have_attribute("href", "/about") |
to_have_class() |
元素包含指定类名 | expect(div).to_have_class("active") |
3. 页面与导航断言
验证页面 URL、标题等。
| 匹配器 | 作用 | 示例 |
|---|---|---|
to_have_url() |
页面 URL 匹配（支持正则 / 部分匹配） | expect(page).to_have_url("https://example.com") |
to_have_title() |
页面标题匹配 | expect(page).to_have_title("示例网站") |
4. 列表与计数断言
验证元素列表的数量、包含关系等。
| 匹配器 | 作用 | 示例 |
|---|---|---|
to_have_count() |
元素列表数量匹配 | expect(page.locator("li")).to_have_count(3) |
to_contain() |
列表包含指定元素（需配合 all()） | expect(await locator.all_text_contents()).to_contain("item1") |
反向断言（否定条件）
在匹配器前加 not_ 即可断言 "不满足条件"，例如：
# 断言元素不可见
expect(locator).not_to_be_visible()
# 断言文本不包含指定内容
expect(p).not_to_contain_text("错误")
# 断言 URL 不是指定值
expect(page).not_to_have_url("https://error.com")
高级选项
1. 超时时间（timeout）
默认超时为 5000 毫秒（5 秒），可自定义等待时间（单位：毫秒）：
# 等待 10 秒，直到元素可见
expect(locator).to_be_visible(timeout=10000)
2. 忽略大小写（ignore_case）
文本匹配时忽略大小写：
expect(heading).to_have_text("home", ignore_case=True) # 匹配 "Home"、"HOME" 等
3. 正则匹配（regex）
文本或 URL 支持正则表达式：
# 匹配以 "user-" 开头的文本
expect(locator).to_have_text(regex=r"^user-.+")
# 匹配 URL 中包含 "id=123" 的页面
expect(page).to_have_url(regex=r".+id=123.+")
断言失败的处理
若断言失败，expect 会抛出 AssertionError，导致测试用例失败，并在报告中显示详细错误信息（如预期值、实际值、定位器等）。
若需在断言失败后执行额外操作（如截图），可结合 pytest 的钩子函数。
与 assert 的区别
| 特性 | expect（Playwright） | assert（Python 内置） |
|---|---|---|
| 适用场景 | 页面元素、交互状态（依赖自动等待） | 普通变量、函数返回值（无自动等待） |
| 自动等待 | 支持（等待元素满足条件） | 不支持（需手动加 wait_for()） |
| 错误信息 | 详细（含元素定位、预期 / 实际值） | 简洁（需手动添加提示） |
| 匹配器丰富度 | 几十种页面相关匹配器 | 仅基础运算符（==、in 等） |
总结
expect 是 Playwright 中处理页面断言的最佳选择，其核心优势是自动等待（避免因元素加载异步导致的不稳定）和丰富的匹配器（覆盖各类页面场景）。使用时需注意：
- 优先用
expect断言页面元素状态和交互结果。 - 结合
not_前缀实现反向断言。 - 通过
timeout等选项适配复杂场景（如慢加载元素）。
更多匹配器可参考 Playwright 官方文档。
评论区