在多台机器上对 Playwright 测试分片-未完纪

简介

Playwright 默认并行运行测试文件，尽量充分利用本机 CPU 核心。若要进一步提高并行度，可以让多台机器同时执行测试。这个模式称为分片（sharding）：把测试分为更小的部分，每个分片都类似一个可以独立运行的任务。

目标是通过分摊测试缩短运行时间。每个分片独立运行，并使用可用 CPU 核心；同时完成工作有助于加快测试。在 CI 流水线中，每个分片都可以是独立任务，利用流水线的硬件资源。

在多台机器之间分片

在命令行传入 --shard=x/y。例如，把测试套件划分为4个分片，每个执行四分之一的测试：

npx playwright test --shard=1/4
npx playwright test --shard=2/4
npx playwright test --shard=3/4
npx playwright test --shard=4/4

原文指出，将这些分片放在不同任务中并行运行，可以使测试套件快4倍。这是理想化示例，实际速度还受任务启动和负载差异影响。

Playwright 只能对可以并行运行的测试分片。默认意味着以测试文件分片。其他方式见并行执行指南。

平衡分片

分片粒度取决于是否启用 fullyParallel，这会影响分片之间的测试分配。

启用 fullyParallel: true 时，Playwright Test 可以在多个分片间并行运行单个测试，并尽量均衡测试数量。它采用测试级粒度，根据测试总数优化分片执行，是希望均衡负载时的推荐模式。

未启用时，默认以文件为粒度，整个测试文件分给某个分片；同一文件在不同项目中可能分到不同分片。每个文件的测试数量会显著影响分布。如果文件大小不均，有的分片运行大量测试，有的很少甚至没有。

因此：启用 fullyParallel 可按单个测试分配；未启用时，应保持文件较小且大小均衡。在 CI 中若目标是均衡分配，推荐 fullyParallel: true，否则可能需要手动调整文件组织。静态跳过的测试，例如 test.skip 或 test.fixme，由于不会运行，不计入分片平衡。

合并多个分片的报告

每个分片有自己的报告。如需查看所有分片的统一结果，可以合并报告。

首先在 CI 中启用 blob reporter：

配置文件：playwright.config.ts

export default defineConfig({
  testDir: './tests',
  reporter: process.env.CI ? 'blob' : 'html',
});

Blob 报告包含运行过的所有测试、结果，以及追踪和截图差异等附件。它可以合并并转换为其他 Playwright 报告。默认保存于 blob-report，更多选项见 Blob reporter 文档。

把所有分片的 Blob 报告放入一个目录，例如 all-blob-reports。报告名称包含分片编号，所以不会冲突。然后运行：

npx playwright merge-reports --reporter html ./all-blob-reports

这会在 playwright-report 目录生成标准 HTML 报告。

GitHub Actions 示例

GitHub Actions 通过任务矩阵及 jobs.<job_id>.strategy.matrix 支持多个任务分片。矩阵为各个选项组合分别运行一个任务。

下面在4台机器上并行运行，再合并为一个报告。别忘了按上一节配置 reporter: process.env.CI ? 'blob' : 'html'。

在任务中增加矩阵，shardTotal: [4] 表示总分片数，shardIndex: [1, 2, 3, 4] 表示各个分片编号。
使用 --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}，让各任务执行相应分片。
把 Blob 报告上传到 GitHub Actions Artifacts，供后续任务使用。

工作流文件：.github/workflows/playwright.yml

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  playwright-tests:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shardIndex: [1, 2, 3, 4]
        shardTotal: [4]
    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 --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}

    - name: Upload blob report to GitHub Actions Artifacts
      if: ${{ !cancelled() }}
      uses: actions/upload-artifact@v4
      with:
        name: blob-report-${{ matrix.shardIndex }}
        path: blob-report
        retention-days: 1

所有分片结束后，用单独的任务合并报告并生成统一 HTML 报告。给 merge-reports 增加 needs: [playwright-tests]，确保任务依赖与执行顺序：

工作流文件：.github/workflows/playwright.yml

jobs:
...
  merge-reports:
    # Merge reports after playwright-tests, even if some shards have failed
    if: ${{ !cancelled() }}
    needs: [playwright-tests]

    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: Download blob reports from GitHub Actions Artifacts
      uses: actions/download-artifact@v5
      with:
        path: all-blob-reports
        pattern: blob-report-*
        merge-multiple: true

    - name: Merge into HTML Report
      run: npx playwright merge-reports --reporter html ./all-blob-reports

    - name: Upload HTML report
      uses: actions/upload-artifact@v4
      with:
        name: html-report--attempt-${{ github.run_attempt }}
        path: playwright-report
        retention-days: 14

此时可在 GitHub Actions 的 Artifacts 页签找到合并后的 HTML 报告。

原文合并报告截图

合并多个环境的报告

若目标是在多个环境运行同样的测试，而不是将测试分片到多台机器，就需要区分这些环境。

可以使用 TestConfig.tag 为所有测试标记环境名称。Blob 报告与后续合并工具会自动读取该标签：

配置文件：playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: process.env.CI ? 'blob' : 'html',
  tag: process.env.CI_ENVIRONMENT_NAME,  // for example "@APIv2"
});

merge-reports 命令行

npx playwright merge-reports path/to/blob-reports-dir 读取指定目录中的所有 Blob 报告，合并为单个报告。

合并不同操作系统的报告时，需要显式提供合并配置，确定测试根目录。

支持以下选项：

--reporter reporter-to-use：指定输出报告类型；多个 reporter 用逗号分隔。

npx playwright merge-reports --reporter=html,github ./blob-reports

--config path/to/config/file：指定配置输出 reporter 的 Playwright 配置文件，也可传入额外 reporter 配置。此文件可以不同于生成 Blob 报告时使用的配置。

npx playwright merge-reports --config=merge.config.ts ./blob-reports

merge.config.ts 示例：

export default {
  testDir: 'e2e',
  reporter: [['html', { open: 'never' }]],
};

来源与许可

作者：Microsoft 与 Playwright 贡献者。原文：Sharding，来自 main 分支，内容可能随分支更新。本文为中文翻译。原文 jobs: ... 块是需要并入前一工作流的节选，不能单独作为完整有效YAML；defineConfig 第一处是配置节选，完整文件须保留导入。

Playwright 仓库采用 Apache License 2.0。版权、许可条款与免责声明按该许可保留，本文翻译属于修改版；配图保留官方原文截图。

文章版权归作者所有，未经允许请勿转载。

THE END