Skip to main content

持续集成

介绍​

¥Introduction

Playwright 测试可以在 CI 环境中执行。我们为常见 CI 提供商创建了示例配置。

¥Playwright tests can be executed in CI environments. We have created sample configurations for common CI providers.

在 CI 上运行测试的 3 个步骤：

¥3 steps to get your tests running on CI:

  1. 确保 CI 代理可以运行浏览器：在 Linux 代理中使用 我们的 Docker 镜像 或使用 CLI 安装依赖。

    ¥Ensure CI agent can run browsers: Use our Docker image in Linux agents or install your dependencies using the CLI.

  2. 安装 Playwright：

    ¥Install Playwright:

    # Install NPM packages
    npm ci

    # Install Playwright browsers and dependencies
    npx playwright install --with-deps

  3. 运行你的测试：

    ¥Run your tests:

    npx playwright test

工作线程​

¥Workers

我们建议在 CI 环境中将 workers 设置为 "1"，以优先考虑稳定性和可重复性。按顺序运行测试可确保每个测试获得完整的系统资源，避免潜在的冲突。但是，如果你有强大的自托管 CI 系统，则可以启用 parallel 测试。对于更广泛的并行化，请考虑 sharding - 将测试分布到多个 CI 作业中。

¥We recommend setting workers to "1" in CI environments to prioritize stability and reproducibility. Running tests sequentially ensures each test gets the full system resources, avoiding potential conflicts. However, if you have a powerful self-hosted CI system, you may enable parallel tests. For wider parallelization, consider sharding - distributing tests across multiple CI jobs.

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

export default defineConfig({
  // Opt out of parallel tests on CI.
  workers: process.env.CI ? 1 : undefined,
});

CI 配置​

¥CI configurations

命令行工具 可用于在 CI 中安装所有操作系统依赖。

¥The Command line tools can be used to install all operating system dependencies in CI.

GitHub Actions​

在推/拉请求时​

¥On push/pull_request

测试将在主/主分支上的推送或拉取请求上运行。workflow 将安装所有依赖，安装 Playwright，然后运行测试。它还将创建 HTML 报告。

¥Tests will run on push or pull request on branches main/master. The workflow will install all dependencies, install Playwright and then run the tests. It will also create the HTML report.

.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@v4
    - uses: actions/setup-node@v4
      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

在 push/pull_request 上（分片）​

¥On push/pull_request (sharded)

GitHub Actions 支持 在多个作业之间分片测试。查看我们的 分片文档，了解有关分片的更多信息，并查看 GitHub actions 示例，了解如何配置作业以在多台机器上运行测试以及如何合并 HTML 报告。

¥GitHub Actions supports sharding tests between multiple jobs. Check out our sharding doc to learn more about sharding and to see a GitHub actions example of how to configure a job to run your tests on multiple machines as well as how to merge the HTML reports.

通过容器​

¥Via Containers

GitHub Actions 通过使用 jobs.<job_id>.container 选项支持 在容器中运行作业。这对于不通过依赖污染主机环境以及拥有一致的环境（例如）很有用。 跨不同操作系统的屏幕截图/视觉回归测试。

¥GitHub Actions support running jobs in a container by using the jobs.<job_id>.container option. This is useful to not pollute the host environment with dependencies and to have a consistent environment for e.g. screenshots/visual regression testing across different operating systems.

.github/workflows/playwright.yml
name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  playwright:
    name: 'Playwright Tests'
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.48.0-jammy
      options: --user 1001
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - name: Install dependencies
        run: npm ci
      - name: Run your tests
        run: npx playwright test

部署中​

¥On deployment

这将在 GitHub 部署 进入 success 状态后开始测试。Vercel 等服务使用此模式，因此你可以在其部署的环境中运行端到端测试。

¥This will start the tests after a GitHub Deployment went into the success state. Services like Vercel use this pattern so you can run your end-to-end tests on their deployed environment.

.github/workflows/playwright.yml
name: Playwright Tests
on:
  deployment_status:
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    if: github.event.deployment_status.state == 'success'
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: lts/*
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright
      run: npx playwright install --with-deps
    - name: Run Playwright tests
      run: npx playwright test
      env:
        PLAYWRIGHT_TEST_BASE_URL: ${{ github.event.deployment_status.target_url }}

快速失败​

¥Fail-Fast

大型测试套件可能需要很长时间才能执行。通过使用 --only-changed 标志执行初步测试运行，你可以运行可能首先失败的测试文件。这将为你提供更快的反馈循环和在处理 Pull 请求时略微降低的 CI 消耗。为了检测受变更集影响的测试文件，--only-changed 会分析套件的依赖图。这是一种启发式方法，可能会遗漏测试，因此在初步测试运行后始终运行完整的测试套件非常重要。

¥Large test suites can take very long to execute. By executing a preliminary test run with the --only-changed flag, you can run test files that are likely to fail first. This will give you a faster feedback loop and slightly lower CI consumption while working on Pull Requests. To detect test files affected by your changeset, --only-changed analyses your suites' dependency graph. This is a heuristic and might miss tests, so it's important that you always run the full test suite after the preliminary test run.

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@v4
      with:
        # Force a non-shallow checkout, so that we can reference $GITHUB_BASE_REF.
        # See https://github.com/actions/checkout for more details.
        fetch-depth: 0
    - uses: actions/setup-node@v4
      with:
        node-version: lts/*
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    - name: Run changed Playwright tests
      run: npx playwright test --only-changed=$GITHUB_BASE_REF
      if: github.event_name == 'pull_request'
    - 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

Docker​

我们有一个 预构建的 Docker 镜像，可以直接使用，也可以作为更新现有 Docker 定义的参考。

¥We have a pre-built Docker image which can either be used directly, or as a reference to update your existing Docker definitions.

建议配置

¥Suggested configuration

  1. 使用 Chromium 时也建议使用 --ipc=host。如果没有它，Chromium 可能会耗尽内存并崩溃。在 Docker 文档 中了解有关此选项的更多信息。

    ¥Using --ipc=host is also recommended when using Chromium. Without it Chromium can run out of memory and crash. Learn more about this option in Docker docs.

  2. 启动 Chromium 时看到其他奇怪的错误？在本地开发时尝试使用 docker run --cap-add=SYS_ADMIN 运行容器。

    ¥Seeing other weird errors when launching Chromium? Try running your container with docker run --cap-add=SYS_ADMIN when developing locally.

  3. 建议使用 --init Docker 标志或 dumb-init 以避免对 PID=1 的进程进行特殊处理。这是僵尸进程的常见原因。

    ¥Using --init Docker flag or dumb-init is recommended to avoid special treatment for processes with PID=1. This is a common reason for zombie processes.

Azure 管道​

¥Azure Pipelines

对于 Windows 或 macOS 代理，无需额外配置，只需安装 Playwright 并运行测试即可。

¥For Windows or macOS agents, no additional configuration required, just install Playwright and run your tests.

对于 Linux 代理，可以使用 我们的 Docker 容器 和 Azure Pipelines 支持 运行容器化作业。或者，你可以使用 命令行工具 安装所有必需的依赖。

¥For Linux agents, you can use our Docker container with Azure Pipelines support running containerized jobs. Alternatively, you can use Command line tools to install all necessary dependencies.

要运行 Playwright 测试，请使用此管道任务：

¥For running the Playwright tests use this pipeline task:

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '18'
  displayName: 'Install Node.js'
- script: npm ci
  displayName: 'npm ci'
- script: npx playwright install --with-deps
  displayName: 'Install Playwright browsers'
- script: npx playwright test
  displayName: 'Run Playwright tests'
  env:
    CI: 'true'

使用 Azure Pipelines 上传 Playwright 报告文件夹​

¥Uploading playwright-report folder with Azure Pipelines

如果任何 Playwright 测试失败，这将使管道运行失败。如果你还想将测试结果与 Azure DevOps 集成，请使用任务 PublishTestResults 任务，如下所示：

¥This will make the pipeline run fail if any of the playwright tests fails. If you also want to integrate the test results with Azure DevOps, use the task PublishTestResults task like so:

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '18'
  displayName: 'Install Node.js'

- script: npm ci
  displayName: 'npm ci'
- script: npx playwright install --with-deps
  displayName: 'Install Playwright browsers'
- script: npx playwright test
  displayName: 'Run Playwright tests'
  env:
    CI: 'true'
- task: PublishTestResults@2
  displayName: 'Publish test results'
  inputs:
    searchFolder: 'test-results'
    testResultsFormat: 'JUnit'
    testResultsFiles: 'e2e-junit-results.xml'
    mergeTestResults: true
    failTaskOnFailedTests: true
    testRunTitle: 'My End-To-End Tests'
  condition: succeededOrFailed()
- task: PublishPipelineArtifact@1
  inputs:
    targetPath: playwright-report
    artifact: playwright-report
    publishLocation: 'pipeline'
  condition: succeededOrFailed()

注意：JUnit 报告器需要通过以下方式进行相应配置

¥Note: The JUnit reporter needs to be configured accordingly via

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

export default defineConfig({
  reporter: [['junit', { outputFile: 'test-results/e2e-junit-results.xml' }]],
});

在 playwright.config.ts 年。

¥in playwright.config.ts.

Azure Pipelines（分片）​

¥Azure Pipelines (sharded)

trigger:
- main

pool:
  vmImage: ubuntu-latest

strategy:
  matrix:
    chromium-1:
      project: chromium
      shard: 1/3
    chromium-2:
      project: chromium
      shard: 2/3
    chromium-3:
      project: chromium
      shard: 3/3
    firefox-1:
      project: firefox
      shard: 1/3
    firefox-2:
      project: firefox
      shard: 2/3
    firefox-3:
      project: firefox
      shard: 3/3
    webkit-1:
      project: webkit
      shard: 1/3
    webkit-2:
      project: webkit
      shard: 2/3
    webkit-3:
      project: webkit
      shard: 3/3
steps:
- task: NodeTool@0
  inputs:
    versionSpec: '18'
  displayName: 'Install Node.js'

- script: npm ci
  displayName: 'npm ci'
- script: npx playwright install --with-deps
  displayName: 'Install Playwright browsers'
- script: npx playwright test --project=$(project) --shard=$(shard)
  displayName: 'Run Playwright tests'
  env:
    CI: 'true'

Azure Pipelines（容器化）​

¥Azure Pipelines (containerized)

trigger:
- main

pool:
  vmImage: ubuntu-latest
container: mcr.microsoft.com/playwright:v1.48.0-noble

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '18'
  displayName: 'Install Node.js'

- script: npm ci
  displayName: 'npm ci'
- script: npx playwright test
  displayName: 'Run Playwright tests'
  env:
    CI: 'true'

CircleCI​

在 CircleCI 上运行 Playwright 与在 GitHub Actions 上运行非常相似。为了指定预构建的 Playwright Docker 镜像，只需在配置中使用 docker: 修改代理定义，如下所示：

¥Running Playwright on CircleCI is very similar to running on GitHub Actions. In order to specify the pre-built Playwright Docker image, simply modify the agent definition with docker: in your config like so:

executors:
  pw-jammy-development:
    docker:
      - image: mcr.microsoft.com/playwright:v1.48.0-noble

注意：使用 docker 代理定义时，你将 playwright 运行的资源类指定为 'medium' 层 此处。Playwright 的默认行为是将工作线程数量设置为检测到的核心数量（在中等层的情况下为 2）。将工作线程数量覆盖到大于此数量将导致不必要的超时和失败。

¥Note: When using the docker agent definition, you are specifying the resource class of where playwright runs to the 'medium' tier here. The default behavior of Playwright is to set the number of workers to the detected core count (2 in the case of the medium tier). Overriding the number of workers to greater than this number will cause unnecessary timeouts and failures.

CircleCI 中的分片​

¥Sharding in CircleCI

CircleCI 中的分片索引为 0，这意味着你需要覆盖默认并行度 ENV VARS。以下示例演示了如何通过向 CIRCLE_NODE_INDEX 添加 1 以传递到 --shard cli arg 来运行 CircleCI 并行度为 4 的 Playwright。

¥Sharding in CircleCI is indexed with 0 which means that you will need to override the default parallelism ENV VARS. The following example demonstrates how to run Playwright with a CircleCI Parallelism of 4 by adding 1 to the CIRCLE_NODE_INDEX to pass into the --shard cli arg.

  playwright-job-name:
    executor: pw-jammy-development
    parallelism: 4
    steps:
      - run: SHARD="$((${CIRCLE_NODE_INDEX}+1))"; npx playwright test -- --shard=${SHARD}/${CIRCLE_NODE_TOTAL}

Jenkins​

Jenkins 支持管道的 Docker 代理。使用 Playwright Docker 镜像 在 Jenkins 上运行测试。

¥Jenkins supports Docker agents for pipelines. Use the Playwright Docker image to run tests on Jenkins.

pipeline {
   agent { docker { image 'mcr.microsoft.com/playwright:v1.48.0-noble' } }
   stages {
      stage('e2e-tests') {
         steps {
            sh 'npm ci'
            sh 'npx playwright test'
         }
      }
   }
}

Bitbucket 管道​

¥Bitbucket Pipelines

Bitbucket Pipelines 可以使用公共 Docker 镜像作为构建环境。要在 Bitbucket 上运行 Playwright 测试，请使用我们的公共 Docker 映像 (参见 Dockerfile)。

¥Bitbucket Pipelines can use public Docker images as build environments. To run Playwright tests on Bitbucket, use our public Docker image (see Dockerfile).

image: mcr.microsoft.com/playwright:v1.48.0-noble

GitLab CI​

要在 GitLab 上运行 Playwright 测试，请使用我们的公共 Docker 映像 (参见 Dockerfile)。

¥To run Playwright tests on GitLab, use our public Docker image (see Dockerfile).

stages:
  - test

tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.48.0-noble
  script:
  ...

分片​

¥Sharding

GitLab CI 支持使用 parallel 关键字的 在多个作业之间分片测试。测试作业将被分成多个并行运行的较小作业。并行作业按 job_name 1/N 至 job_name N/N 的顺序命名。

¥GitLab CI supports sharding tests between multiple jobs using the parallel keyword. The test job will be split into multiple smaller jobs that run in parallel. Parallel jobs are named sequentially from job_name 1/N to job_name N/N.

stages:
  - test

tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.48.0-noble
  parallel: 7
  script:
    - npm ci
    - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL

GitLab CI 还支持使用 parallel:matrix 选项在多个作业之间进行分片测试。测试作业将在单个管道中并行运行多次，但每个作业实例具有不同的变量值。在下面的示例中，我们有 2 个 PROJECT 值和 10 个 SHARD 值，总共需要运行 20 个作业。

¥GitLab CI also supports sharding tests between multiple jobs using the parallel:matrix option. The test job will run multiple times in parallel in a single pipeline, but with different variable values for each instance of the job. In the example below, we have 2 PROJECT values and 10 SHARD values, resulting in a total of 20 jobs to be run.

stages:
  - test

tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.48.0-noble
  parallel:
    matrix:
      - PROJECT: ['chromium', 'webkit']
        SHARD: ['1/10', '2/10', '3/10', '4/10', '5/10', '6/10', '7/10', '8/10', '9/10', '10/10']
  script:
    - npm ci
    - npx playwright test --project=$PROJECT --shard=$SHARD

谷歌云构建​

¥Google Cloud Build

要在 Google Cloud Build 上运行 Playwright 测试，请使用我们的公共 Docker 映像 (参见 Dockerfile)。

¥To run Playwright tests on Google Cloud Build, use our public Docker image (see Dockerfile).

steps:
- name: mcr.microsoft.com/playwright:v1.48.0-noble
  script: 
  ...
  env:
  - 'CI=true'

无人机​

¥Drone

要在 Drone 上运行 Playwright 测试，请使用我们的公共 Docker 映像 (参见 Dockerfile)。

¥To run Playwright tests on Drone, use our public Docker image (see Dockerfile).

kind: pipeline
name: default
type: docker

steps:
  - name: test
    image: mcr.microsoft.com/playwright:v1.48.0-jammy
    commands:
      - npx playwright test

缓存浏览器​

¥Caching browsers

不建议缓存浏览器二进制文件，因为恢复缓存所需的时间与下载二进制文件所需的时间相当。特别是在 Linux 下，需要安装 操作系统依赖，它是不可缓存的。

¥Caching browser binaries is not recommended, since the amount of time it takes to restore the cache is comparable to the time it takes to download the binaries. Especially under Linux, operating system dependencies need to be installed, which are not cacheable.

如果你仍想在 CI 运行之间缓存浏览器二进制文件，请根据 Playwright 版本的哈希在 CI 配置中缓存 这些目录。

¥If you still want to cache the browser binaries between CI runs, cache these directories in your CI configuration, against a hash of the Playwright version.

调试浏览器启动​

¥Debugging browser launches

Playwright 支持 DEBUG 环境变量在执行过程中输出调试日志。将其设置为 pw:browser 在调试 Error: Failed to launch browser 错误时很有帮助。

¥Playwright supports the DEBUG environment variable to output debug logs during execution. Setting it to pw:browser is helpful while debugging Error: Failed to launch browser errors.

DEBUG=pw:browser npx playwright test

运行有头​

¥Running headed

默认情况下，Playwright 以无头模式启动浏览器。请参阅我们的 运行测试 指南，了解如何在有头模式下运行测试。

¥By default, Playwright launches browsers in headless mode. See in our Running tests guide how to run tests in headed mode.

在 Linux 代理上，引导执行需要安装 Xvfb。我们的 Docker 镜像 和 GitHub Action 预装了 Xvfb。要使用 Xvfb 在 head 模式下运行浏览器，请在实际命令之前添加 xvfb-run。

¥On Linux agents, headed execution requires Xvfb to be installed. Our Docker image and GitHub Action have Xvfb pre-installed. To run browsers in headed mode with Xvfb, add xvfb-run before the actual command.

xvfb-run npx playwright test