Playwright CI集成：GitHub Actions自动跑测试与报告生成教程

本教程共 59 篇 · 第 36 篇 · 更新于 2026-08-04 · 约 14 分钟阅读

本节目标：学完能把 Playwright 测试接进 GitHub Actions，每次推代码都自动在无头环境跑一遍，并保留可查的报告。

测试写在本地、只在自己电脑上跑，价值有限。真正的价值是：每次有人提交代码，自动跑一遍，挂了立刻报警。这一步叫持续集成（CI，Continuous Integration）。

什么是 CI

简单说，CI 是一台云端机器，你推送代码它就按你写的脚本自动执行。对 Playwright 来说，这台机器会装依赖、装浏览器、跑测试、最后把报告交还给你。

Note

本章以 GitHub Actions 为例，它是 GitHub 自带的 CI 服务。换 Jenkins、GitLab 思路一致，命令都通用。

一个能跑的 workflow

用 npm init playwright@latest 初始化时，会问你要不要加 CI，选了就会生成 .github/workflows/playwright.yml。内容长这样：

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
      - name: Install dependencies
        run: npm ci
      - name: Install Playwright Browsers
        run: npx playwright install --with-deps
      - name: Run Playwright tests
        run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

这一段做了什么

按顺序看，workflow 替你干了六件事：

把仓库代码拉下来。
装好指定版本的 Node.js。
用 npm ci 安装依赖（比 npm install 更适合 CI）。
用 npx playwright install --with-deps 装浏览器和它们的系统依赖。
真正执行测试。
把 HTML 报告上传，保留 30 天随时翻。

Warning

漏掉 npx playwright install --with-deps 是最常见的 CI 失败原因。只装浏览器不装系统库，跑起来会报缺动态链接库。

无头模式与 CI 适配

本地你习惯看浏览器跑，CI 里没有屏幕，Playwright 会自动用无头（headless）模式跑，不需要额外配置。但有几处建议专门为 CI 调一下：

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  fullyParallel: true,             // 同一文件里的用例也能并行
  forbidOnly: !!process.env.CI,    // CI 上禁止遗留 test.only
  retries: process.env.CI ? 2 : 0, // CI 失败自动重试两次
  workers: process.env.CI ? 1 : undefined,  // 官方模板的保守值，见下方说明
  reporter: process.env.CI ? 'github' : 'html',
});

这几项挨个说清楚：

fullyParallel 打开后，同一个文件里的用例也会分散到不同 worker（工作进程）上跑，不再一条条排队。
forbidOnly 防的是有人调试完忘了删 test.only，导致 CI 只跑了一条用例还显示绿灯。
retries: 2 用来消化偶发抖动，比如网络毛刺。
reporter: 'github' 会把失败信息以注解形式贴到 PR 的代码行上，看起来很直观。

Warning

注意 workers: process.env.CI ? 1 : undefined 和 fullyParallel: true 看着矛盾。这是官方模板的默认值：fullyParallel 允许并行，但 CI 上只给 1 个 worker，实际还是串行。
这么设是为了让新手在共享 runner 上不翻车（免费 runner 通常只有 2 核，并行反而更慢更不稳）。等你的用例之间确认互不干扰，再改成 workers: '50%' 之类的值放开并行，速度提升非常明显。

怎么看失败原因

测试在 CI 挂了，别慌。点进那条 workflow 运行记录，看 Run Playwright tests 步骤，里面有报错信息、期望值和实际值，还有调用栈。

想看得更细，就去 Artifacts（产物）区下载 playwright-report，那是个 zip 包。

Warning

解压后直接双击 index.html 是打不开的，页面会一片空白。HTML 报告需要一个 Web 服务器才能正常工作。

正确姿势是用命令起个本地服务：

npx playwright show-report 你解压出来的报告目录

报告页面里点每条用例旁边的 trace 图标，能一步步回放当时的操作，定位特别直观。

Tip

报告、trace、日志里可能含测试账号、token 等敏感信息。上传到 CI 产物时，只传给可信的存储，别对外公开。

本地先模拟一遍 CI

改 workflow 最烦的就是「改一行、推一次、等五分钟、又红了」。社区工具 act 能在本地用 Docker 跑 GitHub Actions 的配置，省掉这轮试错。

它是个 Go 写的命令行程序，不在 npm 上，得先装：

# macOS
brew install act

# Windows
winget install nektos.act

# Linux
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

装好之后在仓库根目录跑：

act -j test

-j test 指的是 workflow 里那个叫 test 的 job。它会拉一个近似 CI 的容器执行你写的步骤，问题在本地就能发现。

Note

act 是社区工具，不是 Playwright 自带的，也不是 GitHub 官方的。它依赖本地 Docker，跑出来的环境和真实 runner 有细微差别。它只帮你验证配置写没写对，最终结果还是以 GitHub Actions 自己的 runner 为准。

让每条推送都更稳

接好 CI 之后，团队任何一次提交都会被测试守护。

我的建议是：retries 在 CI 上设成 1 或 2，能消化偶发抖动。但别拿重试掩盖真 bug——报告里标了 flaky（不稳定）的用例，得有人跟进，不然迟早变成没人信的红灯。

小结

npm init playwright@latest 时选上 CI，会自动生成 .github/workflows/playwright.yml，改都不用改。
workflow 六步：拉代码 → 装 Node → npm ci → npx playwright install --with-deps → 跑测试 → 传报告。
漏掉 --with-deps 是 CI 失败第一名，只装浏览器不装系统库，一跑就报缺动态链接库。
CI 上没有屏幕，Playwright 自动走无头模式，不用额外配。
配置里对 CI 做区分：forbidOnly、retries: 2、reporter: 'github'；workers 确认用例互不干扰后再放开。
HTML 报告要用 npx playwright show-report 目录 起服务看，直接双击打不开。
报告、trace、日志可能含账号和 token，只往可信的产物存储上传。
想省试错时间，本地用 act 先跑一遍 workflow。

下一章起，我们讲测试框架自身的组织能力——夹具、钩子、并行，它们决定了你的测试能不能既快又清晰。

持续集成 CI

什么是 CI

一个能跑的 workflow

这一段做了什么

无头模式与 CI 适配

怎么看失败原因

本地先模拟一遍 CI

让每条推送都更稳

小结