自动化测试 / 系统课时

截取页面与元素截图

截取页面与元素截图

本课解决自动化测试中如何保留页面状态证据的问题。你将学会使用 Playwright 截取整页、当前可视区域和指定元素截图,将图片保存到测试输出目录,并在测试失败时利用截图定位问题。

学习目标

  • 掌握页面截图与元素截图的常用 API。
  • 学会选择合适的截图范围并验证生成的文件。
  • 能在测试失败时自动保存截图证据。

截图类型与使用场景

Playwright 提供 page.screenshot() 用于页面截图,locator.screenshot() 用于指定元素截图。根据测试目的,可以保存完整页面、当前视口或某个组件区域。

  • 整页截图:page.screenshot({ fullPage: true }),包含页面可滚动区域,适合检查长页面结构、页面布局和内容缺失问题。
  • 可视区域截图:page.screenshot(),默认截取当前视口,适合记录用户当前看到的页面状态,例如弹窗、导航栏或错误提示。
  • 元素截图:locator.screenshot(),只保存目标元素的区域,适合检查按钮、卡片或标题等组件的显示状态。

三者的主要区别是截图范围。页面截图由 Page 对象执行,元素截图由 Locator 对象执行。元素截图会在必要时将目标元素滚动到视口内,并等待元素满足截图条件。

如果只需要记录一个组件的异常,优先使用元素截图,可以减少无关内容;如果问题涉及组件之间的布局关系,则使用页面截图更容易保留完整上下文。

实现页面截图

在已经安装 @playwright/test 并配置好浏览器的项目中,新建 tests/screenshot.spec.ts。示例访问公开演示页面,确认标题可见后,分别生成整页、视口和标题元素截图。

为了避免多次运行或并行测试时发生文件覆盖,使用 Playwright 提供的 testInfo.outputPath() 获取当前测试专属的输出路径,而不是将图片直接写入项目根目录。

ts
import { test, expect } from '@playwright/test';

test('capture screenshot', async ({ page }, testInfo) => {
  await page.goto('https://example.com');

  const heading = page.locator('h1');
  // 确认页面已显示目标内容,避免过早截图。
  await expect(heading).toHaveText('Example Domain');

  // 保存完整页面,包括视口之外的可滚动内容。
  await page.screenshot({
    path: testInfo.outputPath('page.png'),
    fullPage: true,
  });

  // 默认只截取当前浏览器视口。
  await page.screenshot({
    path: testInfo.outputPath('viewport.png'),
  });

  // 只保存标题元素的实际区域。
  await heading.screenshot({
    path: testInfo.outputPath('title.png'),
  });
});

预期结果:测试通过,在当前测试专属的输出目录下生成三个 PNG 文件。

text
page.png      完整页面截图
viewport.png  当前视口截图
title.png     只包含 h1 标题区域的截图

示例中的演示网站页面较短,整页截图和视口截图可能看起来相同。这并不代表参数未生效;在页面内容超过视口高度时,两者的区别会更加明显。

验证截图文件

在项目根目录执行测试命令:

bash
npx playwright test tests/screenshot.spec.ts

预期结果:终端显示测试通过,且没有截图写入错误。若当前配置只启用一个浏览器项目,通常会看到类似输出:

text
1 passed (<TIME>)

<TIME> 表示实际执行耗时;如果配置了多个浏览器项目,测试通过数量会相应增加。

测试完成后,打开 test-results 目录,找到本次测试对应的输出文件夹,分别查看三个 PNG 文件。实际文件夹名称可能包含测试名称和浏览器项目名称,不应在脚本中依赖固定的完整目录名。

可以从以下三个方面验证结果:

  1. page.png 包含整个页面,长页面内容没有被视口边界截断。
  2. viewport.png 的范围对应当前浏览器视口,不包含视口外的内容。
  3. title.png 只显示 Example Domain 标题及其元素区域,没有截入其他页面组件。

如果没有生成图片,先检查测试是否执行到截图语句,再检查目标网站是否可访问、断言是否提前失败,以及输出目录是否具有写入权限。

截图注意事项

截图路径通常应该固定到测试输出目录,例如 test-results,避免污染项目目录。使用 testInfo.outputPath() 可以自动组织每次测试的文件,但这些文件属于测试运行产物,下一次运行时可能被清理;需要长期保存的证据应另外归档或上传到 CI 构建产物。

对于失败自动截图,可以在 playwright.config.ts 的 use 配置中设置 screenshot: 'only-on-failure'。这样测试失败时,运行器会自动保存页面截图,不必在每个测试中重复调用截图 API。该设置保存的是失败时的页面证据,不保证包含更早发生异常时的瞬间状态。

截图还应注意动态内容的影响。动画、异步加载的数据、时间戳和随机内容都可能导致不同运行之间的图片存在差异。截图前应等待关键元素达到预期状态;必要时为截图设置 animations: 'disabled',降低动画造成的画面不一致。

实际项目中,可以用整页截图记录布局问题,用视口截图记录交互现场,用元素截图定位组件异常,再结合断言信息与 Trace 追踪还原失败原因。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

截取页面与元素截图

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通