skillhub-147-playwright-skill
wehub-skill-sync
580 行
18 KiB
Markdown
580 行
18 KiB
Markdown
# CI：GitHub Actions
|
||
|
||
> **使用时机**：在拉取请求、合并到主分支或按计划自动运行 Playwright 测试。GitHub Actions 是 Playwright 项目中最常用的 CI。
|
||
|
||
## 快速参考
|
||
|
||
```bash
|
||
# CI 的关键 CLI 标志
|
||
npx playwright install --with-deps # 安装浏览器 + 操作系统依赖
|
||
npx playwright test --shard=1/4 # 运行 4 个分片中的第 1 个
|
||
npx playwright test --reporter=github # 在 PR 上标注失败信息
|
||
npx playwright merge-reports ./blob-report # 合并分片报告
|
||
```
|
||
|
||
## 模式
|
||
|
||
### 模式 1：生产就绪工作流（可直接复制的起步模板）
|
||
|
||
**使用时机**：任何使用 GitHub Actions 的项目。这是一个完整且经过实战检验的工作流。
|
||
|
||
```yaml
|
||
# .github/workflows/playwright.yml
|
||
name: Playwright Tests
|
||
|
||
on:
|
||
push:
|
||
branches: [main]
|
||
pull_request:
|
||
branches: [main]
|
||
|
||
# 取消同一 PR/分支上的进行中运行
|
||
concurrency:
|
||
group: playwright-${{ github.ref }}
|
||
cancel-in-progress: true
|
||
|
||
env:
|
||
CI: true
|
||
|
||
jobs:
|
||
test:
|
||
timeout-minutes: 30
|
||
runs-on: ubuntu-latest
|
||
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- uses: actions/setup-node@v4
|
||
with:
|
||
node-version: 20
|
||
cache: "npm"
|
||
|
||
- name: Install dependencies
|
||
run: npm ci
|
||
|
||
- name: Cache Playwright browsers
|
||
id: playwright-cache
|
||
uses: actions/cache@v4
|
||
with:
|
||
path: ~/.cache/ms-playwright
|
||
key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
|
||
|
||
- name: Install Playwright browsers
|
||
if: steps.playwright-cache.outputs.cache-hit != 'true'
|
||
run: npx playwright install --with-deps
|
||
|
||
- name: Install Playwright OS dependencies
|
||
if: steps.playwright-cache.outputs.cache-hit == 'true'
|
||
run: npx playwright install-deps
|
||
|
||
- name: Run Playwright tests
|
||
run: npx playwright test
|
||
|
||
- name: Upload HTML report
|
||
uses: actions/upload-artifact@v4
|
||
if: ${{ !cancelled() }}
|
||
with:
|
||
name: playwright-report
|
||
path: playwright-report/
|
||
retention-days: 14
|
||
|
||
- name: Upload test traces
|
||
uses: actions/upload-artifact@v4
|
||
if: failure()
|
||
with:
|
||
name: playwright-traces
|
||
path: test-results/
|
||
retention-days: 7
|
||
```
|
||
|
||
### 模式 2：使用矩阵策略的分片执行
|
||
|
||
**使用时机**：测试套件耗时超过 10 分钟。分散到多个并行运行器以缩短实际耗时。
|
||
**避免时机**：测试套件在 5 分钟以内——分片开销（检出、安装、合并）会抵消其带来的好处。
|
||
|
||
```yaml
|
||
# .github/workflows/playwright-sharded.yml
|
||
name: Playwright Tests (Sharded)
|
||
|
||
on:
|
||
push:
|
||
branches: [main]
|
||
pull_request:
|
||
branches: [main]
|
||
|
||
concurrency:
|
||
group: playwright-${{ github.ref }}
|
||
cancel-in-progress: true
|
||
|
||
env:
|
||
CI: true
|
||
|
||
jobs:
|
||
test:
|
||
timeout-minutes: 20
|
||
runs-on: ubuntu-latest
|
||
strategy:
|
||
fail-fast: false
|
||
matrix:
|
||
shard: [1/4, 2/4, 3/4, 4/4]
|
||
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- uses: actions/setup-node@v4
|
||
with:
|
||
node-version: 20
|
||
cache: "npm"
|
||
|
||
- name: Install dependencies
|
||
run: npm ci
|
||
|
||
- name: Cache Playwright browsers
|
||
id: playwright-cache
|
||
uses: actions/cache@v4
|
||
with:
|
||
path: ~/.cache/ms-playwright
|
||
key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
|
||
|
||
- name: Install Playwright browsers
|
||
if: steps.playwright-cache.outputs.cache-hit != 'true'
|
||
run: npx playwright install --with-deps
|
||
|
||
- name: Install Playwright OS dependencies
|
||
if: steps.playwright-cache.outputs.cache-hit == 'true'
|
||
run: npx playwright install-deps
|
||
|
||
- name: Run Playwright tests (shard ${{ matrix.shard }})
|
||
run: npx playwright test --shard=${{ matrix.shard }}
|
||
|
||
- name: Upload blob report
|
||
uses: actions/upload-artifact@v4
|
||
if: ${{ !cancelled() }}
|
||
with:
|
||
name: blob-report-${{ strategy.job-index }}
|
||
path: blob-report/
|
||
retention-days: 1
|
||
|
||
merge-reports:
|
||
if: ${{ !cancelled() }}
|
||
needs: test
|
||
runs-on: ubuntu-latest
|
||
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- uses: actions/setup-node@v4
|
||
with:
|
||
node-version: 20
|
||
cache: "npm"
|
||
|
||
- name: Install dependencies
|
||
run: npm ci
|
||
|
||
- name: Download all blob reports
|
||
uses: actions/download-artifact@v4
|
||
with:
|
||
path: all-blob-reports
|
||
pattern: blob-report-*
|
||
merge-multiple: true
|
||
|
||
- name: Merge reports
|
||
run: npx playwright merge-reports --reporter=html ./all-blob-reports
|
||
|
||
- name: Upload merged HTML report
|
||
uses: actions/upload-artifact@v4
|
||
with:
|
||
name: playwright-report
|
||
path: playwright-report/
|
||
retention-days: 14
|
||
```
|
||
|
||
**分片配置**——添加 blob reporter 以便合并分片输出：
|
||
|
||
```ts
|
||
// playwright.config.ts
|
||
import { defineConfig } from "@playwright/test"
|
||
|
||
export default defineConfig({
|
||
reporter: process.env.CI ? [["blob"], ["github"]] : [["html", { open: "on-failure" }]],
|
||
})
|
||
```
|
||
|
||
### 模式 3：可复用工作流
|
||
|
||
**使用时机**：多个仓库或多个工作流文件需要相同的 Playwright 配置。
|
||
**避免时机**：只有一个工作流的单个仓库。
|
||
|
||
```yaml
|
||
# .github/workflows/playwright-reusable.yml
|
||
name: Playwright Reusable
|
||
|
||
on:
|
||
workflow_call:
|
||
inputs:
|
||
node-version:
|
||
type: string
|
||
default: "20"
|
||
test-command:
|
||
type: string
|
||
default: "npx playwright test"
|
||
shard-total:
|
||
type: number
|
||
default: 1
|
||
secrets:
|
||
BASE_URL:
|
||
required: false
|
||
TEST_PASSWORD:
|
||
required: false
|
||
|
||
jobs:
|
||
test:
|
||
timeout-minutes: 30
|
||
runs-on: ubuntu-latest
|
||
strategy:
|
||
fail-fast: false
|
||
matrix:
|
||
shard: ${{ fromJson(format('[{0}]', join(fromJson(format('[{0}]', inputs.shard-total == 1 && '"1/1"' || '"1/4","2/4","3/4","4/4"')), ','))) }}
|
||
|
||
env:
|
||
CI: true
|
||
BASE_URL: ${{ secrets.BASE_URL }}
|
||
TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
|
||
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- uses: actions/setup-node@v4
|
||
with:
|
||
node-version: ${{ inputs.node-version }}
|
||
cache: "npm"
|
||
|
||
- run: npm ci
|
||
|
||
- name: Cache Playwright browsers
|
||
id: playwright-cache
|
||
uses: actions/cache@v4
|
||
with:
|
||
path: ~/.cache/ms-playwright
|
||
key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
|
||
|
||
- name: Install Playwright browsers
|
||
if: steps.playwright-cache.outputs.cache-hit != 'true'
|
||
run: npx playwright install --with-deps
|
||
|
||
- name: Install Playwright OS dependencies
|
||
if: steps.playwright-cache.outputs.cache-hit == 'true'
|
||
run: npx playwright install-deps
|
||
|
||
- name: Run tests
|
||
run: ${{ inputs.test-command }} --shard=${{ matrix.shard }}
|
||
|
||
- uses: actions/upload-artifact@v4
|
||
if: ${{ !cancelled() }}
|
||
with:
|
||
name: playwright-report-${{ strategy.job-index }}
|
||
path: playwright-report/
|
||
retention-days: 14
|
||
```
|
||
|
||
**调用可复用工作流：**
|
||
|
||
```yaml
|
||
# .github/workflows/ci.yml
|
||
name: CI
|
||
on:
|
||
pull_request:
|
||
branches: [main]
|
||
|
||
jobs:
|
||
e2e:
|
||
uses: ./.github/workflows/playwright-reusable.yml
|
||
with:
|
||
node-version: "20"
|
||
shard-total: 4
|
||
secrets:
|
||
BASE_URL: ${{ secrets.STAGING_URL }}
|
||
TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
|
||
```
|
||
|
||
### 模式 4：在容器中运行
|
||
|
||
**使用时机**：你需要一个与本地 Docker 运行一致的可重现环境，或者运行器的操作系统依赖引起问题。
|
||
**避免时机**：标准的 `ubuntu-latest` 配合 `--with-deps` 已经能正常工作（这是常见情况）。
|
||
|
||
```yaml
|
||
# .github/workflows/playwright-container.yml
|
||
name: Playwright (Container)
|
||
|
||
on:
|
||
pull_request:
|
||
branches: [main]
|
||
|
||
jobs:
|
||
test:
|
||
timeout-minutes: 30
|
||
runs-on: ubuntu-latest
|
||
container:
|
||
image: mcr.microsoft.com/playwright:v1.52.0-noble
|
||
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- uses: actions/setup-node@v4
|
||
with:
|
||
node-version: 20
|
||
|
||
- run: npm ci
|
||
|
||
# 无需安装浏览器——它们已在容器镜像中
|
||
- name: Run Playwright tests
|
||
run: npx playwright test
|
||
env:
|
||
HOME: /root # 在容器中以 root 身份运行时需要
|
||
|
||
- uses: actions/upload-artifact@v4
|
||
if: ${{ !cancelled() }}
|
||
with:
|
||
name: playwright-report
|
||
path: playwright-report/
|
||
retention-days: 14
|
||
```
|
||
|
||
### 模式 5：环境密钥与部署目标
|
||
|
||
**使用时机**：测试针对需要身份验证凭据的预发/生产环境运行。
|
||
**避免时机**：测试只针对本地启动的开发服务器运行。
|
||
|
||
```yaml
|
||
# .github/workflows/playwright-staging.yml
|
||
name: Playwright (Staging)
|
||
|
||
on:
|
||
push:
|
||
branches: [main]
|
||
workflow_dispatch:
|
||
|
||
jobs:
|
||
test:
|
||
timeout-minutes: 30
|
||
runs-on: ubuntu-latest
|
||
environment: staging # 包含保护规则的 GitHub Environment
|
||
|
||
env:
|
||
CI: true
|
||
BASE_URL: ${{ vars.STAGING_URL }}
|
||
TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
|
||
API_KEY: ${{ secrets.API_KEY }}
|
||
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- uses: actions/setup-node@v4
|
||
with:
|
||
node-version: 20
|
||
cache: "npm"
|
||
|
||
- run: npm ci
|
||
|
||
- name: Cache Playwright browsers
|
||
id: playwright-cache
|
||
uses: actions/cache@v4
|
||
with:
|
||
path: ~/.cache/ms-playwright
|
||
key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
|
||
|
||
- name: Install Playwright browsers
|
||
if: steps.playwright-cache.outputs.cache-hit != 'true'
|
||
run: npx playwright install --with-deps
|
||
|
||
- name: Install Playwright OS dependencies
|
||
if: steps.playwright-cache.outputs.cache-hit == 'true'
|
||
run: npx playwright install-deps
|
||
|
||
- name: Run tests against staging
|
||
run: npx playwright test --grep @smoke
|
||
|
||
- uses: actions/upload-artifact@v4
|
||
if: ${{ !cancelled() }}
|
||
with:
|
||
name: staging-report
|
||
path: playwright-report/
|
||
retention-days: 14
|
||
```
|
||
|
||
### 模式 6：定时运行（夜间回归）
|
||
|
||
**使用时机**：完整回归套件对每个 PR 来说太慢。改为每晚针对主分支运行一次。
|
||
**避免时机**：测试套件在 15 分钟内跑完，且可以在每个 PR 上运行。
|
||
|
||
```yaml
|
||
# .github/workflows/playwright-nightly.yml
|
||
name: Nightly Regression
|
||
|
||
on:
|
||
schedule:
|
||
- cron: "0 3 * * 1-5" # UTC 时间凌晨 3 点，周一至周五
|
||
workflow_dispatch: # 允许手动触发
|
||
|
||
jobs:
|
||
test:
|
||
timeout-minutes: 60
|
||
runs-on: ubuntu-latest
|
||
|
||
env:
|
||
CI: true
|
||
BASE_URL: ${{ vars.STAGING_URL }}
|
||
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- uses: actions/setup-node@v4
|
||
with:
|
||
node-version: 20
|
||
cache: "npm"
|
||
|
||
- run: npm ci
|
||
|
||
- name: Install Playwright browsers
|
||
run: npx playwright install --with-deps
|
||
|
||
- name: Run full regression suite
|
||
run: npx playwright test --grep @regression
|
||
|
||
- uses: actions/upload-artifact@v4
|
||
if: ${{ !cancelled() }}
|
||
with:
|
||
name: nightly-report-${{ github.run_number }}
|
||
path: playwright-report/
|
||
retention-days: 30
|
||
|
||
- name: Notify on failure
|
||
if: failure()
|
||
uses: slackapi/slack-github-action@v1.27.0
|
||
with:
|
||
payload: |
|
||
{
|
||
"text": "Nightly Playwright regression failed: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
|
||
}
|
||
env:
|
||
SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
|
||
```
|
||
|
||
## 决策指南
|
||
|
||
| 场景 | 做法 | 原因 |
|
||
| -------------------------- | ------------------------------------------ | ------------------------------------------ |
|
||
| 小型套件（< 5 分钟） | 单个 job，不分片 | 分片开销超过节省的时间 |
|
||
| 中型套件（5-20 分钟） | 使用矩阵策略分为 2-4 个分片 | 将实际耗时缩短约 60-75% |
|
||
| 大型套件（20+ 分钟） | 4-8 个分片 + blob report 合并 | 将 PR 反馈时间控制在 10 分钟以内 |
|
||
| PR 上的跨浏览器测试 | PR 上仅 Chromium；主分支上测试所有浏览器 | PR 上的耗时减少 3 倍 |
|
||
| 预发/生产冒烟测试 | 使用 `environment:` 的独立工作流 | 隔离密钥，添加审批关卡 |
|
||
| 夜间完整回归测试 | `schedule` 触发器 + `workflow_dispatch` | 全面覆盖，不阻塞 PR |
|
||
| 多个仓库，相同配置 | 使用 `workflow_call` 的可复用工作流 | DRY 原则；更新一个文件，所有仓库受益 |
|
||
| 需要可重现环境 | 使用 Playwright 镜像的容器 job | 与本地 Docker 环境完全一致 |
|
||
|
||
## 反模式
|
||
|
||
| 反模式 | 问题 | 应改为 |
|
||
| ------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
|
||
| 没有 `concurrency` 分组 | 每次推送都会产生重复运行，浪费分钟数 | 添加 `concurrency: { group: ..., cancel-in-progress: true }` |
|
||
| 分片时使用 `fail-fast: true` | 一个分片失败会取消其他分片，丢失它们的测试结果 | 设置 `fail-fast: false` 以收集所有失败 |
|
||
| 安装浏览器时未使用缓存 | 每次运行浪费 60-90 秒 | 以 lockfile 哈希为键，缓存 `~/.cache/ms-playwright` |
|
||
| 未设置 `timeout-minutes` | 卡住的 job 将运行 6 小时（GitHub 默认值） | 设置明确的超时时间：20-30 分钟 |
|
||
| 仅在失败时上传构建产物 | 测试通过时没有报告，无法验证结果 | 使用 `if: ${{ !cancelled() }}` 始终上传 |
|
||
| 在工作流文件中硬编码密钥 | 安全漏洞 | 使用 GitHub Secrets 和 Environments |
|
||
| 在每个 PR 上运行所有浏览器 | 成本增加 3 倍，收益甚微 | PR 上仅 Chromium；合并到主分支时做跨浏览器测试 |
|
||
| `actions/upload-artifact` 未设置保留期限 | 默认 90 天保留期会填满存储 | 为报告设置 `retention-days: 7-14` |
|
||
| 安装浏览器时未使用 `--with-deps` | 缺少操作系统库导致浏览器启动失败 | 始终使用 `npx playwright install --with-deps` |
|
||
|
||
## 故障排查
|
||
|
||
### 浏览器启动失败："Missing dependencies"
|
||
|
||
**原因**：浏览器从缓存安装，但操作系统依赖未被缓存（它们位于系统目录中，而非 `~/.cache`）。
|
||
|
||
**修复**：在缓存命中时始终运行 `npx playwright install-deps`：
|
||
|
||
```yaml
|
||
- name: Install Playwright OS dependencies
|
||
if: steps.playwright-cache.outputs.cache-hit == 'true'
|
||
run: npx playwright install-deps
|
||
```
|
||
|
||
### 测试本地通过但 CI 中超时失败
|
||
|
||
**原因**：CI 运行器的 CPU 核心数和 RAM 少于你的开发机器。默认的 worker 数和超时时间设置得太激进。
|
||
|
||
**修复**：在配置中为 CI 减少 worker 数并增加超时时间：
|
||
|
||
```ts
|
||
// playwright.config.ts
|
||
import { defineConfig } from "@playwright/test"
|
||
|
||
export default defineConfig({
|
||
workers: process.env.CI ? "50%" : undefined,
|
||
use: {
|
||
actionTimeout: process.env.CI ? 15_000 : 10_000,
|
||
navigationTimeout: process.env.CI ? 30_000 : 15_000,
|
||
},
|
||
})
|
||
```
|
||
|
||
### 分片报告不完整——合并报告中缺少部分分片
|
||
|
||
**原因**：使用 `actions/download-artifact@v4` 时未设置 `merge-multiple: true`，或者分片之间的构建产物名称冲突。
|
||
|
||
**修复**：为每个分片赋予唯一的构建产物名称，并使用 `merge-multiple`：
|
||
|
||
```yaml
|
||
# 在每个分片 job 中上传
|
||
- uses: actions/upload-artifact@v4
|
||
with:
|
||
name: blob-report-${{ strategy.job-index }}
|
||
path: blob-report/
|
||
|
||
# 在合并 job 中下载
|
||
- uses: actions/download-artifact@v4
|
||
with:
|
||
path: all-blob-reports
|
||
pattern: blob-report-*
|
||
merge-multiple: true
|
||
```
|
||
|
||
### `webServer` 在 CI 中失败："port 3000 already in use"
|
||
|
||
**原因**：前一次运行留下了僵尸进程，或者其他 job 步骤正在使用该端口。
|
||
|
||
**修复**：确保在 CI 中设置 `reuseExistingServer: false`，并添加一个前置步骤来杀死过期进程：
|
||
|
||
```yaml
|
||
- name: Kill stale processes
|
||
run: lsof -ti:3000 | xargs kill -9 2>/dev/null || true
|
||
```
|
||
|
||
### GitHub 注释未在 PR 上显示
|
||
|
||
**原因**：未配置 `github` reporter。
|
||
|
||
**修复**：为 CI 运行添加 `github` reporter：
|
||
|
||
```ts
|
||
// playwright.config.ts
|
||
import { defineConfig } from "@playwright/test"
|
||
|
||
export default defineConfig({
|
||
reporter: process.env.CI
|
||
? [["html", { open: "never" }], ["github"]]
|
||
: [["html", { open: "on-failure" }]],
|
||
})
|
||
```
|
||
|
||
## 相关文档
|
||
|
||
- [ci/parallel-and-sharding.md](parallel-and-sharding.md) —— 分片策略与 blob report 合并
|
||
- [ci/reporting-and-artifacts.md](reporting-and-artifacts.md) —— reporter 配置与构建产物管理
|
||
- [ci/docker-and-containers.md](docker-and-containers.md) —— CI 容器镜像
|
||
- [ci/ci-gitlab.md](ci-gitlab.md) —— GitLab CI 对应方案
|
||
- [ci/ci-other.md](ci-other.md) —— CircleCI、Azure DevOps、Jenkins
|
||
- [core/configuration.md](../core/configuration.md) —— 感知 CI 的配置设置
|