一文详解Playwright截图和视频录制功能的常用场景与企业项目实战

一句话结论：Playwright 的截图适合“固定证据”，视频适合“还原动作”，Trace 适合“定位根因”。企业项目不要把所有用例都录成视频，而应该采用“失败截图 + 首次重试视频 + 首次重试 Trace + HTML 报告”的分层策略。

本文基于 Playwright 官方文档、官方发布说明以及 Selenium、Cypress 官方资料整理，检索时间为 2026 年 9 月 8 日。示例优先使用 Python，涉及 Playwright Test 专属配置时会明确使用 TypeScript。

一、先说痛点：自动化测试失败了，为什么还要人工“猜”

在企业项目里，最让测试、开发和运维头疼的不是“测试失败”，而是失败后没有足够证据。

例如，支付回归任务凌晨在 CI 中失败。日志只显示 Timeout 30000ms exceeded，开发第二天在本地重跑却通过了。此时团队通常会遇到四个问题：页面当时显示了什么，用户实际点击了哪个元素，接口返回了什么，失败发生在第一次执行还是重试阶段。

如果只保存一段文本日志，团队往往只能靠猜。截图能够回答“当时页面长什么样”，视频能够回答“用户做了哪些动作”，Trace 则能够进一步展示动作前后 DOM 快照、网络请求、控制台和源代码位置。[1] [4]

1.1 痛点一：失败画面没有留下来

弹窗遮挡、样式错位、按钮变灰、接口错误提示等问题，单靠日志很难表达。截图适合保留失败瞬间的视觉状态，也适合做视觉回归基线。

1.2 痛点二：偶发问题无法复盘

竞态条件、慢接口、动画未结束、浏览器差异等问题，通常不是每次都出现。视频能够把点击、输入、跳转和等待过程串起来，比一张静态图更容易复盘。

1.3 痛点三：录了视频仍然不知道根因

视频只能说明“发生了什么”，不一定能说明“为什么发生”。例如按钮看起来存在，但定位 器实际匹配了多个节点；接口返回 500，但页面仍然显示旧数据。Trace Viewer 可以沿时间轴查看动作、DOM 快照、网络请求、控制台、错误和附件，因此它通常更适合 CI 失败诊断。[4]

1.4 解决方案：把测试工件分成三层

企业项目的关键不是“能不能录”，而是在证据价值、运行性能、存储成本和敏感数据之间取得平衡。

二、Playwright 是什么，为什么截图和录制功能值得使用

Playwright 是一个面向现代 Web 应用的浏览器自动化与端到端测试框架。它通过统一 API 驱动 Chromium、Firefox 和 WebKit，并提供定位 器、自动等待、断言、网络控制、截图、视频和 Trace 等能力。[2] [3]

这里可以把一次测试理解成一场“带摄像机的验收”：

• Page 是浏览器中的一个页面。
• BrowserContext 是一个隔离的浏览器会话，类似一个独立的隐身窗口。
• Screenshot 是某个时刻的照片。
• Video 是整个会话的录像。
• Trace 是带时间轴、DOM、网络和日志的黑匣子。

Playwright 的价值并不只是“截图 API 更简单”。它把证据采集和测试运行生命周期结合起来：定位 器支持自动等待，Web-first assertions 会等待页面达到预期状态，失败时可以配合截图、视频和 Trace 形成可追溯的报告。[3]

2.1 它解决的核心问题

第一，它减少了手工等待导致的脆弱性。官方最佳实践建议优先使用面向用户的定位方式，例如角色、名称、标签和显式测试标识，而不是依赖容易变化的 CSS 层级或 XPath。[3]

第二，它能够覆盖多个浏览器项目。企业前端需要关注 Chromium、Firefox 和 WebKit 的差异，Playwright 可以在配置中声明多个项目并行执行。[3]

第三，它把“失败现场”变成可分发的工件。HTML 报告、截图、视频和 Trace 可以上传到 CI 的工件存储，开发人员不必先在本地复现问题。

三、它是怎么演进过来的

Playwright 最初由 Microsoft 团队推动，目标是为现代浏览器自动化提供更直接、更可靠的控制能力。它的发展大致可以分为四个阶段：

官方发布说明显示，Playwright 会持续跟进支持的浏览器版本，并不断扩展 Trace、报告和测试运行器能力。[2] 因此，企业使用时不要只看某一篇旧教程，而应该把当前版本的官方文档和发布说明作为配置依据。

四、环境安装：先跑通第一个截图

4.1 安装 Python 包和浏览器

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install playwright pytest
playwright install chromium

如果企业 CI 同时验证 Firefox 和 WebKit，可以安装全部浏览器：

playwright install

4.2 第一个可运行截图示例

from pathlib import Path
from playwright.sync_api import sync_playwright


OUTPUT_DIR = Path("artifacts")
OUTPUT_DIR.mkdir(exist_ok=True)


with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page(viewport={"width": 1440, "height": 900})
    page.goto("https://playwright.dev/", wait_until="networkidle")

    page.screenshot(
        path=str(OUTPUT_DIR / "playwright-home.png"),
        full_page=True,
    )

    browser.close()

官方截图 API 支持普通截图、全页截图、元素截图、裁剪区域、图片格式和缓冲区输出。[1] 初学者建议先掌握 page.screenshot()，再学习 locator.screenshot() 和视觉断言。

五、截图功能详解：四个最常用场景

5.1 场景一：失败时自动截图

在测试中，截图应当紧贴“可诊断节点”采集。不要在每一行代码后都截图，否则报告会膨胀，真正重要的证据反而难以查找。

from pathlib import Path
from playwright.sync_api import Page


def save_failure_screenshot(page: Page, case_name: str) -> Path:
    output = Path("artifacts") / f"{case_name}-failure.png"
    output.parent.mkdir(exist_ok=True)
    page.screenshot(path=str(output), full_page=True)
    return output

真实项目中可以在 pytest fixture、失败钩子或测试框架报告层统一处理。统一处理的好处是命名、目录和保留策略一致。

5.2 场景二：全页截图，用于长页面验收

全页截图适合产品详情页、协议页、运营落地页和后台配置页。它会截取整个可滚动页面，而不是只截取当前视口。[1]

from playwright.sync_api import sync_playwright


with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page(viewport={"width": 1440, "height": 900})
    page.goto("https://example.com", wait_until="domcontentloaded")
    page.screenshot(path="artifacts/long-page.png", full_page=True)
    browser.close()

需要注意，动态页面可能在滚动过程中加载图片或触发懒加载。企业项目应先等待关键内容完成，再截图，不要把“截图完成”误当成“页面业务完成”。

5.3 场景三：元素截图，用于局部证据

当页面很长、但问题只发生在订单卡片或错误提示框时，元素截图比全页截图更便于查看和归档。

from playwright.sync_api import sync_playwright


with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com", wait_until="domcontentloaded")

    card = page.get_by_role("article").first
    card.screenshot(path="artifacts/order-card.png")

    browser.close()

元素截图依赖定 位器。定位 器优先选择用户能理解的角色、名称和标签；如果业务组件没有稳定语义，可以让开发补充 data-testid，而不是把深层 CSS 选择器写进几十个测试文件。[3]

5.4 场景四：截图进入内存，用于上传或像素比对

截图不一定要先写文件。可以先得到二进制内容，再交给对象存储、视觉比对服务或报告附件。

from playwright.sync_api import sync_playwright


with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com", wait_until="domcontentloaded")

    image_bytes = page.screenshot(type="png")
    print(f"screenshot bytes: {len(image_bytes)}")

    browser.close()

5.5 截图常见错误

六、录制功能详解：视频不是 Trace 的替代品

6.1 Python 手动录制

Python Library 模式通过 record_video_dir 开启录制。关键规则是：视频在 BrowserContext 关闭后才会最终保存。[5]

from pathlib import Path
from playwright.sync_api import sync_playwright


video_dir = Path("artifacts/videos")
video_dir.mkdir(parents=True, exist_ok=True)


with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    context = browser.new_context(
        viewport={"width": 1280, "height": 720},
        record_video_dir=str(video_dir),
        record_video_size={"width": 1280, "height": 720},
    )
    page = context.new_page()
    page.goto("https://example.com", wait_until="networkidle")
    page.get_by_role("heading").first.wait_for()

    video = page.video
    context.close()

    if video is not None:
        print(f"video path: {video.path()}")

    browser.close()

注意，page.video.path() 也要在页面或 Context 关闭之后读取。若忘记关闭 Context，CI 进程可能结束了，视频却没有完整落盘。

6.2 视频尺寸与文件大小

官方文档说明，视频默认会按视口缩放到不超过 800×800 的范围。如果需要固定视频尺寸，应同时设置 viewport 和 record_video_size。[5]

企业项目可以采用以下策略：

1. 本地调试时按需开启视频，避免磁盘快速增长。
2. CI 只在首次重试时录制视频。
3. 只保留失败或重试测试的视频。
4. 按项目、分支、提交号、浏览器和测试名组织目录。
5. 对视频设置对象存储生命周期策略，避免永久保留。

6.3 Playwright Test 中的按需录制

Playwright Test 的视频配置使用 TypeScript。官方支持 off、on、retain-on-failure 和 on-first-retry 等模式。[2]

import { defineConfig } from '@playwright/test';

export default defineConfig({
  retries: 1,
  use: {
    video: 'on-first-retry',
  },
});

如果希望失败测试保留视频、成功测试自动清理，可以使用：

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    video: 'retain-on-failure',
  },
});

6.4 视频适合什么，不适合什么

视频适合复盘交互顺序、观察动画或页面跳转、展示用户操作流程，也适合产品和测试团队快速理解问题。

视频不适合替代网络日志、DOM 快照和接口响应。面对“为什么元素不可点击”“为什么接口返回异常”“为什么定 位器匹配了多个元素”等问题，Trace 通常比视频更高效。

七、Trace Viewer：企业 CI 调试的主力工具

Trace Viewer 可以查看每个动作的时间线、动作前后快照、定位 器、源代码、调用日志、错误、控制台、网络请求、元数据和附件。[4]

7.1 CI 推荐配置

import { defineConfig } from '@playwright/test';

export default defineConfig({
  retries: 1,
  use: {
    screenshot: 'only-on-failure',
    video: 'on-first-retry',
    trace: 'on-first-retry',
  },
});

这套配置的含义是：平时不制造大量工件，失败时至少有截图；第一次重试时记录视频和 Trace；如果第一次执行偶发失败，重试现场会成为诊断证据。

7.2 查看 Trace

npx playwright show-trace test-results/example-test/trace.zip

也可以使用官方 Trace Viewer 网页打开 Trace 文件。官方说明，网页版本在浏览器本地处理 Trace，不会把 Trace 内容上传到外部服务。[4] 企业使用时仍然要遵循公司数据分级和浏览器安全策略，不要把生产真实数据直接放进公共环境。

7.3 为什么不建议默认trace: 'on'

Trace 会记录大量调试信息，官方建议不要在每个测试上默认开启，因为它会带来明显的性能和存储成本。[3] [4] 更合理的策略是：本地排查时临时开启，CI 使用 on-first-retry 或 retain-on-failure。

八、企业项目落地方案：从目录到治理

8.1 推荐目录结构

project/
├── tests/
│   ├── login_test.py
│   ├── payment_test.py
│   └── fixtures.py
├── artifacts/
│   ├── screenshots/
│   ├── videos/
│   └── traces/
├── reports/
├── pytest.ini
└── requirements.txt

实际 CI 中可以把 artifacts/ 映射到流水线工件目录，并为每次运行增加提交号和流水线编号。

8.2 用环境变量控制是否录制

import os
from pathlib import Path
from playwright.sync_api import sync_playwright


record_video = os.getenv("PW_RECORD_VIDEO", "0") == "1"
video_dir = Path(os.getenv("PW_VIDEO_DIR", "artifacts/videos"))
video_dir.mkdir(parents=True, exist_ok=True)


with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    context_options = {"viewport": {"width": 1280, "height": 720}}

    if record_video:
        context_options.update({
            "record_video_dir": str(video_dir),
            "record_video_size": {"width": 1280, "height": 720},
        })

    context = browser.new_context(**context_options)
    page = context.new_page()
    page.goto("https://example.com", wait_until="domcontentloaded")
    page.screenshot(path="artifacts/screenshots/home.png")
    context.close()
    browser.close()

本地需要录像时执行：

PW_RECORD_VIDEO=1 pytest -q

普通回归则不打开视频：

pytest -q

8.3 CI 工件命名规范

推荐使用以下字段组成文件名：

{project}-{browser}-{test_name}-{retry}-{status}.{ext}

例如：

web-chromium-payment-refund-0-failed.png
web-chromium-payment-refund-1-retry.webm
web-chromium-payment-refund-1-retry-trace.zip

命名规范的目的不是“好看”，而是让开发人员可以不打开报告，直接从文件名定位到浏览器、用例、重试次数和状态。

8.4 数据安全和合规边界

截图、视频和 Trace 可能包含用户姓名、手机号、订单号、Token、Cookie、接口响应和内部域名。企业落地至少需要落实以下措施：

九、和 Selenium、Cypress 的对比：不要只看“谁更快”

Selenium 官方将 WebDriver 定义为通过原生方式驱动浏览器的标准化接口，并强调 W3C WebDriver 和 WebDriver BiDi 的生态价值。[6] Cypress 官方文档则强调手动截图、失败自动截图、按 spec 录制视频以及云端 Test Replay。[7]

**选型建议：**新建现代 Web E2E 项目，优先评估 Playwright；如果企业已经积累大量 Selenium 测试和 WebDriver 基础设施，应先计算迁移成本；如果团队高度偏前端、重视本地交互调试并计划使用 Cypress Cloud，则 Cypress 也有明显吸引力。

十、常用场景清单：什么时候该截图，什么时候该录制

十一、面试官高频问题与标准回答

问题 1：Playwright 的截图和视频有什么区别？

**回答：**截图是某个时间点的静态证据，适合确认页面状态和做视觉比对；视频是测试过程的动态记录，适合复盘交互顺序。两者都不能完全替代 Trace，因为 Trace 还能查看动作、DOM 快照、网络、控制台和源代码位置。

问题 2：为什么视频文件在脚本结束前找不到？

**回答：**Playwright 的视频通常在 Page 或 BrowserContext 关闭后才最终保存。手动创建 Context 时必须显式 context.close()，并在关闭后读取视频路径。[5]

问题 3：企业 CI 是否应该每条用例都录视频？

**回答：**通常不应该。全量录制会增加运行时间、磁盘和上传成本，也会扩大敏感数据暴露面。更合理的是失败保留视频或首次重试录制视频，平时优先保留失败截图和 HTML 报告。

问题 4：为什么官方建议 CI 用 Trace 而不是视频？

**回答：**Trace 不仅有画面，还能按动作查看 DOM 快照、定位 器、网络请求、控制台、错误和源代码位置，因此定位根因的效率更高。[3] [4]

问题 5：sleep()能不能解决截图时机问题？

**回答：**不推荐。固定等待无法保证业务状态完成，时间短了会误判，时间长了会拖慢测试。应使用定位 器的自动等待和 Web-first assertions，例如等待按钮可见、文本出现或请求完成。[3]

问题 6：全页截图为什么可能不稳定？

**回答：**页面可能包含动态时间、随机推荐、动画、懒加载图片、字体加载和滚动触发逻辑。视觉回归前应固定测试数据、关闭动画、等待关键资源，并统一浏览器、视口、时区和字体环境。

问题 7：定位 器和截图有什么关系？

**回答：**元素截图依赖稳定定位 器。定位 器越贴近用户可见语义，测试越不容易因为 DOM 重构而失效。应优先使用 get_by_role、get_by_label、get_by_text 或稳定的测试标识，而不是复杂 CSS 和 XPath。[3]

问题 8：Playwright 和 Selenium 怎么选？

**回答：**新项目要重点评估跨浏览器、并发、Trace 和团队语言栈，Playwright 通常更适合现代 Web E2E。已有大量 Selenium 资产的企业，应先看迁移收益和标准化要求；Selenium 的 WebDriver 标准和生态仍然具有长期价值。[6]

十二、从零到企业可用的落地路线

建议按以下顺序推进，而不是一开始就堆叠全部能力：

1. 先完成稳定的定 位器和断言规范。
2. 为关键失败路径增加截图。
3. 在 CI 中启用失败截图和 HTML 报告。
4. 为首次重试启用视频和 Trace。
5. 建立工件命名、归档、保留期和权限规范。
6. 对高价值页面引入视觉回归，而不是对所有页面盲目截图比对。
7. 统计失败类型，持续减少 flaky test，而不是依赖无限重试掩盖问题。

十三、总结

Playwright 的截图和录制功能，真正的价值不在于“生成一张图片或一个视频”，而在于把自动化测试从一句失败日志升级为一套可审计、可复盘、可定位的证据链。

对于个人学习，建议掌握三个最小示例：页面截图、元素截图、Context 视频录制。对于企业项目，建议采用四件套：失败截图、首次重试视频、首次重试 Trace、HTML 报告。对于长期质量建设，还要把定位 器规范、测试数据隔离、工件治理和失败率统计一起纳入工程体系。

如果只记住一个实践原则，请记住：截图负责证明状态，视频负责还原动作，Trace 负责解释原因。

以上就是一文详解Playwright截图和视频录制功能的常用场景与企业项目实战的详细内容，更多关于Playwright截图和视频录制的资料请关注脚本之家其它相关文章！