企业官网建设流程全解析

[Playwright] playwright.config.ts 配置详解：浏览器、超时、重试

最近在给我自己的项目补充 Playwright 自动化测试时，发现playwright.config.ts里有不少配置。

一开始觉得，配置文件嘛，能跑就行。但实际运行测试时，遇到了几个问题：为什么一个测试执行了三遍？为什么断言明明写错了，还要等几秒才报错？为什么本地测试失败就结束，而 CI 环境还会重新执行？

这篇结合项目中的真实配置，聊聊三个比较实用的功能。

一、浏览器配置：为什么一个测试会执行三遍？

我们项目的配置是：

projects:[{name:'chromium',use:{...devices['Desktop Chrome']},},{name:'firefox',use:{...devices['Desktop Firefox']},},{name:'webkit',use:{...devices['Desktop Safari']},},],

这里配置了三个浏览器项目：

• Chromium：Chrome、Edge 等浏览器使用的核心引擎。
• Firefox：Firefox 浏览器使用的引擎。
• WebKit：Safari 使用的浏览器引擎。

如果直接运行：

npx playwrighttest

Playwright 会在三个浏览器项目中分别执行匹配的测试。

但日常开发时，我通常没必要每次都跑三个浏览器。比如只想检查 Chromium：

npx playwrighttest--project=chromium

需要做跨浏览器回归时，再运行全部项目。

终端展示 Chromium、Firefox、WebKit 三个浏览器项目的测试执行记录

这里需要注意：WebKit 可以帮助我们发现 Safari 引擎相关的兼容性问题，但它不完全等同于在真实 Safari 浏览器中测试。

二、超时配置：为什么断言失败还要等 5 秒？

之前写 Bing 搜索测试时，我故意把 URL 断言写错：

awaitexpect(page).toHaveURL('https://www.google.com/');

实际页面已经跳转到了 Bing 搜索结果，但测试并没有立即失败，而是等了大约 5 秒。

原因是toHaveURL()属于会自动重试的断言。Playwright 会持续检查 URL，直到满足条件或超过等待时间。

我们项目没有显式设置超时，因此使用 Playwright Test 的默认值：

如果想在配置文件里明确设置，可以这样写：

exportdefaultdefineConfig({timeout:30000,expect:{timeout:5000,},});

也可以只修改某一次断言：

awaitexpect(page).toHaveURL('Google',{timeout:2000,});

这样最多等待 2 秒，而不是默认的 5 秒。

同一个错误 URL 断言，分别设置 5000ms 和 2000ms 后的失败信息

这里我觉得最容易混淆的是：测试超时和断言超时不是一回事。

timeout控制整个测试，包括页面操作和断言；expect.timeout只控制相应自动重试断言的等待时间。

所以遇到测试超时，先看是哪一步卡住了，不要上来就把所有 timeout 改成 60 秒。

三、重试配置：为什么本地失败一次，CI 却会执行三次？

这是我们 HPC Dashboard 项目里的实际配置：

retries:process.env.CI?2:0,workers:process.env.CI?1:undefined,//process.env.CI 读取当前运行环境中的 CI 环境变量//retries 是重试次数，workers 是并行执行测试的工作进程数量//条件 ? 条件成立时的值 : 条件不成立时的值

process.env.CI 是读取环境变量 CI，通常在 GitHub Actions、Jenkins 等持续集成环境中设置

含义很简单：

• CI 环境：失败后最多重试两次。
• 本地运行：失败后不自动重试。
• CI 环境：只使用一个 worker，减少并发执行带来的资源竞争。

这里的retries: 2不是总共执行两次，而是首次执行失败后，最多再执行两次，也就是最多三次。

不需要真的启动 CI，我们可以直接通过命令行验证：

npx playwrighttesttests/demo/bing.spec.ts--project=chromium--retries=2

运行之前那个故意写错 URL 的测试，就能观察到失败后的重试过程。

HTML 报告中同一个失败测试的首次执行和 Retry 记录

都是三条记录

不过，重试也不是越多越好。

比如 URL 明明写错了，重试十次也不会变成正确结果。重试更适合帮助识别偶发性失败（Flaky Test），例如测试环境偶尔响应慢、页面状态不稳定等情况。

如果某个测试总是第一次失败、第二次通过，应该进一步排查原因，而不是觉得“反正最后绿了就行”。

四、总结

回头看，我们项目的配置其实挺符合日常开发需求：

• 浏览器：本地先跑 Chromium，需要时再做跨浏览器测试。
• 超时：区分整个测试的超时和单次断言的等待时间。
• 重试：本地失败及时暴露问题，CI 环境允许有限次数的重试。

playwright.config.ts不需要一开始就写得特别复杂。真正重要的是，遇到问题时知道应该检查哪个配置，而不是靠不断增加超时和重试次数让测试“看起来通过”。