跳到主要内容

测试分片

简介​

默认情况下，Playwright 会以并行方式运行测试文件，并尽可能充分利用机器上的 CPU 核心。为了实现更高级别的并行化，您可以通过在多台机器上同时运行测试来进一步扩展 Playwright 测试执行。我们将这种运行模式称为"分片"(sharding)。在 Playwright 中，分片意味着将测试分割成更小的部分，称为"分片"。每个分片就像一个可以独立运行的独立任务。这样做的目的是通过分割测试来加快测试运行时间。

当您对测试进行分片时，每个分片都可以独立运行，利用可用的 CPU 核心。这有助于通过同时执行任务来加速测试过程。

在 CI 流水线中，每个分片可以作为独立任务运行，利用 CI 流水线中可用的硬件资源（如 CPU 核心）来更快地运行测试。

在多台机器间分片测试​

要对测试套件进行分片，请在命令行中传入 --shard=x/y 参数。例如，要将测试套件分成四个分片，每个分片运行四分之一的测试：

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

现在，如果您在不同的任务上并行运行这些分片，您的测试套件将可以快四倍完成。

请注意，Playwright 只能对可以并行运行的测试进行分片。默认情况下，这意味着 Playwright 会对测试文件进行分片。更多选项请参阅并行化指南。

分片负载均衡​

根据是否使用 testProject.fullyParallel 选项，分片可以在两个粒度级别上进行。这会影响测试在分片间的分配方式。

启用 fullyParallel 的分片

当启用 fullyParallel: true 时，Playwright Test 会在多个分片间并行运行单个测试，确保每个分片获得均匀分布的测试。这实现了测试级别的粒度控制，意味着每个分片会尝试平衡其运行的独立测试数量。这是确保分片负载均衡的首选模式，因为 Playwright 可以根据测试总数优化分片执行。

不启用 fullyParallel 的分片

在没有 fullyParallel 设置的情况下，Playwright Test 默认采用文件级别的粒度，意味着整个测试文件会被分配给分片（注意同一个文件可能在不同项目中被分配到不同分片）。这种情况下，每个文件中的测试数量会极大影响分片分布。如果测试文件大小不均（即某些文件包含的测试远多于其他文件），某些分片可能最终运行明显更多的测试，而其他分片可能运行较少甚至没有测试。

关键要点：

  • 启用 fullyParallel: true：测试在单个测试级别进行分割，实现更均衡的分片执行。
  • 不启用 fullyParallel：测试在文件级别进行分割，因此为了平衡分片，保持测试文件小而均匀很重要。
  • 为了最有效地利用分片功能，特别是在 CI 环境中，建议在追求分片间均衡分布时使用 fullyParallel: true。否则，可能需要手动组织测试文件以避免不均衡。

合并来自多个分片的测试报告​

在前面的示例中，每个测试分片都有自己的测试报告。如果想要获得一个显示所有分片测试结果的合并报告，可以将它们合并。

首先在 CI 运行时向配置中添加 blob 报告器：

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

Blob 报告包含所有运行的测试及其结果的信息，以及所有测试附件，如追踪记录和截图差异。Blob 报告可以合并并转换为任何其他 Playwright 报告格式。默认情况下，blob 报告会生成在 blob-report 目录中。

要合并来自多个分片的报告，请将所有 blob 报告文件放入一个目录，例如 all-blob-reports。Blob 报告名称包含分片编号，因此不会发生冲突。

之后，运行 npx playwright merge-reports 命令：

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

这将在 playwright-report 目录中生成标准的 HTML 报告。

GitHub Actions 示例​

GitHub Actions 支持使用 jobs.<job_id>.strategy.matrix 选项在多个任务间分片运行测试。matrix 选项会为提供的每个选项组合运行一个独立的任务。

以下示例展示了如何配置一个任务，在四台机器上并行运行测试，然后将报告合并为单一报告。别忘了像上面的示例一样，在你的 playwright.config.ts 文件中添加 reporter: process.env.CI ? 'blob' : 'html',。

  1. 首先我们在任务配置中添加 matrix 选项，其中 shardTotal: [4] 表示我们想要创建的分片总数，shardIndex: [1, 2, 3, 4] 是分片编号数组。
  2. 然后我们使用 --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} 选项运行 Playwright 测试。这将为每个分片运行测试命令。
  3. 最后我们将 blob 报告上传到 GitHub Actions Artifacts。这将使 blob 报告可供工作流中的其他任务使用。
.github/workflows/playwright.yml
name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  playwright-tests:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shardIndex: [1, 2, 3, 4]
        shardTotal: [4]
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: lts/*
    - name: 安装依赖
      run: npm ci
    - name: 安装 Playwright 浏览器
      run: npx playwright install --with-deps

    - name: 运行 Playwright 测试
      run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}

    - name: 上传 blob 报告到 GitHub Actions Artifacts
      if: ${{ !cancelled() }}
      uses: actions/upload-artifact@v4
      with:
        name: blob-report-${{ matrix.shardIndex }}
        path: blob-report
        retention-days: 1
  1. 所有分片完成后，你可以运行一个独立任务来合并报告并生成一个组合的 HTML 报告。为了确保执行顺序，我们通过添加 needs: [playwright-tests] 使 merge-reports 任务依赖于分片的 playwright-tests 任务。
.github/workflows/playwright.yml
jobs:
...
  merge-reports:

# 在 playwright-tests 后合并报告，即使某些分片测试失败
    if: ${{ !cancelled() }}
    needs: [playwright-tests]

    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: lts/*
    - name: 安装依赖
      run: npm ci

    - name: 从 GitHub Actions 制品下载 blob 报告
      uses: actions/download-artifact@v4
      with:
        path: all-blob-reports
        pattern: blob-report-*
        merge-multiple: true

    - name: 合并为 HTML 报告
      run: npx playwright merge-reports --reporter html ./all-blob-reports

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

现在您可以看到报告已被合并，在 GitHub Actions 制品选项卡中可以获取合并后的 HTML 报告。

image

合并报告 CLI 工具​

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

当需要合并来自不同操作系统的报告时，必须提供一个明确的合并配置来消除歧义，确定应该使用哪个目录作为测试根目录。

支持的选项：

  • --reporter 使用的报告器

    指定要生成的报告类型。可以指定多个报告器，用逗号分隔。

    示例：

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

  • --config 配置文件路径

    指定包含输出报告器的 Playwright 配置文件。使用此选项可以向输出报告器传递额外的配置。这个配置文件可以与创建 blob 报告时使用的配置文件不同。

    示例：

    npx playwright merge-reports --config=merge.config.ts ./blob-reports
    merge.config.ts
    export default {
      testDir: 'e2e',
      reporter: [['html', { open: 'never' }]],
    };