CI中自动录制失败测试的Playwright Trace：原理、配置与工程实践

1. 项目概述：为什么我们需要在CI中自动录制失败用例的Trace？

在自动化测试的世界里，最让人头疼的往往不是写测试用例，而是当它们在持续集成（CI）环境中失败时，如何快速定位问题。你可能会遇到这样的情况：本地跑得好好的测试，一到CI流水线上就莫名其妙地挂了。日志里只留下一句模糊的“TimeoutError: Timeout 30000ms exceeded.”，或者一个元素定位失败。面对这样的报错，你就像面对一个黑盒，只能靠猜——是网络慢了？是页面没加载完？还是元素选择器突然失效了？

传统的解决方案是截图和录屏。截图能提供失败瞬间的静态画面，但丢失了上下文和交互信息；录屏能记录过程，但文件体积大、不易定位关键帧，而且无法进行交互式回放。这时，Playwright的Trace Viewer功能就成了一把利器。它记录的不是视频，而是一系列浏览器操作（网络请求、DOM快照、控制台日志、执行轨迹等）的元数据，生成一个轻量级的、可交互的“时光机”。你可以像操作一个调试器一样，逐帧回放测试步骤，查看每一步的页面状态、网络请求和日志，精准定位问题根源。

然而，手动开启Trace录制会拖慢所有测试的执行速度，并产生巨大的存储开销。最经济的做法是：只在测试失败时，自动录制并保存Trace文件。这就是“Playwright Trace Viewer CI集成”项目的核心价值。它不是一个独立工具，而是一套将Playwright的失败追踪能力无缝嵌入到CI/CD流水线中的工程实践方案。通过它，开发者和测试人员无需登录CI服务器、无需手动复现，就能直接在流水线报告或归档物中，获取一个可点击、可回放、信息完整的失败现场记录，将排查时间从小时级缩短到分钟级。

2. 整体方案设计与技术选型考量

实现“失败用例自动录制可交互Trace”并非单一命令，而是一个涉及测试框架、CI系统、文件存储和报告展示的闭环。我们需要拆解为几个核心环节：触发录制、收集文件、持久化存储、提供访问。

2.1 核心组件与工作流

整个方案围绕以下几个核心组件构建：

1. Playwright Test Runner： 执行测试的主体，负责在测试失败时触发Trace录制。
2. CI Runner/Agent： 执行CI流水线的环境（如GitHub Actions的ubuntu-latestrunner，或Jenkins的agent节点）。
3. 对象存储或文件服务器： 用于存储生成的.zip格式的Trace文件。这是关键，因为CI Runner通常是临时的，测试结束后文件会丢失。
4. Trace Viewer： Playwright提供的查看工具，可以是本地的playwright show-trace命令，也可以是集成了Trace Viewer的测试报告系统（如Playwright HTML Report）。

工作流如下：

• 测试执行： CI流水线中，正常执行Playwright测试套件。
• 失败捕获： 通过Playwright Test的配置或编程式钩子，监听测试失败事件。
• 按需录制： 仅对失败的测试用例，启动Trace录制（或确保其已被录制）。录制的内容通常包含失败前若干步骤，以便回溯。.文件收集与上传： 测试运行结束后，将失败用例对应的Trace文件从临时目录收集起来。
• 持久化存储： 将这些Trace文件上传到可持久访问的存储服务（如AWS S3、Google Cloud Storage、Azure Blob，或自建的MinIO、Artifactory等）。
• 报告关联： 在CI的测试报告页面（如GitHub Actions的Annotations、GitLab CI的Job Artifacts，或第三方报告如Allure、Playwright HTML Report）中，生成一个可直接点击下载或在线查看Trace的链接。

2.2 关键配置：playwright.config.ts的智慧

一切始于配置文件。Playwright Test提供了强大的配置项来管理Trace。

// playwright.config.ts import { defineConfig } from '@playwright/test'; export default defineConfig({ // ... 其他配置 use: { // 全局为所有测试启用Trace，但设置为‘on-first-retry’或‘on-all-retries’是更佳实践 // trace: 'on', // 不推荐：所有测试都录，CI上会非常慢且占空间 trace: 'retain-on-failure', // 核心配置：仅在失败时保留Trace // 或使用更精细的 ‘on-first-retry’ 配合重试机制 // trace: 'on-first-retry', }, // 配置重试机制，对于Flaky测试，配合‘on-first-retry’可以只录重试时的Trace retries: process.env.CI ? 2 : 0, // 在CI环境中自动重试2次 // 输出Trace的目录 reporter: [ ['html', { outputFolder: 'playwright-report' }], // HTML报告 // 可以添加其他reporter ], });

为什么选择trace: 'retain-on-failure'？这是本方案的首选。它的行为是：为每一个测试用例都录制Trace，但如果测试通过了，则在测试结束时立即清理掉对应的Trace文件；只有测试失败了，Trace文件才会被保留下来。这看似“全录”，实则“按需保存”。在CI环境中，磁盘I/O和存储空间是宝贵的，retain-on-failure在保证能捕获任何失败现场的同时，最大程度减少了无用文件的堆积。相比之下，trace: 'on'会保留所有Trace，导致资源浪费；而trace: 'off'则完全无法捕获失败信息。

on-first-retry的妙用如果你的测试套件存在一些不稳定的（Flaky）测试，可以结合重试机制使用trace: 'on-first-retry'。这样，只有在第一次重试时才录制Trace。如果测试直接通过，不录制；如果第一次失败但重试后通过，则录制了失败那次的重试过程，有助于分析Flaky原因。这比retain-on-failure更节省资源，但可能错过一些非重试路径的失败。

实操心得：Trace目录管理Playwright默认将Trace文件输出到test-results/目录下。每个测试套件（项目）会生成独立的子目录。在CI中，务必确保这个目录不会被缓存，以免不同流水线运行的Trace文件互相污染。同时，在流水线结束时，应有步骤清理旧的test-results，只保留我们想要上传的那些失败用例的Trace。

2.3 CI系统的选择与集成策略

不同的CI系统（GitHub Actions, GitLab CI, Jenkins, CircleCI等）在文件收集、存储和展示方面有细微差别。但核心思想一致：将Trace文件作为“制品”（Artifacts）进行上传和关联。

• GitHub Actions： 使用actions/upload-artifact和actions/download-artifact动作。可以将test-results整个目录或过滤后的失败用例Trace文件上传。在Job Summary页面可以直接看到和下载这些制品。
• GitLab CI： 使用artifacts关键字在.gitlab-ci.yml中定义。可以指定过期时间和路径。Trace文件会打包在Job的页面供下载。
• Jenkins： 使用archiveArtifacts步骤或stash/unstash指令。也可以集成插件将制品归档到Jenkins master或外部存储。

更进阶的策略是使用云存储服务。将Trace文件上传到S3等对象存储，并生成一个带有短暂过期时间的预签名URL（Presigned URL），然后将这个URL以某种形式（如注释到PR，或写入自定义的测试报告）展示出来。这样做的好处是：

1. 存储独立： 不占用CI系统本身的存储配额。
2. 访问控制灵活： 可以通过URL控制访问权限和有效期。
3. 易于集成： 生成的URL可以轻松嵌入到各种通知和报告系统中。

3. 分步实现：以GitHub Actions为例的完整流水线

让我们以一个使用GitHub Actions的Node.js项目为例，构建完整的集成流水线。假设项目使用Playwright for TypeScript/JavaScript。

3.1 基础测试执行流水线

首先，创建一个基础的.github/workflows/playwright.yml文件。

name: Playwright Tests on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: timeout-minutes: 60 runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '18' - name: Install dependencies run: npm ci - name: Install Playwright Browsers run: npx playwright install --with-deps chromium - name: Run Playwright tests run: npx playwright test # 注意：这里我们依赖 playwright.config.ts 中的 trace: 'retain-on-failure' - name: Upload Playwright HTML Report if: always() # 无论成功失败都上传报告 uses: actions/upload-artifact@v4 with: name: playwright-html-report path: playwright-report/ retention-days: 7 - name: Upload Trace files for failed tests if: failure() # 只有测试失败时才执行此步骤 uses: actions/upload-artifact@v4 with: name: playwright-traces-failed path: test-results/ retention-days: 14 # Trace文件可以保留更久一些以便分析

这个流水线已经具备了基本功能：运行测试，并在失败时上传整个test-results目录。但这里有个问题：我们上传了所有的测试结果文件，包括截图、视频（如果配置了）和通过的测试的残留文件。我们需要更精确。

3.2 精准收集与上传失败用例的Trace

我们需要一个脚本，在测试运行后，只找出失败测试对应的Trace文件（通常是.zip格式）。我们可以利用Playwright Test的JSON报告或直接解析test-results目录结构。

创建一个脚本scripts/collect-failed-traces.js：

const fs = require('fs'); const path = require('path'); const { execSync } = require('child_process'); /** * 收集失败测试的Trace文件。 * 策略：读取Playwright生成的JSON行报告（如果配置了），或解析test-results目录。 */ function collectFailedTraces() { const resultsDir = path.join(process.cwd(), 'test-results'); const outputDir = path.join(process.cwd(), 'failed-traces'); // 临时收集目录 if (!fs.existsSync(resultsDir)) { console.log('No test-results directory found.'); return; } // 创建临时输出目录 if (!fs.existsSync(outputDir)) { fs.mkdirSync(outputDir, { recursive: true }); } // 方法一：如果使用JSON行reporter，可以解析它来精确知道哪些测试失败了 // 这里我们演示更通用的方法二：遍历test-results，寻找包含“.zip”的目录（即Trace文件） let foundAny = false; const projects = fs.readdirSync(resultsDir); for (const project of projects) { const projectPath = path.join(resultsDir, project); if (!fs.statSync(projectPath).isDirectory()) continue; const testDirs = fs.readdirSync(projectPath); for (const testDir of testDirs) { const testPath = path.join(projectPath, testDir); if (!fs.statSync(testPath).isDirectory()) continue; // 在每个测试目录中寻找trace.zip文件 const traceFile = path.join(testPath, 'trace.zip'); if (fs.existsSync(traceFile)) { foundAny = true; // 复制到收集目录，可以按“项目-测试名”重命名以避免冲突 const destFileName = `${project}-${testDir}-trace.zip`; const destPath = path.join(outputDir, destFileName); fs.copyFileSync(traceFile, destPath); console.log(`Collected trace: ${destFileName}`); } } } if (!foundAny) { console.log('No trace files found for failed tests.'); // 清理空目录，避免上传空制品 fs.rmSync(outputDir, { recursive: true, force: true }); } } collectFailedTraces();

然后更新你的GitHub Actions工作流，在运行测试后执行这个脚本：

- name: Run Playwright tests run: npx playwright test # 注意：这里我们依赖 playwright.config.ts 中的 trace: 'retain-on-failure' - name: Collect traces from failed tests if: failure() # 或 always()，配合脚本内的空目录清理 run: node scripts/collect-failed-traces.js - name: Upload Trace files for failed tests if: failure() uses: actions/upload-artifact@v4 with: name: playwright-traces-failed path: failed-traces/ # 上传我们精准收集的目录 retention-days: 14

注意事项：Trace文件命名与冲突上述脚本的简单重命名（${project}-${testDir}）在测试名包含特殊字符或路径较长时可能有问题。更健壮的做法是使用测试的testId或对测试名进行安全编码（如slugify）。此外，如果同一个测试文件中的多个测试用例失败，它们的目录名可能相同（Playwright会添加后缀），直接复制可能导致覆盖。在实际应用中，可以考虑使用更稳定的唯一标识符，或者直接上传整个结构清晰的子目录。

3.3 集成HTML报告并关联Trace

Playwright HTML报告本身支持与Trace文件关联。如果报告和Trace文件在相对路径下，报告中的失败测试项旁边会直接显示一个“View trace”按钮。

为了让在CI上传的HTML报告也能关联到Trace，我们需要确保报告和Trace的相对路径关系在CI环境中得以保持。一个常见做法是将它们放在同一个制品目录下，或者修改HTML报告的生成路径。

更新playwright.config.ts，将报告输出到包含Trace的目录内：

export default defineConfig({ // ... 其他配置 reporter: [ ['html', { outputFolder: 'test-results/playwright-report' }], // 将报告输出到test-results下 ], });

然后更新流水线，上传整个test-results目录（或包含报告和Trace的子目录）：

- name: Upload Test Results (Report & Traces) if: always() uses: actions/upload-artifact@v4 with: name: playwright-test-results path: test-results/ retention-days: 14

这样，下载playwright-test-results制品后，打开playwright-report/index.html，点击失败的测试，就能直接查看关联的Trace了。

4. 进阶：上传至云存储与动态链接生成

对于大型项目或需要长期保存Trace的场景，使用GitHub Actions的制品功能可能受存储空间和时长限制。上传到云存储（如AWS S3）是更专业的方案。

4.1 使用AWS S3存储Trace

假设你已经配置了AWS的访问密钥（AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY）作为GitHub仓库的Secrets。

首先，安装AWS CLI或使用相关的GitHub Action。我们使用aws-actions/configure-aws-credentials来配置凭证，然后使用awsCLI命令上传。

更新流水线，添加上传到S3的步骤：

- name: Configure AWS credentials if: failure() # 仅在失败时配置并上传 uses: aws-actions/configure-aws-credentials@v4 with: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} aws-region: us-east-1 # 你的S3区域 - name: Upload failed traces to S3 if: failure() run: | # 为本次运行创建一个唯一路径，例如基于GITHUB_RUN_ID S3_PATH="s3://your-bucket-name/playwright-traces/${{ github.repository }}/${{ github.run_id }}/" # 使用aws cli同步整个failed-traces目录 aws s3 sync failed-traces/ $S3_PATH --acl bucket-owner-full-control # 输出可访问的URL前缀（需要设置桶为公共可读或使用预签名URL，后者更安全） echo "Trace files uploaded to: $S3_PATH"

4.2 生成预签名URL并通知

直接公开S3桶不安全。更好的做法是生成一个预签名URL，该URL在有限时间内（如24小时）有效。这需要一点额外的脚本逻辑。

创建一个脚本scripts/upload-and-generate-urls.js，使用AWS SDK for JavaScript：

const { S3Client, PutObjectCommand, GetObjectCommand } = require('@aws-sdk/client-s3'); const { getSignedUrl } = require('@aws-sdk/s3-request-presigner'); const fs = require('fs'); const path = require('path'); const client = new S3Client({ region: process.env.AWS_REGION || 'us-east-1' }); const bucketName = process.env.AWS_S3_BUCKET; async function uploadFile(filePath, key) { const fileStream = fs.createReadStream(filePath); const command = new PutObjectCommand({ Bucket: bucketName, Key: key, Body: fileStream, }); await client.send(command); console.log(`Uploaded: ${key}`); // 生成一个24小时有效的预签名下载URL const getCommand = new GetObjectCommand({ Bucket: bucketName, Key: key }); const signedUrl = await getSignedUrl(client, getCommand, { expiresIn: 86400 }); // 24小时 return signedUrl; } async function main() { const tracesDir = path.join(process.cwd(), 'failed-traces'); if (!fs.existsSync(tracesDir)) { console.log('No failed traces to upload.'); return; } const traceFiles = fs.readdirSync(tracesDir).filter(f => f.endsWith('.zip')); const uploadPromises = []; const urlMap = {}; for (const file of traceFiles) { const localPath = path.join(tracesDir, file); const s3Key = `playwright-traces/${process.env.GITHUB_REPOSITORY}/${process.env.GITHUB_RUN_ID}/${file}`; uploadPromises.push( uploadFile(localPath, s3Key).then(url => { urlMap[file] = url; }) ); } await Promise.all(uploadPromises); // 将URL映射表输出到环境变量或文件，供后续步骤使用 // 例如，写入一个JSON文件 const summaryPath = path.join(process.cwd(), 'trace-urls.json'); fs.writeFileSync(summaryPath, JSON.stringify(urlMap, null, 2)); console.log(`Trace URL summary written to ${summaryPath}`); // 在GitHub Actions中，可以设置一个输出变量（多行文本） let urlOutput = ''; for (const [file, url] of Object.entries(urlMap)) { urlOutput += `${file}: ${url}\n`; } // 在GitHub Actions中，通过特定的输出语法设置 console.log(`::set-output name=trace_urls::${encodeURIComponent(urlOutput)}`); // 注意：新版本的GitHub Actions推荐使用环境文件，这里仅为示例。 } main().catch(console.error);

然后在GitHub Actions工作流中调用这个脚本，并将生成的链接以注释等形式添加到PR或工作流总结中：

- name: Upload traces to S3 and generate URLs if: failure() env: AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_REGION: 'us-east-1' AWS_S3_BUCKET: 'your-bucket-name' GITHUB_REPOSITORY: ${{ github.repository }} GITHUB_RUN_ID: ${{ github.run_id }} run: | node scripts/upload-and-generate-urls.js # 读取生成的URL文件 cat trace-urls.json - name: Comment on PR with trace links if: failure() && github.event_name == 'pull_request' uses: actions/github-script@v7 with: script: | const fs = require('fs'); let commentBody = '## 🐛 Playwright 测试失败\n\n以下测试用例执行失败，可下载Trace文件进行交互式调试：\n\n'; try { const urlData = JSON.parse(fs.readFileSync('trace-urls.json', 'utf8')); for (const [testName, url] of Object.entries(urlData)) { commentBody += `- **${testName}**: [下载Trace](${url})\n`; } } catch (e) { commentBody += '（未能生成Trace文件链接）\n'; } commentBody += `\n> Trace文件有效期为24小时。使用 \`npx playwright show-trace <文件路径>\` 查看。`; github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: commentBody });

5. 常见问题、排查技巧与优化建议

在实际集成过程中，你可能会遇到以下典型问题：

5.1 Trace文件太大，导致上传缓慢或存储成本高

• 问题：Trace文件默认包含截图、网络请求等，可能单个就达到几十MB。
• 排查与解决：
  1. 精简Trace内容：在playwright.config.ts中配置use.trace时，可以指定模式。‘trace’: ‘on-first-retry’比‘retain-on-failure’生成的文件更少。但这可能丢失信息。
  2. 使用screenshots和snapshots选项：在配置中限制截图和快照的详细程度。

     use: { trace: { mode: 'retain-on-failure', screenshots: true, // 设为 false 可禁用截图，但会损失重要信息 snapshots: true, // 设为 false 可禁用DOM快照，不推荐 } }

  3. 选择性录制：对于特别长的测试，可以考虑在代码中通过test.info().attach()或自定义编程式录制，只录制关键步骤或失败前的最后N步。Playwright API允许你手动开始和停止录制。
  4. 压缩与清理：在上传前，可以使用脚本检查并删除过大的、非关键的中间文件（尽管Playwright的.zip本身已是压缩格式）。定期清理云存储中的旧Trace文件。

5.2 CI环境中Trace Viewer无法直接打开

• 问题：在CI的制品页面下载Trace文件后，需要本地有Playwright环境才能用npx playwright show-trace查看。
• 解决：
  1. 推广标准流程：在团队文档中明确，查看Trace需要本地安装Playwright (npm i -D @playwright/test)。
  2. 使用在线查看器（实验性）：Playwright官方提供了一个在线的Trace查看器（ trace.playwright.dev ），你可以将.zip文件拖入其中查看。注意：这会将你的Trace文件上传到微软的服务器，请勿用于包含敏感数据的测试。可以在失败通知中附带此链接和说明。
  3. 集成到HTML报告：如前所述，确保HTML报告和Trace文件的相对路径正确，这样在下载完整的制品包后，打开HTML报告就能直接点击查看，无需手动命令。

5.3 测试通过，但CI步骤依然上传了空目录或残留文件

• 问题：流水线中if: failure()条件判断的是整个Job的状态。如果前面有步骤失败（如安装依赖失败），导致测试根本没运行，但test-results目录可能残留上次运行的文件，upload-artifact步骤仍会执行。
• 排查与解决：
  1. 更精确的条件判断：可以尝试在步骤中检查test-results目录下是否存在新的Trace文件，再决定是否上传。这需要更复杂的脚本。
  2. 使用needs和job.status：在GitHub Actions中，可以通过needs.<job_id>.result来判断特定作业的结果，进行更精细的控制。
  3. 每次清理：在流水线开始时，增加一个步骤清理旧的test-results和playwright-report目录，确保每次运行都是全新的。

5.4 并行测试下的Trace文件收集

• 问题：当使用shard进行并行测试时，每个shard会在独立的进程或机器上运行，生成各自的test-results目录。
• 解决：
  1. 统一收集点：为每个shard指定不同的输出子目录，例如test-results/shard-0,test-results/shard-1。在最后的收集步骤中，合并所有这些目录。
  2. 使用CI的依赖作业（Dependent Job）：在GitHub Actions中，可以设置一个单独的collect-and-upload作业，它needs: [test-shard-1, test-shard-2, ...]，并在该作业中下载所有shard产生的制品，合并后再统一上传。这需要将每个shard的test-results都作为中间制品上传。

5.5 性能影响评估

在CI中启用Trace录制（即使是retain-on-failure）会对测试执行时间有轻微影响，因为需要持续收集数据。根据我们的经验，这个开销通常在5%-15%之间，对于大多数项目是可以接受的。为了最小化影响：

• 仅在CI中启用：通过环境变量区分本地和CI环境，在CI中才配置trace: 'retain-on-failure'。

  // playwright.config.ts const traceMode = process.env.CI ? 'retain-on-failure' : 'off'; export default defineConfig({ use: { trace: traceMode, }, });

• 优化测试用例：保持测试的原子性和独立性，避免过长的端到端测试。长测试不仅Trace文件大，失败时排查范围也广。

将Playwright Trace Viewer与CI集成，看似是增加了一些配置复杂度，但它为团队带来的调试效率提升是巨大的。它把黑盒变成了白盒，把猜测变成了确证。当你下次再看到CI红点时，心中不再是焦虑，而是可以淡定地点开那个Trace链接，像侦探一样一步步还原案发现场。这套实践，无疑是现代高质量前端工程化体系中，值得投入的一个环节。