自动化测试 / 系统课时
配置断言超时
配置断言超时
断言超时决定 Playwright 愿意为“页面最终达到期望状态”等待多久。合理设置应覆盖正常业务延迟,又不能把真实故障拖成漫长等待。本节区分全局与局部断言超时,并用一个慢状态更新示例验证覆盖规则。
学习目标
- 配置项目级
expect断言超时 - 为个别慢操作设置局部断言超时
- 区分断言超时、测试超时与操作超时的职责
先分清断言超时的职责
Playwright 的 Web-First 断言会在超时窗口内重复检查条件。断言超时只控制这一类等待,不等于整个测试最多能运行多久,也不等于点击、填写等操作的超时。
常见的三个层次可以这样理解:
| 设置 | 控制范围 | 适合解决的问题 |
|---|---|---|
expect.timeout |
Web-First 断言 | 元素文本、可见性、数量等最终状态 |
timeout |
整个测试 | 防止单个测试整体运行过久 |
actionTimeout |
点击、填写等操作 | 限制单次页面操作的等待时间 |
断言等待上限必须小于测试整体还能提供的时间预算。否则即使给断言设置了更大的值,测试本身也可能先超时退出。
设置项目级断言上限
可以在 playwright.config.ts 的 expect 中定义统一上限。下面把普通断言等待设置为 1 秒,同时保留 10 秒的测试总超时,便于后面的慢断言做局部覆盖。
import { defineConfig } from '@playwright/test';
export default defineConfig({
timeout: 10_000,
expect: {
timeout: 1_000,
},
});生效行为:未单独指定 timeout 的 Web-First 断言最多重试约 1 秒;测试整体仍受 10 秒上限约束。可通过运行任意故意延迟超过 1 秒的断言验证配置是否生效。
为慢断言做局部覆盖
如果只有少数业务动作天然更慢,不要把全局超时一起放大。下面页面在 1.5 秒后才把状态改成 done,因此该断言显式给出 2.5 秒上限。
import { test, expect } from '@playwright/test';
test('慢状态使用局部断言超时', async ({ page }) => {
await page.setContent(`
<div data-testid="status">processing</div>
<script>
setTimeout(() => {
document.querySelector('[data-testid="status"]').textContent = 'done';
}, 1500);
</script>
`);
const status = page.getByTestId('status');
// 覆盖全局 1 秒限制,只放宽这一条确实较慢的断言。
await expect(status).toHaveText('done', { timeout: 2_500 });
console.log('status assertion passed');
});预期输出:
status assertion passed如果删除局部的 { timeout: 2_500 },这条断言会受全局 1 秒配置约束,并在状态更新前失败。
按业务响应时间确定数值
超时应该来自可解释的业务上限,而不是测试失败后不断加大。可以先观察正常环境中的接口和 UI 完成时间,再给少量网络与调度抖动留余量。例如,大多数搜索结果 1 秒内出现,就没有必要把所有断言统一放宽到几十秒。
超时失败时先查条件是否可能成立
断言超时表示在等待窗口内始终没有观察到期望状态,但根因不一定是“时间不够”。应先检查 Locator 是否指向正确元素、触发业务动作是否成功、页面是否进入了预期状态,再决定是否调整时间。
当某个场景确实有稳定且合理的较长响应上限时,用局部 timeout 明确表达例外;只有大多数断言都需要相同等待预算时,才调整项目级 expect.timeout。这样既保留正常测试的快速失败能力,也能容纳真正的慢业务流程。