1. 项目概述从截图到“全息回放”的测试革命还在为自动化测试失败时只能看到一张冰冷的截图而抓狂吗截图就像犯罪现场的一张模糊照片你只知道“出事了”却完全不知道“事情是怎么一步步发展到这个地步的”。作为一线测试开发我经历过太多这样的时刻CI/CD流水线红灯亮起日志里只抛出一句“Element not found”然后附上一张元素早已消失的页面截图。排查问题就像在玩一个没有存档点的解谜游戏你得从头开始手动复现祈祷能撞上那个导致失败的幽灵条件。直到我把 Playwright 的视频录制和Trace Viewer这两个功能组合起来用整个调试体验发生了质变。这不再是简单的“事后截图”而是给每一次测试执行安装了一个“黑匣子”可以随时进行全息回放。今天要聊的就是如何花5分钟配置让你在测试失败时能像“事后诸葛亮”一样清晰地回溯测试执行的每一个动作、每一次网络请求、每一条控制台日志。这不仅仅是工具的使用更是一种测试理念的升级从结果验证转向过程洞察。这套组合拳适合所有正在使用或考虑使用 Playwright 进行 Web 自动化测试的工程师无论是前端测试、端到端E2E测试还是做爬虫时的行为模拟与调试。它能极大降低排查成本让“为什么失败”变得一目了然。2. 核心工具解析为什么是 Playwright 的视频与 Trace在深入配置之前我们得先搞清楚为什么是 Playwright 的这两个特性成为了绝配而不是用其他工具如 Selenium的截图或日志。这背后是对现代 Web 应用复杂性和调试需求深层次的理解。2.1 视频录制不止于“录屏”Playwright 的视频录制功能初看就是个录屏但它的实现机制和集成度决定了其不可替代性。核心原理与优势Playwright 为每个测试运行的浏览器上下文Browser Context启动一个视频编码器。它并非简单捕获屏幕像素而是与浏览器引擎深度集成以帧为单位高效录制。这意味着精准同步视频时间线与测试步骤精确对应你看到的每一次点击、输入都和测试代码的执行时刻严丝合缝。高性能低开销相比于传统桌面录屏软件它的开销极小。因为它录制的是浏览器的渲染输出而非整个桌面并且通常采用高效的编码器如libvpx在 CI 服务器这种无头环境下也能流畅运行。失败聚焦可以配置为“仅失败时保存”避免成功测试的视频占用大量存储空间。视频会自动以测试用例名命名与测试报告如 Allure关联后点击报告中的链接即可直接播放失败瞬间。注意视频录制会占用额外的 CPU 和内存在资源极度受限的 CI 环境中需权衡开启。但对于绝大多数现代 CI 环境如 GitHub Actions, GitLab CI这点开销是完全可以接受的其带来的调试收益远超成本。2.2 Trace Viewer超越日志的“时空胶囊”如果说视频让你看到了“发生了什么”那么 Trace 文件则让你能深入探究“为什么会发生”。Trace 是 Playwright 独有的王牌功能它是一个包含测试执行过程中大量上下文的 ZIP 文件。一个 Trace 文件里究竟有什么当你打开一个.zip格式的 Trace 文件通常通过playwright show-trace命令会启动一个本地的交互式查看器里面包含了以下维度的信息操作时间线精确到毫秒的测试步骤序列包括导航、点击、填充、断言等。完整的 DOM 快照在每一个操作步骤前后页面的完整 HTML 结构都被保存下来。你可以像在 Elements 面板中一样实时查看、搜索当时的 DOM 树。网络请求记录所有发出的 XHR/Fetch 请求、响应状态码、载荷Request/Response Payload、耗时。这对于调试因 API 接口返回数据异常导致的失败至关重要。控制台输出测试期间浏览器控制台打印的所有console.log、warn、error信息。执行截图在关键步骤自动捕获的截图作为视频的补充。Trace 与视频的关系 你可以把 Trace 理解为测试执行的“源代码”和“元数据”而视频是其“可视化渲染”。两者结合构成了一个立体的调试环境先用视频快速定位到失败的大致时间段和视觉表现再打开对应时间点的 Trace深入分析当时的网络请求、DOM 状态和日志找到根因。3. 五分钟极速配置实战理论说再多不如一行代码。下面我们以最常用的 Playwright for Python 和 Playwright for Node.js 为例展示如何快速配置。目标是测试失败时自动保存视频和 Trace 文件。3.1 基础环境与项目搭建首先确保你已经有一个 Playwright 项目。如果没有可以快速初始化# 对于 Node.js/TypeScript 项目 npm init playwrightlatest # 按照提示选择 TypeScript/JavaScript以及是否安装依赖。 # 对于 Python 项目 pip install pytest-playwright playwright install安装后项目结构里会有一个playwright.config.ts或.js、.py 的配置文件。我们的魔法就主要发生在这里。3.2 配置视频录制以 pytest-playwright 为例在playwright.config.py中我们主要配置use选项下的video参数。# playwright.config.py import os from playwright.sync_api import Playwright, expect def pytest_configure(config): # 可以设置一个环境变量来控制是否录制视频方便本地调试时关闭 os.environ[PWVIDEO] on def pytest_playwright_configure_video(device, video_mode): # 根据环境变量决定录制模式 if os.getenv(PWVIDEO) on: # ‘on-first-retry’ 仅在第一次重试时录制配合重试机制节省资源 # ‘retain-on-failure’ 仅保留失败测试的视频 # ‘on’ 始终录制并保留 return ‘retain-on-failure‘ return ‘off‘更常见且直接的方式是在pytest的fixture中配置# conftest.py import pytest from playwright.sync_api import Page pytest.fixture(scope“function”) def page(context): # 为每个测试函数提供一个 page 对象并配置视频 page context.new_page() # 开始录制视频保存路径为 test-results/videos/ page.video.start(path“test-results/videos/” pytest.current_test_name “.webm”) yield page # 测试结束后根据结果决定是否保存视频 if page.video: if request.node.rep_call.failed: # 如果测试失败 page.video.save_as() # 保存视频 else: page.video.delete() # 删除成功测试的视频对于 Node.js配置在playwright.config.ts中更为简洁// playwright.config.ts import { defineConfig, devices } from playwright/test; export default defineConfig({ use: { // 开启视频录制仅保留失败用例的视频 video: ‘retain-on-failure‘, // 视频保存路径 videoPath: ‘test-results/videos/’, }, // 全局配置测试结果输出目录 outputDir: ‘test-results/’, });3.3 配置 Trace 追踪以 Node.js 为例Trace 的配置同样在配置文件中完成通常我们希望在测试失败时自动捕获 Trace。// playwright.config.ts export default defineConfig({ use: { // ... 其他配置如 video, baseURL 等 }, // 全局的“项目”配置可以对不同浏览器分别设置 projects: [ { name: ‘chromium’, use: { ...devices[‘Desktop Chrome’] }, }, ], // 配置 reporter例如内置的 html 报告 reporter: [[‘html’, { outputFolder: ‘playwright-report’ }]], // 最重要的配置全局的钩子在测试失败时收集 Trace globalSetup: require.resolve(‘./global-setup’), globalTeardown: require.resolve(‘./global-teardown’), }); // 但是更推荐使用内置的 testInfo 附件功能在测试中按需添加 Trace // 下面是一个在 afterEach 钩子中根据测试状态保存 Trace 的示例 // 在某个 test.setup.ts 文件或配置的全局 hook 中 import { test as baseTest } from ‘playwright/test’; export const test baseTest.extend({ context: async ({ context }, use, testInfo) { // 在测试使用 context 前启动 Trace await context.tracing.start({ name: testInfo.title, screenshots: true, snapshots: true, // 必须为 true 才能保存 DOM 快照 sources: true, // 记录操作源 }); await use(context); // 测试使用完 context 后根据结果保存 Trace const tracePath testInfo.outputPath(‘trace.zip’); if (testInfo.status ‘failed’ || testInfo.status ‘timedOut’) { await context.tracing.stop({ path: tracePath }); // 将 trace 文件作为附件添加到测试报告中方便在 HTML 报告中直接点击查看 testInfo.attachments.push({ name: ‘trace’, contentType: ‘application/zip’, path: tracePath, }); } else { await context.tracing.stop(); // 不保存路径即丢弃 Trace 数据 } }, });关键参数解析snapshots: true这是获取 DOM 快照的关键必须开启。sources: true会记录是哪个测试文件、哪行代码触发了操作对于大型项目定位问题代码非常有帮助。testInfo.outputPath()这是一个非常实用的方法它会在配置的outputDir如test-results下为当前测试创建一个以测试标题命名的子目录用于存放该测试专属的 Trace、视频等文件避免了文件名冲突。3.4 整合配置与一键运行将以上视频和 Trace 配置整合后你的playwright.config.ts核心部分可能看起来像这样export default defineConfig({ timeout: 30 * 1000, // 每个测试的超时时间 retries: 1, // 失败重试次数配合 ‘video: ‘on-first-retry’’ 使用 outputDir: ‘./test-results’, // 所有输出物的家 fullyParallel: true, // 并行测试 forbidOnly: !!process.env.CI, // CI 环境中禁止使用 test.only reporter: [ [‘list’], // 控制台简洁输出 [‘html’, { open: ‘never’, outputFolder: ‘./playwright-report’ }], // HTML 报告 [‘junit’, { outputFile: ‘./test-results/junit.xml’ }], // 用于 CI 集成 ], use: { baseURL: ‘http://localhost:3000’, // 你的应用地址 trace: ‘retain-on-failure’, // 核心配置仅在失败时保留 Trace video: ‘retain-on-failure’, // 核心配置仅在失败时保留视频 screenshot: ‘only-on-failure’, // 顺便也配置一下失败截图 actionTimeout: 10 * 1000, navigationTimeout: 30 * 1000, }, projects: [ { name: ‘Chrome Stable’, use: { ...devices[‘Desktop Chrome’], channel: ‘chrome’ }, }, { name: ‘Mobile Safari’, use: { ...devices[‘iPhone 13’] }, }, ], webServer: { // 可选在运行测试前自动启动本地开发服务器 command: ‘npm run dev’, url: ‘http://localhost:3000’, reuseExistingServer: !process.env.CI, }, });配置完成后运行测试命令如npx playwright test或pytest当有测试失败时你会在test-results目录下找到对应的.webm视频文件和.zip的 Trace 文件。4. “事后诸葛亮”实战如何高效使用 Trace Viewer 和视频文件生成了怎么用才是关键。很多人只是打开视频看一眼或者粗略扫一下 Trace 时间线这远远没有发挥其威力。4.1 Trace Viewer 深度使用指南运行npx playwright show-trace path/to/trace.zip命令会启动一个本地服务器并在浏览器中打开交互界面。1. 时间线分析定位“案发”精确时刻打开 Trace 后最上方是时间线。上面标注了所有测试操作点击、输入、导航等。当测试失败时失败点如失败的断言会用一个红色的图标标记。你的第一件事就是点击这个红色标记查看器会自动定位到失败发生的那一刻。2. DOM 探查冻结案发现场定位到失败时刻后中间主面板会显示当时的页面截图。但更重要的是左侧的“Snapshot”面板。这里保存了那一刻的完整 DOM。搜索元素如果你在代码中定位#submit-button失败了可以立刻在 Snapshot 的搜索框里输入这个选择器看看这个元素在那一刻是否存在、其属性和样式是什么。可能你会发现它被一个弹窗遮住了z-index问题或者被设置了display: none。审查样式就像在 DevTools 里一样你可以查看任何元素的计算样式这对于排查 CSS 导致的布局错位、元素不可见等问题是杀手锏。3. 网络请求审查揪出数据元凶在失败时刻切换到“Network”标签页。这里列出了之前发生的所有网络请求。过滤与搜索如果失败与一个特定的 API 调用相关你可以通过 URL 关键词过滤。检查这个请求的状态码是 4xx/5xx 错误吗响应体返回的数据结构是否符合预期是不是返回了{“error”: “Invalid token”}导致前端逻辑出错请求头是否携带了正确的认证信息如 Cookie、Authorization时序关联结合时间线看是在哪个操作之后发起了这个请求请求的耗时是否异常这能帮你判断是前端操作触发错误还是后端响应缓慢或异常。4. 控制台日志捕捉运行时错误切换到“Console”标签页。这里汇集了console.log、未捕获的 JavaScript 异常、警告等信息。一个TypeError: Cannot read property ‘xxx’ of undefined的错误信息能直接把你引向问题的根源。4.2 视频与 Trace 的联动排查流程我个人的标准排查 SOP 如下第一眼看视频。快速播放失败测试的视频直观感受失败时的页面状态。是卡在加载是弹窗没出现还是数据列表为空这给我一个宏观的、直觉上的认知。第二眼开 Trace直奔失败点。在 Trace Viewer 中点击失败标记直接“传送”到失败发生的那一帧。第三眼查 DOM。在 Snapshot 中搜索测试代码试图操作的元素选择器。检查其是否存在、是否可见、属性是否正确。这一步能解决至少 50% 的“元素找不到”问题。第四眼看网络。如果 DOM 看起来正常但交互失败比如点击提交没反应立刻去 Network 面板查看相关的 XHR/Fetch 请求是否发出、是否成功、返回数据是否正确。第五眼扫控制台。如果前几步都没问题Console 面板里的 JavaScript 错误或警告往往是最后的关键线索。4.3 在 CI/CD 流水线中集成与查看本地好用在 CI如 GitHub Actions, GitLab CI, Jenkins上更重要因为那里是问题的高发区。1. 上传产物在 CI 脚本中测试运行完毕后无论成功与否都将test-results目录包含视频、Trace、截图和playwright-report目录HTML报告作为构建产物Artifacts上传。# GitHub Actions 示例片段 - name: Upload test results if: always() # 无论测试成功失败都上传 uses: actions/upload-artifactv4 with: name: playwright-results path: | test-results/ playwright-report/ retention-days: 7 # 保留7天2. 在 CI 界面直接查看HTML 报告GitHub Actions 等平台可以直接在浏览器中打开上传的 HTML 报告playwright-report/index.html。在报告中失败的测试用例旁边会有“视频”、“Trace”、“截图”的图标点击即可直接下载或预览部分平台支持内嵌预览。Trace 查看你需要下载.zip文件到本地然后用npx playwright show-trace命令查看。对于团队协作可以考虑将 Trace 文件上传到某个内部静态文件服务器并生成一个可直接点击的链接放在 CI 评论或通知里。3. 与通知系统集成可以在测试失败后通过 Slack、钉钉、企业微信等 Webhook发送通知消息并附上失败测试的 HTML 报告链接、以及关键截图可以从视频中截取一帧或使用失败截图。这样相关负责人能第一时间获取到最丰富的上下文信息。5. 高级技巧与避坑指南掌握了基本用法下面这些从实战中踩坑总结出来的技巧能让你玩得更溜避免常见陷阱。5.1 性能与存储优化策略开启视频和 Trace 后最直接的担忧就是磁盘空间和 CI 执行时间。策略一精准捕获按需保存trace: ‘retain-on-failure’和video: ‘retain-on-failure’是黄金配置确保只保留失败用例的“证据”。对于极其不稳定或核心流程的测试可以单独为其配置trace: ‘on’和video: ‘on’进行全程记录便于深度分析偶发问题。策略二控制 Trace 内容粒度await context.tracing.start({ snapshots: true, screenshots: true, sources: true, // 以下两个选项可以显著减小文件大小 _live: false, // 不建议在 CI 开启会增大开销 _overwrite: true, });实际上snapshotsDOM是占用空间的大头但也是最有价值的。如果磁盘空间真的非常紧张可以考虑只对最复杂的页面开启snapshots对于静态页面可以关闭。策略三定期清理与归档在 CI 脚本中设置构建产物的保留策略如只保留最近 10 次构建的产物。对于需要长期归档的 Trace如用于重现线上重大 bug可以手动下载并存储到专门的存储系统如 S3中并建立索引。策略四使用更高效的视频编解码器Playwright 默认的视频编码器通常是平衡了兼容性和效率的。如果你完全在 Linux CI 环境下运行可以尝试配置codec为libx264如果系统支持它可能比默认的libvpx有更好的压缩比。但需注意跨平台播放的兼容性。5.2 应对动态内容与 Flaky TestsFlaky Tests非确定性测试是自动化测试的噩梦。视频和 Trace 是诊断它的利器。场景一个测试有时成功有时失败失败时提示“元素不可交互”。排查收集多次失败时的 Trace 和视频。对比多次失败时间线观察失败前最后一个成功操作是什么。是不是每次都在点击同一个按钮前查看 Snapshot检查目标按钮的状态。是否有时是disabled状态是否有时被一个短暂出现的加载动画覆盖查看 Network检查在点击操作前是否有一个不稳定的 API 请求其响应时间波动很大导致前端状态更新时机不确定。解决方案根据 Trace 分析出的根因在测试代码中增加更稳健的等待策略。例如不要用固定的page.waitForTimeout(5000)而是改用 Playwright 提供的智能等待# 不好的做法 await page.wait_for_timeout(2000) await page.click(‘button#submit’) # 好的做法等待元素达到可交互状态 await page.locator(‘button#submit’).wait_for(state‘attached’) await page.locator(‘button#submit’).wait_for(state‘visible’) # 或者更直接地click 方法本身会进行可交互性检查 await page.locator(‘button#submit’).click() # 如果是因为网络请求可以等待请求完成 async with page.expect_response(‘**/api/submit’) as response_info: await page.locator(‘button#submit’).click() response await response_info.value5.3 与 Allure 等高级报告框架集成Playwright 内置的 HTML 报告已经很好用但如果你团队已经在使用 Allure 作为统一的测试报告平台也可以无缝集成。Node.js使用allure-playwright包。Python使用pytest-allure和allure-python。集成后你可以在 Allure 报告的测试用例详情页看到 “Attachments” 部分里面会包含 Playwright 自动附加的视频、Trace 和截图。点击即可在 Allure 界面内直接播放视频或下载 Trace 文件实现了所有测试证据在一个平台上的集中管理和展示。一个常见的坑确保你的 Allure 结果目录通常是allure-results和 Playwright 的输出目录test-results配置正确并且附件文件的路径是相对路径以便 Allure 能正确找到并链接它们。5.4 排查经典问题案例实录案例一元素点击失败截图显示元素存在现象Element is not visible错误。Trace 排查打开 Trace定位到点击操作。查看 Snapshot搜索该元素发现其style包含pointer-events: none或opacity: 0。查看时间线发现点击前有一个元素状态变更操作。根因前端组件的交互状态如禁用、只读是通过 CSS 控制的而非disabled属性。测试代码只检查了disabled属性没检查样式。解决在点击前增加对元素可交互性的自定义断言或使用page.locator(‘…’).is_enabled()方法该方法会检查多种可交互状态。案例二列表数据为空但手动操作正常现象测试断言列表第一项文本为“某值”但实际为空。Trace 排查看视频发现页面加载后列表区域空白了一段时间才出现数据。打开 Trace定位到断言失败的时刻。查看 Network 面板过滤列表数据的 API 请求。发现该请求确实返回了数据。查看 Console 面板发现一条错误Uncaught TypeError: data.map is not a function。根因后端 API 在某种边界条件下如空数据返回的数据结构从数组变成了对象前端渲染逻辑没有处理这种异常情况导致渲染失败。解决修复前端代码的健壮性同时测试代码可以增加对 API 响应数据结构的断言提前发现问题。案例三测试在 CI 上偶发超时本地从不出错现象Timeout 30000ms exceeded。Trace 排查收集 CI 上失败的 Trace因为超时也属于失败会被保留。查看时间线的最后部分看测试卡在了哪个操作上通常是某个wait_for_selector或导航。查看 Network 面板看是否有某个关键资源如 JS、CSS、API加载极其缓慢或失败。对比本地成功运行的 Trace 网络时间。根因CI 环境网络到某个第三方 CDN 的资源加载不稳定或者测试环境的后端服务在 CI 运行期间性能波动大。解决增加全局超时时间对特定慢操作单独设置更长的超时或者使用page.route来 mock 掉不稳定的第三方请求保证测试的稳定性。从这些案例可以看出视频提供了“现象”而 Trace 提供了深究“根因”所需的一切上下文。两者结合使得调试从一种“猜测艺术”变成了一种“侦查科学”。这套组合拳打下来团队里关于“测试又挂了谁来看看”的扯皮时间至少减少了 80%因为证据链就摆在那里清晰无误。
Playwright视频录制与Trace Viewer：5分钟配置实现自动化测试全息调试
1. 项目概述从截图到“全息回放”的测试革命还在为自动化测试失败时只能看到一张冰冷的截图而抓狂吗截图就像犯罪现场的一张模糊照片你只知道“出事了”却完全不知道“事情是怎么一步步发展到这个地步的”。作为一线测试开发我经历过太多这样的时刻CI/CD流水线红灯亮起日志里只抛出一句“Element not found”然后附上一张元素早已消失的页面截图。排查问题就像在玩一个没有存档点的解谜游戏你得从头开始手动复现祈祷能撞上那个导致失败的幽灵条件。直到我把 Playwright 的视频录制和Trace Viewer这两个功能组合起来用整个调试体验发生了质变。这不再是简单的“事后截图”而是给每一次测试执行安装了一个“黑匣子”可以随时进行全息回放。今天要聊的就是如何花5分钟配置让你在测试失败时能像“事后诸葛亮”一样清晰地回溯测试执行的每一个动作、每一次网络请求、每一条控制台日志。这不仅仅是工具的使用更是一种测试理念的升级从结果验证转向过程洞察。这套组合拳适合所有正在使用或考虑使用 Playwright 进行 Web 自动化测试的工程师无论是前端测试、端到端E2E测试还是做爬虫时的行为模拟与调试。它能极大降低排查成本让“为什么失败”变得一目了然。2. 核心工具解析为什么是 Playwright 的视频与 Trace在深入配置之前我们得先搞清楚为什么是 Playwright 的这两个特性成为了绝配而不是用其他工具如 Selenium的截图或日志。这背后是对现代 Web 应用复杂性和调试需求深层次的理解。2.1 视频录制不止于“录屏”Playwright 的视频录制功能初看就是个录屏但它的实现机制和集成度决定了其不可替代性。核心原理与优势Playwright 为每个测试运行的浏览器上下文Browser Context启动一个视频编码器。它并非简单捕获屏幕像素而是与浏览器引擎深度集成以帧为单位高效录制。这意味着精准同步视频时间线与测试步骤精确对应你看到的每一次点击、输入都和测试代码的执行时刻严丝合缝。高性能低开销相比于传统桌面录屏软件它的开销极小。因为它录制的是浏览器的渲染输出而非整个桌面并且通常采用高效的编码器如libvpx在 CI 服务器这种无头环境下也能流畅运行。失败聚焦可以配置为“仅失败时保存”避免成功测试的视频占用大量存储空间。视频会自动以测试用例名命名与测试报告如 Allure关联后点击报告中的链接即可直接播放失败瞬间。注意视频录制会占用额外的 CPU 和内存在资源极度受限的 CI 环境中需权衡开启。但对于绝大多数现代 CI 环境如 GitHub Actions, GitLab CI这点开销是完全可以接受的其带来的调试收益远超成本。2.2 Trace Viewer超越日志的“时空胶囊”如果说视频让你看到了“发生了什么”那么 Trace 文件则让你能深入探究“为什么会发生”。Trace 是 Playwright 独有的王牌功能它是一个包含测试执行过程中大量上下文的 ZIP 文件。一个 Trace 文件里究竟有什么当你打开一个.zip格式的 Trace 文件通常通过playwright show-trace命令会启动一个本地的交互式查看器里面包含了以下维度的信息操作时间线精确到毫秒的测试步骤序列包括导航、点击、填充、断言等。完整的 DOM 快照在每一个操作步骤前后页面的完整 HTML 结构都被保存下来。你可以像在 Elements 面板中一样实时查看、搜索当时的 DOM 树。网络请求记录所有发出的 XHR/Fetch 请求、响应状态码、载荷Request/Response Payload、耗时。这对于调试因 API 接口返回数据异常导致的失败至关重要。控制台输出测试期间浏览器控制台打印的所有console.log、warn、error信息。执行截图在关键步骤自动捕获的截图作为视频的补充。Trace 与视频的关系 你可以把 Trace 理解为测试执行的“源代码”和“元数据”而视频是其“可视化渲染”。两者结合构成了一个立体的调试环境先用视频快速定位到失败的大致时间段和视觉表现再打开对应时间点的 Trace深入分析当时的网络请求、DOM 状态和日志找到根因。3. 五分钟极速配置实战理论说再多不如一行代码。下面我们以最常用的 Playwright for Python 和 Playwright for Node.js 为例展示如何快速配置。目标是测试失败时自动保存视频和 Trace 文件。3.1 基础环境与项目搭建首先确保你已经有一个 Playwright 项目。如果没有可以快速初始化# 对于 Node.js/TypeScript 项目 npm init playwrightlatest # 按照提示选择 TypeScript/JavaScript以及是否安装依赖。 # 对于 Python 项目 pip install pytest-playwright playwright install安装后项目结构里会有一个playwright.config.ts或.js、.py 的配置文件。我们的魔法就主要发生在这里。3.2 配置视频录制以 pytest-playwright 为例在playwright.config.py中我们主要配置use选项下的video参数。# playwright.config.py import os from playwright.sync_api import Playwright, expect def pytest_configure(config): # 可以设置一个环境变量来控制是否录制视频方便本地调试时关闭 os.environ[PWVIDEO] on def pytest_playwright_configure_video(device, video_mode): # 根据环境变量决定录制模式 if os.getenv(PWVIDEO) on: # ‘on-first-retry’ 仅在第一次重试时录制配合重试机制节省资源 # ‘retain-on-failure’ 仅保留失败测试的视频 # ‘on’ 始终录制并保留 return ‘retain-on-failure‘ return ‘off‘更常见且直接的方式是在pytest的fixture中配置# conftest.py import pytest from playwright.sync_api import Page pytest.fixture(scope“function”) def page(context): # 为每个测试函数提供一个 page 对象并配置视频 page context.new_page() # 开始录制视频保存路径为 test-results/videos/ page.video.start(path“test-results/videos/” pytest.current_test_name “.webm”) yield page # 测试结束后根据结果决定是否保存视频 if page.video: if request.node.rep_call.failed: # 如果测试失败 page.video.save_as() # 保存视频 else: page.video.delete() # 删除成功测试的视频对于 Node.js配置在playwright.config.ts中更为简洁// playwright.config.ts import { defineConfig, devices } from playwright/test; export default defineConfig({ use: { // 开启视频录制仅保留失败用例的视频 video: ‘retain-on-failure‘, // 视频保存路径 videoPath: ‘test-results/videos/’, }, // 全局配置测试结果输出目录 outputDir: ‘test-results/’, });3.3 配置 Trace 追踪以 Node.js 为例Trace 的配置同样在配置文件中完成通常我们希望在测试失败时自动捕获 Trace。// playwright.config.ts export default defineConfig({ use: { // ... 其他配置如 video, baseURL 等 }, // 全局的“项目”配置可以对不同浏览器分别设置 projects: [ { name: ‘chromium’, use: { ...devices[‘Desktop Chrome’] }, }, ], // 配置 reporter例如内置的 html 报告 reporter: [[‘html’, { outputFolder: ‘playwright-report’ }]], // 最重要的配置全局的钩子在测试失败时收集 Trace globalSetup: require.resolve(‘./global-setup’), globalTeardown: require.resolve(‘./global-teardown’), }); // 但是更推荐使用内置的 testInfo 附件功能在测试中按需添加 Trace // 下面是一个在 afterEach 钩子中根据测试状态保存 Trace 的示例 // 在某个 test.setup.ts 文件或配置的全局 hook 中 import { test as baseTest } from ‘playwright/test’; export const test baseTest.extend({ context: async ({ context }, use, testInfo) { // 在测试使用 context 前启动 Trace await context.tracing.start({ name: testInfo.title, screenshots: true, snapshots: true, // 必须为 true 才能保存 DOM 快照 sources: true, // 记录操作源 }); await use(context); // 测试使用完 context 后根据结果保存 Trace const tracePath testInfo.outputPath(‘trace.zip’); if (testInfo.status ‘failed’ || testInfo.status ‘timedOut’) { await context.tracing.stop({ path: tracePath }); // 将 trace 文件作为附件添加到测试报告中方便在 HTML 报告中直接点击查看 testInfo.attachments.push({ name: ‘trace’, contentType: ‘application/zip’, path: tracePath, }); } else { await context.tracing.stop(); // 不保存路径即丢弃 Trace 数据 } }, });关键参数解析snapshots: true这是获取 DOM 快照的关键必须开启。sources: true会记录是哪个测试文件、哪行代码触发了操作对于大型项目定位问题代码非常有帮助。testInfo.outputPath()这是一个非常实用的方法它会在配置的outputDir如test-results下为当前测试创建一个以测试标题命名的子目录用于存放该测试专属的 Trace、视频等文件避免了文件名冲突。3.4 整合配置与一键运行将以上视频和 Trace 配置整合后你的playwright.config.ts核心部分可能看起来像这样export default defineConfig({ timeout: 30 * 1000, // 每个测试的超时时间 retries: 1, // 失败重试次数配合 ‘video: ‘on-first-retry’’ 使用 outputDir: ‘./test-results’, // 所有输出物的家 fullyParallel: true, // 并行测试 forbidOnly: !!process.env.CI, // CI 环境中禁止使用 test.only reporter: [ [‘list’], // 控制台简洁输出 [‘html’, { open: ‘never’, outputFolder: ‘./playwright-report’ }], // HTML 报告 [‘junit’, { outputFile: ‘./test-results/junit.xml’ }], // 用于 CI 集成 ], use: { baseURL: ‘http://localhost:3000’, // 你的应用地址 trace: ‘retain-on-failure’, // 核心配置仅在失败时保留 Trace video: ‘retain-on-failure’, // 核心配置仅在失败时保留视频 screenshot: ‘only-on-failure’, // 顺便也配置一下失败截图 actionTimeout: 10 * 1000, navigationTimeout: 30 * 1000, }, projects: [ { name: ‘Chrome Stable’, use: { ...devices[‘Desktop Chrome’], channel: ‘chrome’ }, }, { name: ‘Mobile Safari’, use: { ...devices[‘iPhone 13’] }, }, ], webServer: { // 可选在运行测试前自动启动本地开发服务器 command: ‘npm run dev’, url: ‘http://localhost:3000’, reuseExistingServer: !process.env.CI, }, });配置完成后运行测试命令如npx playwright test或pytest当有测试失败时你会在test-results目录下找到对应的.webm视频文件和.zip的 Trace 文件。4. “事后诸葛亮”实战如何高效使用 Trace Viewer 和视频文件生成了怎么用才是关键。很多人只是打开视频看一眼或者粗略扫一下 Trace 时间线这远远没有发挥其威力。4.1 Trace Viewer 深度使用指南运行npx playwright show-trace path/to/trace.zip命令会启动一个本地服务器并在浏览器中打开交互界面。1. 时间线分析定位“案发”精确时刻打开 Trace 后最上方是时间线。上面标注了所有测试操作点击、输入、导航等。当测试失败时失败点如失败的断言会用一个红色的图标标记。你的第一件事就是点击这个红色标记查看器会自动定位到失败发生的那一刻。2. DOM 探查冻结案发现场定位到失败时刻后中间主面板会显示当时的页面截图。但更重要的是左侧的“Snapshot”面板。这里保存了那一刻的完整 DOM。搜索元素如果你在代码中定位#submit-button失败了可以立刻在 Snapshot 的搜索框里输入这个选择器看看这个元素在那一刻是否存在、其属性和样式是什么。可能你会发现它被一个弹窗遮住了z-index问题或者被设置了display: none。审查样式就像在 DevTools 里一样你可以查看任何元素的计算样式这对于排查 CSS 导致的布局错位、元素不可见等问题是杀手锏。3. 网络请求审查揪出数据元凶在失败时刻切换到“Network”标签页。这里列出了之前发生的所有网络请求。过滤与搜索如果失败与一个特定的 API 调用相关你可以通过 URL 关键词过滤。检查这个请求的状态码是 4xx/5xx 错误吗响应体返回的数据结构是否符合预期是不是返回了{“error”: “Invalid token”}导致前端逻辑出错请求头是否携带了正确的认证信息如 Cookie、Authorization时序关联结合时间线看是在哪个操作之后发起了这个请求请求的耗时是否异常这能帮你判断是前端操作触发错误还是后端响应缓慢或异常。4. 控制台日志捕捉运行时错误切换到“Console”标签页。这里汇集了console.log、未捕获的 JavaScript 异常、警告等信息。一个TypeError: Cannot read property ‘xxx’ of undefined的错误信息能直接把你引向问题的根源。4.2 视频与 Trace 的联动排查流程我个人的标准排查 SOP 如下第一眼看视频。快速播放失败测试的视频直观感受失败时的页面状态。是卡在加载是弹窗没出现还是数据列表为空这给我一个宏观的、直觉上的认知。第二眼开 Trace直奔失败点。在 Trace Viewer 中点击失败标记直接“传送”到失败发生的那一帧。第三眼查 DOM。在 Snapshot 中搜索测试代码试图操作的元素选择器。检查其是否存在、是否可见、属性是否正确。这一步能解决至少 50% 的“元素找不到”问题。第四眼看网络。如果 DOM 看起来正常但交互失败比如点击提交没反应立刻去 Network 面板查看相关的 XHR/Fetch 请求是否发出、是否成功、返回数据是否正确。第五眼扫控制台。如果前几步都没问题Console 面板里的 JavaScript 错误或警告往往是最后的关键线索。4.3 在 CI/CD 流水线中集成与查看本地好用在 CI如 GitHub Actions, GitLab CI, Jenkins上更重要因为那里是问题的高发区。1. 上传产物在 CI 脚本中测试运行完毕后无论成功与否都将test-results目录包含视频、Trace、截图和playwright-report目录HTML报告作为构建产物Artifacts上传。# GitHub Actions 示例片段 - name: Upload test results if: always() # 无论测试成功失败都上传 uses: actions/upload-artifactv4 with: name: playwright-results path: | test-results/ playwright-report/ retention-days: 7 # 保留7天2. 在 CI 界面直接查看HTML 报告GitHub Actions 等平台可以直接在浏览器中打开上传的 HTML 报告playwright-report/index.html。在报告中失败的测试用例旁边会有“视频”、“Trace”、“截图”的图标点击即可直接下载或预览部分平台支持内嵌预览。Trace 查看你需要下载.zip文件到本地然后用npx playwright show-trace命令查看。对于团队协作可以考虑将 Trace 文件上传到某个内部静态文件服务器并生成一个可直接点击的链接放在 CI 评论或通知里。3. 与通知系统集成可以在测试失败后通过 Slack、钉钉、企业微信等 Webhook发送通知消息并附上失败测试的 HTML 报告链接、以及关键截图可以从视频中截取一帧或使用失败截图。这样相关负责人能第一时间获取到最丰富的上下文信息。5. 高级技巧与避坑指南掌握了基本用法下面这些从实战中踩坑总结出来的技巧能让你玩得更溜避免常见陷阱。5.1 性能与存储优化策略开启视频和 Trace 后最直接的担忧就是磁盘空间和 CI 执行时间。策略一精准捕获按需保存trace: ‘retain-on-failure’和video: ‘retain-on-failure’是黄金配置确保只保留失败用例的“证据”。对于极其不稳定或核心流程的测试可以单独为其配置trace: ‘on’和video: ‘on’进行全程记录便于深度分析偶发问题。策略二控制 Trace 内容粒度await context.tracing.start({ snapshots: true, screenshots: true, sources: true, // 以下两个选项可以显著减小文件大小 _live: false, // 不建议在 CI 开启会增大开销 _overwrite: true, });实际上snapshotsDOM是占用空间的大头但也是最有价值的。如果磁盘空间真的非常紧张可以考虑只对最复杂的页面开启snapshots对于静态页面可以关闭。策略三定期清理与归档在 CI 脚本中设置构建产物的保留策略如只保留最近 10 次构建的产物。对于需要长期归档的 Trace如用于重现线上重大 bug可以手动下载并存储到专门的存储系统如 S3中并建立索引。策略四使用更高效的视频编解码器Playwright 默认的视频编码器通常是平衡了兼容性和效率的。如果你完全在 Linux CI 环境下运行可以尝试配置codec为libx264如果系统支持它可能比默认的libvpx有更好的压缩比。但需注意跨平台播放的兼容性。5.2 应对动态内容与 Flaky TestsFlaky Tests非确定性测试是自动化测试的噩梦。视频和 Trace 是诊断它的利器。场景一个测试有时成功有时失败失败时提示“元素不可交互”。排查收集多次失败时的 Trace 和视频。对比多次失败时间线观察失败前最后一个成功操作是什么。是不是每次都在点击同一个按钮前查看 Snapshot检查目标按钮的状态。是否有时是disabled状态是否有时被一个短暂出现的加载动画覆盖查看 Network检查在点击操作前是否有一个不稳定的 API 请求其响应时间波动很大导致前端状态更新时机不确定。解决方案根据 Trace 分析出的根因在测试代码中增加更稳健的等待策略。例如不要用固定的page.waitForTimeout(5000)而是改用 Playwright 提供的智能等待# 不好的做法 await page.wait_for_timeout(2000) await page.click(‘button#submit’) # 好的做法等待元素达到可交互状态 await page.locator(‘button#submit’).wait_for(state‘attached’) await page.locator(‘button#submit’).wait_for(state‘visible’) # 或者更直接地click 方法本身会进行可交互性检查 await page.locator(‘button#submit’).click() # 如果是因为网络请求可以等待请求完成 async with page.expect_response(‘**/api/submit’) as response_info: await page.locator(‘button#submit’).click() response await response_info.value5.3 与 Allure 等高级报告框架集成Playwright 内置的 HTML 报告已经很好用但如果你团队已经在使用 Allure 作为统一的测试报告平台也可以无缝集成。Node.js使用allure-playwright包。Python使用pytest-allure和allure-python。集成后你可以在 Allure 报告的测试用例详情页看到 “Attachments” 部分里面会包含 Playwright 自动附加的视频、Trace 和截图。点击即可在 Allure 界面内直接播放视频或下载 Trace 文件实现了所有测试证据在一个平台上的集中管理和展示。一个常见的坑确保你的 Allure 结果目录通常是allure-results和 Playwright 的输出目录test-results配置正确并且附件文件的路径是相对路径以便 Allure 能正确找到并链接它们。5.4 排查经典问题案例实录案例一元素点击失败截图显示元素存在现象Element is not visible错误。Trace 排查打开 Trace定位到点击操作。查看 Snapshot搜索该元素发现其style包含pointer-events: none或opacity: 0。查看时间线发现点击前有一个元素状态变更操作。根因前端组件的交互状态如禁用、只读是通过 CSS 控制的而非disabled属性。测试代码只检查了disabled属性没检查样式。解决在点击前增加对元素可交互性的自定义断言或使用page.locator(‘…’).is_enabled()方法该方法会检查多种可交互状态。案例二列表数据为空但手动操作正常现象测试断言列表第一项文本为“某值”但实际为空。Trace 排查看视频发现页面加载后列表区域空白了一段时间才出现数据。打开 Trace定位到断言失败的时刻。查看 Network 面板过滤列表数据的 API 请求。发现该请求确实返回了数据。查看 Console 面板发现一条错误Uncaught TypeError: data.map is not a function。根因后端 API 在某种边界条件下如空数据返回的数据结构从数组变成了对象前端渲染逻辑没有处理这种异常情况导致渲染失败。解决修复前端代码的健壮性同时测试代码可以增加对 API 响应数据结构的断言提前发现问题。案例三测试在 CI 上偶发超时本地从不出错现象Timeout 30000ms exceeded。Trace 排查收集 CI 上失败的 Trace因为超时也属于失败会被保留。查看时间线的最后部分看测试卡在了哪个操作上通常是某个wait_for_selector或导航。查看 Network 面板看是否有某个关键资源如 JS、CSS、API加载极其缓慢或失败。对比本地成功运行的 Trace 网络时间。根因CI 环境网络到某个第三方 CDN 的资源加载不稳定或者测试环境的后端服务在 CI 运行期间性能波动大。解决增加全局超时时间对特定慢操作单独设置更长的超时或者使用page.route来 mock 掉不稳定的第三方请求保证测试的稳定性。从这些案例可以看出视频提供了“现象”而 Trace 提供了深究“根因”所需的一切上下文。两者结合使得调试从一种“猜测艺术”变成了一种“侦查科学”。这套组合拳打下来团队里关于“测试又挂了谁来看看”的扯皮时间至少减少了 80%因为证据链就摆在那里清晰无误。
