持续集成

介绍

🌐 Introduction

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

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

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

确保 CI 代理能够运行浏览器：在 Linux 代理中使用我们的 Docker 镜像，或使用 CLI 安装你的依赖。

安装 Playwright：

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps"

运行你的测试：
```
mvn test
```

CI 配置

🌐 CI configurations

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

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

GitHub 操作

🌐 GitHub Actions

在推/拉请求时

🌐 On push/pull_request

测试将在 main/master 分支的 push 或 pull request 上运行。工作流将安装所有依赖，安装 Playwright，然后运行测试。

🌐 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.

.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@v5
    - uses: actions/setup-java@v5
      with:
        distribution: 'temurin'
        java-version: '25'
    - name: Build & Install
      run: mvn -B install -D skipTests --no-transfer-progress
    - name: Ensure browsers are installed
      run: mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps"
    - name: Run tests
      run: mvn test

通过容器

🌐 Via Containers

GitHub Actions 支持通过使用 jobs.<job_id>.container 选项在容器中运行作业。这有助于避免在主机环境中引入依赖，并在不同操作系统上进行截图/视觉回归测试时保持一致的环境。

.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/java:v1.57.0-noble
      options: --user 1001
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-java@v5
        with:
          distribution: 'temurin'
          java-version: '25'
      - name: Build & Install
        run: mvn -B install -D skipTests --no-transfer-progress
      - name: Run tests
        run: mvn 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@v5
    - uses: actions/setup-java@v5
      with:
        distribution: 'temurin'
        java-version: '25'
    - name: Build & Install
      run: mvn -B install -D skipTests --no-transfer-progress
    - name: Install Playwright
      run: mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps"
    - name: Run tests
      run: mvn test
      env:
        # This might depend on your test-runner
        PLAYWRIGHT_TEST_BASE_URL: ${{ github.event.deployment_status.target_url }}

Docker

我们有一个预构建的 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. Make sure to follow the Recommended Docker Configuration to ensure the best performance.

Azure 管道

🌐 Azure Pipelines

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

🌐 For Windows or macOS agents, no additional configuration is 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: JavaToolInstaller@1
  inputs:
    versionSpec: '25'
    jdkArchitectureOption: 'x64'
    jdkSourceOption: AzureStorage
- script: mvn -B install -D skipTests --no-transfer-progress
  displayName: 'Build and install'
- script: mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps"
  displayName: 'Install Playwright browsers'
- script: mvn test
  displayName: 'Run tests'

Azure Pipelines（容器化）

🌐 Azure Pipelines (containerized)

trigger:
- main

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

steps:
- task: JavaToolInstaller@1
  inputs:
    versionSpec: '25'
    jdkArchitectureOption: 'x64'
    jdkSourceOption: AzureStorage

- script: mvn -B install -D skipTests --no-transfer-progress
  displayName: 'Build and install'
- script: mvn test
  displayName: 'Run tests'

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-noble-development:
    docker:
      - image: mcr.microsoft.com/playwright/java:v1.57.0-noble

注意：在使用 Docker 代理定义时，你是在指定 Playwright 运行的资源类别为“中等”等级这里。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.

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/java:v1.57.0-noble' } }
   stages {
      stage('e2e-tests') {
         steps {
            sh 'mvn -B install -D skipTests --no-transfer-progress'
            sh 'mvn 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/java:v1.57.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/java:v1.57.0-noble
  script:
  ...

缓存浏览器

🌐 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 运行之间缓存浏览器二进制文件，请在你的 CI 配置中缓存这些目录，并使用 Playwright 版本的哈希值。

🌐 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 mvn 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 运行浏览器，请在实际命令前添加 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 mvn test

介绍​

CI 配置​

GitHub 操作​

在推/拉请求时​

通过容器​

部署中​

Docker​

Azure 管道​

Azure Pipelines（容器化）​

CircleCI​

Jenkins​

Bitbucket 管道​

GitLab CI​

缓存浏览器​

调试浏览器启动​

运行有头​

介绍