46. 截图 Screenshots 与视频 Videos

本节目标：学完你能随手给整个页面或某个元素拍照，也能在测试里录下视频，方便失败后回看。

测试挂了，光看报错文字常常不够。Screenshot（截图）能定格那一刻页面长啥样；Video（视频）能回放整个过程。两者都是排错的好帮手。

截一张图有多简单

最朴素的写法，保存成文件就行：

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

test('给首页拍张照', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.screenshot({ path: 'screenshot.png' });
});

page.screenshot 还接受很多参数，比如图片格式、裁剪区域、清晰度。用到时再去翻 API 文档即可。

全页截图

普通截图只拍「当前屏幕这么大」。全页截图（full page）会把整页滚到底，连屏幕外的内容一起拍。

await page.screenshot({ path: 'screenshot.png', fullPage: true });

Note

全页截图适合做存档或人工核对。但它依赖页面能正常滚动，遇到弹窗或固定浮层可能拍得不全。

截某个元素的图

有时你只想看一个按钮、一个卡片。用 Locator（定位器）去截，范围就只圈住那个元素。

await page.locator('.header').screenshot({ path: 'screenshot.png' });

元素截图不会被页头页脚干扰，做视觉对比时更干净。

截到内存里，不写文件

不想落盘，可以把图读成缓冲区（buffer），拿去压缩、比对，或发给第三方工具。

const buffer = await page.screenshot();
console.log(buffer.toString('base64'));

录视频的开关

视频默认是关的。在 playwright.config.ts 里用 video 配置打开它，常用取值有这几个：

'off'：不录（默认）。
'on'：每次运行都录、都保留。
'retain-on-failure'：每次都录，但通过的会删掉。
'on-first-retry'：只在第一次重试时录。
'on-all-retries'：每次重试都录。

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

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

Tip

新手常在这里翻车：把 video 设成 'on'，跑一堆全录，磁盘很快爆。日常建议用 'retain-on-failure' 或 'on-first-retry'。

视频的精细控制

视频还能指定尺寸。常见做法是限定分辨率，避免文件过大：

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

export default defineConfig({
  use: {
    video: {
      mode: 'on-first-retry',
      size: { width: 640, height: 480 },
    },
  },
});

Tip

想回看测试过程，更推荐用 Trace（追踪）——它记录了 DOM 快照、网络请求和操作步骤，信息比视频全得多。下一章就讲它。

Warning

视频要等页面或浏览器上下文（context）关闭后才真正落盘。手动建 context 时，记得 await context.close()，否则视频可能丢。

多页面场景取视频

一个测试里切了好几个页面，可以用 page.video() 拿到对应的视频对象，再问它文件在哪：

// 没开录制时 page.video() 返回 null，所以要判空
const video = page.video();
if (video) {
  const videoPath = await video.path();
  console.log(videoPath);
}

截图和视频怎么选

想快速看「长啥样」：截图，尤其元素截图。
想回放「怎么一步步坏的」：视频。
想进 CI 排错：官方更推荐用 Trace（追踪，见下一章），它比视频信息更全。

一句话：截图抓瞬间，视频看全过程，Trace 两者都包。

小结

截图和视频都是「事后看现场」的工具。截图抓瞬间，适合快速确认长啥样；视频看全过程，但占磁盘，日常开 on-first-retry 就够。真要排错，下一章的 Trace 比这俩都强。新手别把 video 设成 on，磁盘会爆。