分片

介绍

🌐 Introduction

默认情况下，Playwright 会并行运行测试文件，并努力实现对你机器上 CPU 核心的最佳利用。为了实现更高程度的并行化，你可以通过在多台机器上同时运行测试来进一步扩展 Playwright 的测试执行。我们称这种操作模式为“分片”。在 Playwright 中，分片意味着将你的测试拆分成称为“片”的更小部分。每个片就像一个可以独立运行的单独任务。其整体目的是将测试分开，以加快测试运行时间。

🌐 By default, Playwright runs test files in parallel and strives for optimal utilization of CPU cores on your machine. In order to achieve even greater parallelisation, you can further scale Playwright test execution by running tests on multiple machines simultaneously. We call this mode of operation "sharding". Sharding in Playwright means splitting your tests into smaller parts called "shards". Each shard is like a separate job that can run independently. The whole purpose is to divide your tests to speed up test runtime.

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

🌐 When you shard your tests, each shard can run on its own, utilizing the available CPU cores. This helps speed up the testing process by doing tasks simultaneously.

在 CI 管道中，每个分片都可以作为单独的作业运行，利用 CI 管道中可用的硬件资源（如 CPU 内核）来更快地运行测试。

🌐 In a CI pipeline, each shard can run as a separate job, making use of the hardware resources available in your CI pipeline, like CPU cores, to run tests faster.

多台机器之间的分片测试

🌐 Sharding tests between multiple machines

要对测试套件进行分片，请将 --shard=x/y 传递给命令行。例如，要将套件分成四个分片，每个分片运行四分之一的测试:

🌐 To shard the test suite, pass --shard=x/y to the command line. For example, to split the suite into four shards, each running one fourth of the tests:

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

现在，如果你在不同的作业上并行运行这些分片，你的测试套件完成速度将提高四倍。

🌐 Now, if you run these shards in parallel on different jobs, your test suite completes four times faster.

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

🌐 Note that Playwright can only shard tests that can be run in parallel. By default, this means Playwright will shard test files. Learn about other options in the parallelism guide.

平衡分片

🌐 Balancing Shards

分片可以在两个不同的粒度级别上进行，这取决于你是否使用testProject.fullyParallel选项。这会影响测试在各个分片之间的分配方式。

🌐 Sharding can be done at two levels of granularity depending on whether you use the testProject.fullyParallel option or not. This affects how the tests are balanced across the shards.

使用 fullyParallel 的分片

当启用 fullyParallel: true 时，Playwright Test 会在多个分片中并行运行单个测试，确保每个分片都能获得均匀分布的测试。这允许测试级别的细粒度控制，也就是说每个分片会尝试平衡它运行的单个测试数量。这是在分片时确保负载均衡的首选模式，因为 Playwright 可以根据测试的总数优化分片执行。

🌐 When fullyParallel: true is enabled, Playwright Test runs individual tests in parallel across multiple shards, ensuring each shard receives an even distribution of tests. This allows for test-level granularity, meaning each shard will attempt to balance the number of individual tests it runs. This is the preferred mode for ensuring even load distribution when sharding, as Playwright can optimize shard execution based on the total number of tests.

没有 fullyParallel 的分片

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

🌐 Without the fullyParallel setting, Playwright Test defaults to file-level granularity, meaning entire test files are assigned to shards (note that the same file may be assigned to different shards across different projects). In this case, the number of tests per file can greatly influence shard distribution. If your test files are not evenly sized (i.e., some files contain many more tests than others), certain shards may end up running significantly more tests, while others may run fewer or even none.

主要要点：

使用 fullyParallel: true：测试在单个测试级别进行拆分，从而实现更均衡的分片执行。
没有 fullyParallel：测试在文件级别拆分，因此为了平衡分片，保持测试文件小且大小均匀非常重要。
为了确保分片的最有效使用，特别是在 CI 环境中，建议在希望实现跨分片的均衡分布时使用 fullyParallel: true。否则，你可能需要手动整理测试文件以避免不平衡。

合并来自多个分片的报告

🌐 Merging reports from multiple shards

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

🌐 In the previous example, each test shard has its own test report. If you want to have a combined report showing all the test results from all the shards, you can merge them.

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

🌐 Start with adding blob reporter to the config when running on CI:

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

Blob 报告包含有关所有已运行测试及其结果的信息，以及所有测试附件，例如跟踪和截图差异。Blob 报告可以合并并转换为任何其他 Playwright 报告。默认情况下，blob 报告将生成到 blob-report 目录中。你可以在这里了解 blob 报告选项。

🌐 Blob report contains information about all the tests that were run and their results as well as all test attachments such as traces and screenshot diffs. Blob reports can be merged and converted to any other Playwright report. By default, blob report will be generated into blob-report directory. You can learn about blob report options here.

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

🌐 To merge reports from multiple shards, put the blob report files into a single directory, for example all-blob-reports. Blob report names contain shard number, so they will not clash.

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

🌐 Afterwards, run npx playwright merge-reports command:

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

这将生成一个标准的 HTML 报告到 playwright-report 目录。

🌐 This will produce a standard HTML report into playwright-report directory.

GitHub Actions 示例

🌐 GitHub Actions example

GitHub Actions 支持使用 jobs.<job_id>.strategy.matrix 选项在多个作业之间分片测试。matrix 选项将为提供的选项的每一种可能组合运行一个单独的作业。

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

🌐 The following example shows you how to configure a job to run your tests on four machines in parallel and then merge the reports into a single report. Don't forget to add reporter: process.env.CI ? 'blob' : 'html', to your playwright.config.ts file as in the example above.

首先，我们在作业配置中添加一个 matrix 选项，并在 shardTotal: [4] 选项中包含我们想要创建的分片总数，以及 shardIndex: [1, 2, 3, 4] 选项中包含分片编号的数组。
然后我们使用 --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} 选项运行 Playwright 测试。这将为每个分片运行我们的测试命令。
最后，我们将 blob 报告上传到 GitHub Actions 的工件。这将使其他工作流中的任务可以使用该 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@v5
    - uses: actions/setup-node@v5
      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 报告。为了确保执行顺序，我们通过添加 needs: [playwright-tests] 使 merge-reports 任务依赖于我们的分片 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@v5
    - uses: actions/setup-node@v5
      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 报告。

🌐 You can now see the reports have been merged and a combined HTML report is available in the GitHub Actions Artifacts tab.

合并来自多个环境的报告

🌐 Merging reports from multiple environments

如果你想在多个环境中运行相同的测试，而不是将测试分配到多台机器上，你需要区分这些环境。

🌐 If you want to run the same tests in multiple environments, as opposed to shard your tests onto multiple machines, you need to differentiate these enviroments.

在这种情况下，指定 testConfig.tag 属性是有用的，用于将所有测试标记为环境名称。这个标签将会被 blob 报告自动识别，并在后续被合并工具使用。

🌐 In this case, it is useful to specify the testConfig.tag property, to tag all tests with the environment name. This tag will be automatically picked up by the blob report and later on by the merge tool.

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"
});

合并报告 CLI

🌐 Merge-reports CLI

npx playwright merge-reports path/to/blob-reports-dir 会读取传入目录中的所有 blob 报告，并将它们合并成一个单一的报告。

当合并来自不同操作系统的报告时，你必须提供显式的合并配置来消除应将哪个目录用作测试根目录的歧义。

🌐 When merging reports from different OS'es you'll have to provide an explicit merge config to disambiguate which directory should be used as tests root.

支持的选项：

🌐 Supported options:

--reporter reporter-to-use

生成哪份报告。可以有多个报告者，用逗号分隔。

示例：
```
npx playwright merge-reports --reporter=html,github ./blob-reports
```
--config path/to/config/file

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

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

介绍​

多台机器之间的分片测试​

平衡分片​

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

GitHub Actions 示例​

合并来自多个环境的报告​

合并报告 CLI​

介绍