Playwright 如何调整超时设置
Playwright 超时分四层：测试整体 30s、断言 5s、动作无默认（跟随测试）、导航无独立默认上限（受测试总超时约束）。playwright.config 里 timeout/expect.timeout/actionTimeout/navigationTimeout 分别调整，附单层覆盖写法。
一句话回答：在 playwright.config.ts 里分层调整：timeout（单个测试总时长，默认 30 秒）、expect.timeout（断言等待，默认 5 秒）、use.actionTimeout（点击等单动作）、use.navigationTimeout（页面导航）。单个测试/单条断言也可以就地覆盖：test.setTimeout(120000)、expect(locator).toBeVisible({ timeout: 10000 })。
四层超时与默认值
| 层 | 配置项 | 默认 | 管什么 |
|---|---|---|---|
| 测试整体 | timeout |
30s | 一个 test 从头到尾 |
| 断言 | expect.timeout |
5s | toBeVisible 等重试上限 |
| 动作 | use.actionTimeout |
0（跟随测试超时） | click/fill 单次操作 |
| 导航 | use.navigationTimeout |
0（跟随测试超时） | goto/waitForURL |
全局配置
import { defineConfig } from '@playwright/test';
export default defineConfig({
timeout: 60_000, // 每个测试 60 秒
expect: { timeout: 10_000 }, // 断言最多等 10 秒
use: {
actionTimeout: 15_000, // 单次点击/填充
navigationTimeout: 30_000, // 页面导航
},
});
局部覆盖
test('大文件上传', async ({ page }) => {
test.setTimeout(180_000); // 只给这个测试放宽到 3 分钟
// ...
await expect(page.locator('#done')).toBeVisible({ timeout: 60_000 });
});
// 慢测试分组
test.describe('报表', () => {
test.describe.configure({ timeout: 300_000 });
});
调超时前先想一秒
"Timeout of 30000ms exceeded" 有两种病因：
- 真慢：环境差、大数据量、冷启动——调大超时合理
- 假慢（更常见）：选择器写错等一个永远不存在的元素、页面卡在错误状态——调大超时只是把失败从 30 秒拖成 120 秒
排障顺序：先看 Trace（npx playwright show-trace）确认卡在哪一步，再决定调不调。
常见问题（FAQ）
Q：CI 上比本地慢一倍，统一放大超时？
A：配置里用环境变量区分：timeout: process.env.CI ? 120_000 : 60_000。需要重试时配置 retries，并保留 Trace 排查 flaky；重试不能替代定位根因。
Q：actionTimeout 设了为什么没用？
A：动作超时的默认 0 表示"不设独立上限，受测试总超时约束"。设了但测试总超时先到，照样失败——大 actionTimeout 要配合更大的测试 timeout。
Q：全局 beforeAll 超时算谁的？
A：hook 的超时单独算：test.beforeAll 默认也受测试 timeout 影响，可在 hook 内 test.setTimeout() 调整该 hook 的超时；Playwright Test 没有 hooksTimeout 配置项。
参考资料
本文依据官方资料核对，未进行现场运行测试；代码与配置示例需结合实际版本、权限和环境验证。
