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 核心组件与工作流整个方案围绕以下几个核心组件构建Playwright Test Runner 执行测试的主体负责在测试失败时触发Trace录制。CI Runner/Agent 执行CI流水线的环境如GitHub Actions的ubuntu-latestrunner或Jenkins的agent节点。对象存储或文件服务器 用于存储生成的.zip格式的Trace文件。这是关键因为CI Runner通常是临时的测试结束后文件会丢失。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等对象存储并生成一个带有短暂过期时间的预签名URLPresigned URL然后将这个URL以某种形式如注释到PR或写入自定义的测试报告展示出来。这样做的好处是存储独立 不占用CI系统本身的存储配额。访问控制灵活 可以通过URL控制访问权限和有效期。易于集成 生成的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/checkoutv4 - uses: actions/setup-nodev4 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-artifactv4 with: name: playwright-html-report path: playwright-report/ retention-days: 7 - name: Upload Trace files for failed tests if: failure() # 只有测试失败时才执行此步骤 uses: actions/upload-artifactv4 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.jsconst 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-artifactv4 with: name: playwright-traces-failed path: failed-traces/ # 上传我们精准收集的目录 retention-days: 14注意事项Trace文件命名与冲突上述脚本的简单重命名${project}-${testDir}在测试名包含特殊字符或路径较长时可能有问题。更健壮的做法是使用测试的testId或对测试名进行安全编码如slugify。此外如果同一个测试文件中的多个测试用例失败它们的目录名可能相同Playwright会添加后缀直接复制可能导致覆盖。在实际应用中可以考虑使用更稳定的唯一标识符或者直接上传整个结构清晰的子目录。3.3 集成HTML报告并关联TracePlaywright 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-artifactv4 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-credentialsv4 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_PATHs3://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_PATH4.2 生成预签名URL并通知直接公开S3桶不安全。更好的做法是生成一个预签名URL该URL在有限时间内如24小时有效。这需要一点额外的脚本逻辑。创建一个脚本scripts/upload-and-generate-urls.js使用AWS SDK for JavaScriptconst { 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 nametrace_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-scriptv7 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。排查与解决精简Trace内容在playwright.config.ts中配置use.trace时可以指定模式。‘trace’: ‘on-first-retry’比‘retain-on-failure’生成的文件更少。但这可能丢失信息。使用screenshots和snapshots选项在配置中限制截图和快照的详细程度。use: { trace: { mode: retain-on-failure, screenshots: true, // 设为 false 可禁用截图但会损失重要信息 snapshots: true, // 设为 false 可禁用DOM快照不推荐 } }选择性录制对于特别长的测试可以考虑在代码中通过test.info().attach()或自定义编程式录制只录制关键步骤或失败前的最后N步。Playwright API允许你手动开始和停止录制。压缩与清理在上传前可以使用脚本检查并删除过大的、非关键的中间文件尽管Playwright的.zip本身已是压缩格式。定期清理云存储中的旧Trace文件。5.2 CI环境中Trace Viewer无法直接打开问题在CI的制品页面下载Trace文件后需要本地有Playwright环境才能用npx playwright show-trace查看。解决推广标准流程在团队文档中明确查看Trace需要本地安装Playwright (npm i -D playwright/test)。使用在线查看器实验性Playwright官方提供了一个在线的Trace查看器 trace.playwright.dev 你可以将.zip文件拖入其中查看。注意这会将你的Trace文件上传到微软的服务器请勿用于包含敏感数据的测试。可以在失败通知中附带此链接和说明。集成到HTML报告如前所述确保HTML报告和Trace文件的相对路径正确这样在下载完整的制品包后打开HTML报告就能直接点击查看无需手动命令。5.3 测试通过但CI步骤依然上传了空目录或残留文件问题流水线中if: failure()条件判断的是整个Job的状态。如果前面有步骤失败如安装依赖失败导致测试根本没运行但test-results目录可能残留上次运行的文件upload-artifact步骤仍会执行。排查与解决更精确的条件判断可以尝试在步骤中检查test-results目录下是否存在新的Trace文件再决定是否上传。这需要更复杂的脚本。使用needs和job.status在GitHub Actions中可以通过needs.job_id.result来判断特定作业的结果进行更精细的控制。每次清理在流水线开始时增加一个步骤清理旧的test-results和playwright-report目录确保每次运行都是全新的。5.4 并行测试下的Trace文件收集问题当使用shard进行并行测试时每个shard会在独立的进程或机器上运行生成各自的test-results目录。解决统一收集点为每个shard指定不同的输出子目录例如test-results/shard-0,test-results/shard-1。在最后的收集步骤中合并所有这些目录。使用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链接像侦探一样一步步还原案发现场。这套实践无疑是现代高质量前端工程化体系中值得投入的一个环节。