最近团队迁移到 Playwright，新人反馈最多的问题不是定位器，也不是异步处理，而是——断言时而通过、时而失败，本地跑通 CI 却挂，排查起来又慢又烦。
其实，Playwright 的断言机制设计非常优秀：内置 web-first 断言（如 、）自带自动等待 + 智能重试，理论上比 Selenium 稳得多。
但为什么实际用起来问题频发？
核心原因就两个：没吃透底层逻辑 + 被旧习惯带偏了节奏。
今天，我就结合团队真实案例，系统梳理 Playwright 断言的核心逻辑、6 个必学方法、5 大高频坑点和最佳实践，帮你写出稳定、可维护、真正有价值的自动化测试。
断言是什么？为什么它如此重要？
元素定位（Locators） 帮你“找到”元素
断言（Assertions） 帮你“校验”结果是否正确
一个没有断言的测试，根本算不上测试——它充其量只是一个运行脚本。
🔍 什么是断言？
断言是一种检查机制（Check），比如：
按钮是否可见？
URL 是否跳转正确？
页面是否显示“登录成功”？
复选框是否被勾选？
核心逻辑很简单：
检查失败 ➡ 测试失败（Fail）
检查通过 ➡ 测试通过（Pass）
在 Playwright 中，统一用 expect(...) 编写断言：
awaitexpect(page.getByText('欢迎回来')).toBeVisible();
⚠️ 为什么断言至关重要？
想象一下：你写了登录脚本，点了“登录”，页面也跳了……但没加任何断言。
那你怎么知道：
用户真的登录成功了？
Token 是否下发？
跳的是首页还是错误页？
没有断言 = 没有验证 = 测试毫无价值。
而有了断言，你才能：
✅ 确认系统行为符合预期
✅ 主动捕捉 Bug
✅ 真正提升软件质量，而不是“跑了个寂寞”
6 个最实用的断言方法（附真实场景 + 代码）
以下是我要求新人必须掌握的 6 个高频断言，覆盖 90% 日常场景：
表格
方法 用途 典型场景 示例
toBeVisible() 元素是否可见 成功提示、错误弹窗、加载完成 await expect(page.getByText('保存成功')).toBeVisible();
toHaveText()
文本是否精确匹配
用户名、状态标签、订单号 await expect(page.locator('#name')).toHaveText('张三');
toHaveURL() 页面 URL 是否正确 登录跳转、提交重定向 await expect(page).toHaveURL(/dashboard/);
toHaveTitle()
