掌握用于CI测试运行的Playwright GitHub Actions YAML配置
一个用于剧本编写的GitHub Actions工作流，可逐行处理：触发器、任务、代码检出、Node.js环境配置、npm ci安装、浏览器安装、测试执行以及报告生成。
当 Playwright 测试套件被上传到 GitHub 后，下一步就是让每次推送和拉取请求都能自动运行该套件。GitHub Actions 提供了这样的持续集成平台，而 Playwright 能生成的 YAML 工作流则起到了将仓库事件转换为云运行环境中的浏览器测试的作用。那些跳过这一步的团队往往要等到合并数小时之后，在笔记本电脑上才发现问题，此时定位故障就变得更加困难了。
本指南将涵盖以下内容：
- GitHub Actions 如何与 Playwright 项目结合使用
on块的作用jobs块的组织结构- 典型 Playwright 工作流中每一步的功能
最终，Playwright CI 文件的结构应足够清晰，以便在 Node 版本、浏览器或分支发生变化时进行编辑。请将示例视为模板而非黑箱：一旦各要素都明确，更换执行节点或添加冒烟测试都会变得十分简单。
Playwright 中的 GitHub Actions 与 YAML 文件简介
GitHub Actions 是托管在 GitHub 内部的 CI/CD 工具。只要仓库有变动，它就能自动执行构建、测试和部署操作。对于注重即时性的自动化框架而言，这意味着无需任何人打开笔记本电脑并手动点击运行，同样的 Playwright 命令即可在预置的执行节点镜像上执行。
通过 npm init playwright@latest 进行全新安装时会询问是否要添加 GitHub Actions 工作流。选择同意后，系统会在 .github/workflows 目录下生成一个 YAML 文件。该文件会指定 Node 版本、安装依赖项，并在向 GitHub 托管的服务器推送代码或提交拉取请求时运行 Playwright。
如果当时拒绝添加，也可以稍后手动添加相同结构：创建 .github/workflows 目录，然后手动放入工作流 YAML 文件。
Playwright 的文档在 https://playwright.dev/docs/ci-intro 的 CI 入门指南中提供了现成的示例。该文件是安装依赖项、准备浏览器以及在每次相关推送或拉取请求时执行测试的常用起点。
了解 GitHub Actions 中的 YAML 文件
下面的示例展示了一个典型的 Playwright 工作流。每个部分决定了流程何时启动，以及在 PR 显示绿色或红色状态之前运行器需要执行哪些操作。
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
on 参数
on 参数用于指定启动工作流的事件。它是流程的入口点：如果没有匹配的事件，则不会执行任何操作。
在示例中，关联了两种类型的事件：
- 推送事件：向
main或master分支推送代码会启动任务，这样默认分支上的直接提交就能立即得到测试。 - 拉取请求事件：针对
main或master分支创建或更新 PR 也会启动任务，这样待合并的代码在真正合并之前就能被检查。
这些触发条件共同覆盖了集成提交和审查流程，正是自动化框架所依赖的安全保障机制。
任务部分概述
jobs模块是在触发条件匹配后执行的工作计划。每个任务通常会声明以下内容：
- 任务名称：用于标识该工作单元的标签，如
test。 - 运行环境：机器镜像，常见的是
ubuntu-latest。 - 超时时间与条件：诸如
timeout-minutes之类的限制，用于规定任务允许的运行时长。 - 步骤：按顺序执行的操作——拉取代码、安装依赖、准备浏览器、运行测试、上传结果文件。
该部分是工作流的核心：环境准备、Playwright执行以及结果存储都依赖于它。如果某个任务失败，GitHub会首先显示出失败的步骤名称，因此在此处使用清晰的标签对于事故排查非常重要。
步骤详解
拉取代码
运行器必须持有仓库中的文件。几乎总是先进行检出操作；没有检出，后续步骤就没有任何内容可安装或执行。大多数 Playwright 工作流都会使用官方的检出动作，这样工作目录就会与触发运行的提交版本保持一致。
设置 Node.js
Playwright 基于 Node 运行。通过锁定 node-version: lts/* 可以确保运行器使用最新的长期支持版本，从而使安装和测试脚本能够运行在稳定的环境中。如果项目已经在本地统一使用了某个 LTS 版本，明确锁定该主版本也是可行的。
安装依赖项
npm ci 会根据 package-lock.json 的内容将依赖项安装到全新的项目结构中。在 CI 环境中，相比 npm install，这种方式更值得使用，因为它基于锁文件进行安装，能够在不同运行中保持一致性；而当锁文件与 package.json 不同步时，会立即抛出明显错误。
安装 Playwright 浏览器
测试需要 Chromium、Firefox 和 WebKit 的二进制文件以及相关的系统包。此步骤会下载这些浏览器，以便运行工具能够实际启动它们。如果跳过此步骤，而开发者机器上已缓存有浏览器，则常常会导致本地测试通过但 CI 测试失败的情况。
运行 Playwright 测试
这就是实际执行过程：Playwright 会在配置好的浏览器中运行项目测试，并反馈测试结果是通过还是失败。一旦出现失败，程序将以非零退出码结束运行，因此当分支保护规则要求执行相应流程时，GitHub 的检查机制会阻止代码合并。
上传测试报告
该工作流会通过upload-artifact保存生成的Playwright报告，通常设置retention-days: 30，以便在一个月内仍能查看失败情况。若运行被取消而非正常完成，可通过if: ${{ !cancelled() }}这样的条件跳过上传操作。将HTML报告作为工件保存，通常比仅为重现偶发失败的断言而重新运行测试套件更有利于调试。