Skip to main content
Cypress应用

Cypress.Screenshot

Screenshot API 允许您设置默认配置，用于控制以下场景的截图行为：

  • 执行 .screenshot 命令时的截图
  • 测试失败时自动捕获的截图

可配置项包括：

  • 截取屏幕的哪些部分
  • 是否在截图中缩放被测应用
  • 截图时是否禁用 JavaScript 定时器和 CSS 动画
  • 运行失败时是否自动截图
  • 截图时需要屏蔽的元素
  • 截图前是否等待命令日志同步完成

语法​

Cypress.Screenshot.defaults(options)

参数​

options (Object)

包含以下一个或多个配置项的对象：

配置项默认值描述
blackout[]字符串选择器数组，匹配截图时需要屏蔽的元素。不适用于 runner 模式的截图。
capture'fullPage'指定 Cypress 测试运行器的截取范围。元素截图不受此配置影响。有效值为 viewport、fullPage 或 runner。viewport 只截取当前视口中的被测应用；fullPage 截取完整的被测应用页面；runner 截取整个浏览器窗口（包括 Cypress 命令日志）。测试失败时的自动截图强制使用 runner 模式。当启用 Test Replay 且隐藏了 Runner UI 时，runner 截图将不包含 Runner UI，仅截取当前视口中的被测应用。
disableTimersAndAnimationstrue为 true 时，截图期间会暂停 JavaScript 定时器（setTimeout、setInterval 等）和 CSS 动画。
scalefalse是否缩放应用以适应浏览器视口。runner 模式强制启用此选项。
screenshotOnRunFailuretrue为 true 时，在 cypress run 执行期间遇到失败会自动截图。
overwritefalse保存截图时是否覆盖同名文件。
onBeforeScreenshotnull非失败截图前的回调函数。元素截图时参数为被截取的元素，其他截图时参数为 $el。
onAfterScreenshotnull非失败截图后的回调函数。元素截图时第一个参数为被截取的元素，其他截图时第一个参数为 $el。第二个参数包含截图相关属性，如保存路径和截图尺寸。

示例​

截图前屏蔽元素​

匹配指定选择器的元素会在截图时被屏蔽（仅当 capture 为 viewport 时生效）。runner 模式会忽略此配置。

Cypress.Screenshot.defaults({
  blackout: ['.secret-info', '[data-hide=true]'],
})

截取整个 Cypress 浏览器窗口​

默认情况下 cy.screenshot() 只截取被测应用。调试时可能需要截取整个 Cypress 浏览器窗口。

Cypress.Screenshot.defaults({
  capture: 'runner',
})

允许定时器和动画继续运行​

默认会禁用 JavaScript 定时器和 CSS 动画以防止截图期间被测应用发生变化，但可以关闭此行为。

Cypress.Screenshot.defaults({
  disableTimersAndAnimations: false,
})

禁用运行失败时的自动截图​

默认在 cypress run 执行失败时会自动截图，可以禁用此功能。

Cypress.Screenshot.defaults({
  screenshotOnRunFailure: false,
})

覆盖现有截图​

默认情况下，Cypress 会为同一测试中的每次截图生成唯一文件。可以通过 overwrite 选项覆盖同名截图文件。

Cypress.Screenshot.defaults({
  overwrite: true,
})

缩放 viewport 和 fullPage 截图​

默认情况下，当 capture 为 viewport 时会关闭被测应用的缩放，以防止不同分辨率屏幕上的截图差异。可以启用缩放使截图效果与 Cypress 正常使用时一致。runner 模式强制启用此选项。

Cypress.Screenshot.defaults({
  scale: true,
})

使用回调函数修改 DOM​

onBeforeScreenshot 和 onAfterScreenshot 回调提供了同步修改 DOM 的机会，可以创建更一致的截图状态。

下例中，假设应用中有显示当前时间的时钟，这会导致截图结果不确定。可以通过回调在截图前隐藏时钟，截图后再显示。

Cypress.Screenshot.defaults({
  onBeforeScreenshot($el) {
    const $clock = $el.find('.clock')

    if ($clock) {
      $clock.hide()
    }
  },

  onAfterScreenshot($el, props) {
    const $clock = $el.find('.clock')

    if ($clock) {
      $clock.show()
    }
  },
})

从回调中获取截图属性​

Cypress.Screenshot.defaults({
  onAfterScreenshot($el, props) {
    // props 包含截图相关信息，例如：
    // {
    //   path: '/Users/janelane/project/screenshots/my-screenshot.png',
    //   size: '15 kb',
    //   dimensions: {
    //     width: 1000,
    //     height: 660,
    //   },
    //   scaled: true,
    //   blackout: ['.foo'],
    //   duration: 2300,
    // }
  },
})

注意事项​

截图配置的存放位置​

放置此配置的理想位置是在 supportFile中， 因为它会在任何测试文件执行前加载。

历史版本​

版本号变更内容
8.7.0新增 overwrite 配置选项。

相关链接​

目录