设置 CI

介绍

Playwright 测试可以在任何 CI 提供商上运行。本指南介绍了一种在 GitHub 上使用 GitHub Actions 运行测试的方法。如果你想了解更多内容，或者了解如何配置其他 CI 提供商，请查看我们关于持续集成的详细文档。

你将学习

• 如何设置 GitHub Actions
• 如何查看测试日志
• 如何查看 HTML 报告
• 如何查看跟踪
• 如何在 Web 上发布报告

设置 GitHub Actions

在使用 VS Code 扩展安装 Playwright，或使用 npm init playwright@latest 时，系统会为你提供添加 GitHub Actions 工作流的选项。这会在 .github/workflows 文件夹中创建一个 playwright.yml 文件，其中包含了在每次向 main/master 分支推送代码以及提交拉取请求时运行测试所需的一切。该文件如下所示：

.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-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
    - uses: actions/upload-artifact@v4
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

该工作流会执行以下步骤：

1. 克隆你的仓库
2. 安装 Node.js
3. 安装 NPM 依赖
4. 安装 Playwright 浏览器
5. 运行 Playwright 测试
6. 将 HTML 报告上传到 GitHub UI

要了解更多信息，请参阅 “Understanding GitHub Actions”。

创建仓库并推送到 GitHub

一旦你设置好了 GitHub Actions 工作流，你只需要在 GitHub 上创建一个仓库，或者将代码推送到一个已有仓库中。按照 GitHub 上的说明进行操作，不要忘记使用 git init 命令初始化一个 Git 仓库，这样你就可以 add、commit 和 push 你的代码。

(图略)

打开工作流

点击 Actions 标签页即可查看工作流。在这里，你可以看到测试是通过还是失败。

(图略)

查看测试日志

点击某次工作流运行后，你会看到 GitHub 执行的所有操作。点击 Run Playwright tests，即可查看错误消息、预期结果与实际结果，以及调用日志。

(图略)

HTML 报告

HTML 报告会展示你测试的完整报告。你可以按浏览器、通过的测试、失败的测试、跳过的测试以及不稳定的测试来筛选报告。

下载 HTML 报告

在 Artifacts 部分，点击 playwright-report，即可将报告下载为一个 zip 文件。

(图略)

查看 HTML 报告

直接在本地打开报告并不会按预期工作，因为你需要一个 Web 服务器才能让所有内容正常运行。请先解压 zip 文件，最好解压到一个已经安装了 Playwright 的文件夹中。然后在命令行中切换到报告所在目录，并使用 npx playwright show-report，后跟解压后的文件夹名称。这样会启动一个服务，并允许你在浏览器中查看报告。

npx playwright show-report name-of-my-extracted-playwright-report

(图略)

要了解更多关于报告的信息，请查看我们关于 HTML Reporter 的详细指南。

查看跟踪

在你使用 npx playwright show-report 启动报告服务后，点击测试文件名旁边的跟踪图标，就可以打开该测试的跟踪。然后你可以查看测试的跟踪，并检查每一个操作，尝试找出测试失败的原因。

(图略)

在 Web 上发布报告

将 HTML 报告下载为 zip 文件并不是非常方便。不过，我们可以利用 Azure Storage 的静态网站托管能力，以简单高效的方式在互联网上提供 HTML 报告，所需配置也很少。

1. 创建一个 Azure Storage 账户。
2. 为该存储账户启用静态网站托管。
3. 在 Azure 中创建一个 Service Principal，并授予其对 Azure Blob Storage 的访问权限。命令执行成功后，会显示下一步要用到的凭据。

az ad sp create-for-rbac --name "github-actions" --role "Storage Blob Data Contributor" --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>/providers/Microsoft.Storage/storageAccounts/<STORAGE_ACCOUNT_NAME>

4. 使用上一步得到的凭据，在你的 GitHub 仓库中设置加密的 secrets。进入仓库的设置，在 GitHub Actions secrets 中添加以下 secrets：

• AZCOPY_SPA_APPLICATION_ID
• AZCOPY_SPA_CLIENT_SECRET
• AZCOPY_TENANT_ID

关于如何使用客户端密钥对 service principal 进行授权的详细指南，请参阅 Microsoft 文档。

5. 添加一个步骤，将 HTML 报告上传到 Azure Storage。

.github/workflows/playwright.yml

...
  - name: Upload HTML report to Azure
    shell: bash
    run: |
      REPORT_DIR='run-${{ github.run_id }}-${{ github.run_attempt }}'
      azcopy cp --recursive "./playwright-report/*" "https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net/$web/$REPORT_DIR"
      echo "::notice title=HTML report url::https://<STORAGE_ACCOUNT_NAME>.z1.web.core.windows.net/$REPORT_DIR/index.html"
    env:
      AZCOPY_AUTO_LOGIN_TYPE: SPN
      AZCOPY_SPA_APPLICATION_ID: '${{ secrets.AZCOPY_SPA_APPLICATION_ID }}'
      AZCOPY_SPA_CLIENT_SECRET: '${{ secrets.AZCOPY_SPA_CLIENT_SECRET }}'
      AZCOPY_TENANT_ID: '${{ secrets.AZCOPY_TENANT_ID }}'

$web 存储容器中的内容可以通过该网站的公共 URL 在浏览器中访问。

Note

对于从 fork 仓库创建的拉取请求，这一步不会生效，因为这类工作流无法访问 secrets。

正确处理 Secrets

诸如跟踪文件、HTML 报告，甚至控制台日志等构件都包含你的测试执行信息。它们可能包含敏感数据，例如测试用户的凭据、指向预发布后端的访问令牌、测试源码，有时甚至还包括你的应用源码。请像对待这些敏感数据一样谨慎对待这些文件。

如果你在 CI 工作流中上传报告和跟踪，请确保只上传到可信的构件存储中，或者在上传前对文件进行加密。与团队成员共享构件时也是一样：请使用可信的文件共享方式，或者在共享前先对文件进行加密。

接下来做什么

• 学习如何使用 Locators
• 学习如何执行 Actions
• 学习如何编写 Assertions
• 进一步了解 Trace Viewer
• 了解更多在 GitHub Actions 上运行测试的方法
• 了解更多在其他 CI 提供商上运行测试的方法