Skip to main content
Cypress应用

screenshot

对被测应用进行截图，并可选择包含 Cypress命令日志。

语法​

.screenshot()
.screenshot(fileName)
.screenshot(options)
.screenshot(fileName, options)

// ---或---

cy.screenshot()
cy.screenshot(fileName)
cy.screenshot(options)
cy.screenshot(fileName, options)

用法​

正确用法

cy.screenshot()
cy.get('.post').screenshot()

参数​

fileName (String)

图像文件的名称。将相对于 截图文件夹和 测试文件路径。当传入路径时，将创建对应的文件夹结构。 更多信息请参见下面的 命名规则。

options (Object)

传入一个选项对象以改变.screenshot()的默认行为。

选项默认值描述
logtrue在命令日志中显示该命令
blackout[]字符串选择器数组，用于匹配截图时应被涂黑的元素。不适用于runner模式的截图。
capture'fullPage'指定要截取Cypress测试运行器的哪些部分。此值对元素截图无效。有效值为viewport、fullPage或runner。当为viewport时，截取被测应用在当前视口中的部分。当为fullPage时，截取被测应用从顶部到底部的全部内容。当为runner时，截取整个浏览器视口，包括Cypress命令日志。对于测试失败时自动截取的截图，此选项始终强制为runner。当启用Test Replay且Runner UI被隐藏时，runner模式的截图将不包含Runner UI，而是仅截取被测应用在当前视口中的部分。
clipnull用于裁剪最终截图图像的位置和尺寸（以像素为单位）。应为以下形状：{ x: 0, y: 0, width: 100, height: 100 }
disableTimersAndAnimationstrue为true时，在截图期间阻止JavaScript定时器（setTimeout、setInterval等）和CSS动画运行。
paddingnull用于调整元素截图尺寸的内边距。可以是一个数字，或最多四个数字的数组使用CSS简写表示法。此属性仅适用于元素截图，其他类型的截图将被忽略。
scalefalse是否缩放应用以适应浏览器视口。当capture为runner时，此选项始终强制为true。
timeoutresponseTimeout等待.screenshot()解析的时长，超过则超时
overwritefalse保存时是否覆盖同名的重复截图文件。
onBeforeScreenshotnull在非失败截图前调用的回调函数。当截取元素截图时，参数为被截取的元素。对于其他截图，参数为document。
onAfterScreenshotnull在非失败截图后调用的回调函数。当截取元素截图时，第一个参数为被截取的元素。对于其他截图，第一个参数为document。第二个参数为关于截图的信息，包括保存的path和截图的dimensions。

有关这些选项的更多详情以及如何为所有.screenshot()调用设置默认值， 请参阅Cypress.Screenshot API文档。

生成结果 了解主题管理​

  • .screenshot()返回与传入时相同的主题。
  • 在.screenshot()之后继续链式调用依赖于主题的命令是不安全的。

示例​

截图默认保存在cypress/screenshots文件夹中。 您可以在Cypress配置中更改截图保存的目录。

无参数​

截取截图​

// cypress/e2e/users.cy.js

describe('我的测试', () => {
  it('截取截图', () => {
    // 截图将保存为
    // cypress/screenshots/users.cy.js/我的测试 -- 截取截图.png
    cy.screenshot()
  })
})

文件名​

截取截图并保存为指定文件名​

// 截图将保存为
// cypress/screenshots/spec.cy.js/clicking-on-nav.png
cy.screenshot('clicking-on-nav')

截取截图并保存到指定目录​

// 截图将保存为
// cypress/screenshots/spec.cy.js/actions/login/clicking-login.png
cy.screenshot('actions/login/clicking-login')

裁剪​

将截图裁剪到指定位置和尺寸​

// 截图将从顶部和左侧各裁剪20px
// 尺寸为400px x 300px
cy.screenshot({ clip: { x: 20, y: 20, width: 400, height: 300 } })

截取元素​

截取第一个.post元素的截图​

cy.get('.post').first().screenshot()

截取第一个.post元素的截图，并添加10px内边距​

cy.get('.post').first().screenshot({ padding: 10 })

链式调用截图后点击被截取的元素​

cy.get('button').first().screenshot().click()

通过onAfterScreenshot回调获取截图信息​

cy.screenshot('my-screenshot', {
  onAfterScreenshot($el, props) {
    // props包含关于截图的信息，
    // 包括但不限于以下内容：
    // {
    //   name: 'my-screenshot',
    //   path: '/Users/janelane/project/screenshots/spec.cy.js/my-screenshot.png',
    //   size: '15 kb',
    //   dimensions: {
    //     width: 1000,
    //     height: 660,
    //   },
    //   scaled: true,
    //   blackout: [],
    //   duration: 2300,
    // }
  },
})

注意事项​

命名规则​

截图命名遵循以下规则：

  • 截图保存在截图文件夹内。 在该文件夹内，截图保存在相对于测试文件路径的文件夹结构中，此路径会移除与其他测试文件共享的公共祖先路径。在此文件夹内，截图将以测试名称保存： {screenshotsFolder}/{adjustedSpecPath}/{testName}.png
  • 对于命名的截图，使用名称代替套件和测试名称： {screenshotsFolder}/{adjustedSpecPath}/{name}.png
  • 对于任何重复的截图（无论是否命名），将在名称后附加数字： {screenshotsFolder}/{adjustedSpecPath}/{testName} (1).png。
info

可以通过向cy.screenshot()传递{overwrite: true}选项来显式覆盖重复的截图。

  • 对于失败的截图，使用默认命名方案并在名称后附加 (failed)： 
    {screenshotsFolder}/{adjustedSpecPath}/{testName} (failed).png

例如，给定位于cypress/e2e/users/login.cy.js的测试文件：

describe('我的测试', () => {
  it('截取截图', () => {
    // 注意：此文件包含多个截图
    // 每个截图都有一个公共祖先路径`/users/`。
    // 在此场景中，`/users/`将从路径中移除。
    // cypress/screenshots/login.cy.js/我的测试 -- 截取截图.png
    cy.screenshot()
    // cypress/screenshots/login.cy.js/我的测试 -- 截取截图 (1).png
    cy.screenshot()
    // cypress/screenshots/login.cy.js/我的测试 -- 截取截图 (2).png
    cy.screenshot()

    // cypress/screenshots/login.cy.js/my-screenshot.png
    cy.screenshot('my-screenshot')
    // cypress/screenshots/login.cy.js/my-screenshot (1).png
    cy.screenshot('my-screenshot')
    // cypress/screenshots/login.cy.js/my/nested/screenshot.png
    cy.screenshot('my/nested/screenshot')

    // 如果此测试失败，截图将保存为
    // cypress/screenshots/login.cy.js/我的测试 -- 截取截图 (failed).png
  })
})
info

有关如何编写和组织测试以及如何保存资产的更多信息， 请参阅编写和组织测试

after:screenshot插件事件​

您可以通过after:screenshot插件事件 获取任何给定截图的详细信息并在其写入磁盘后进行操作。

测试失败​

测试失败时自动截图​

在通过cypress run运行或在持续集成中运行时， Cypress会在测试失败时自动截图。您可以通过在screenshotOnRunFailure或 Cypress.Screenshot.defaults()中 将screenshotOnRunFailure设置为false来关闭此功能。

查看截图​

CI中的截图​

您可以在Cypress Cloud中查看CI运行期间截取的截图，无需额外工作。

或者，要在持续集成UI中查看截图，大多数CI提供商都提供了将截图导出为工件并使其可用的方法。请参阅其相应文档。

异步性​

理解截图何时被截取​

截图是一个异步操作，大约需要100ms完成。在截图完成时， 您的应用中可能已发生变化。重要的是要意识到截图可能不完全反映命令发出时应用的状态。

例如 - 假设我们编写的命令超时： cy.get('#element')。这会导致测试失败。 Cypress随后会自动在测试失败时截图，但在这100ms的时间范围内， 您的应用中可能已发生变化。理论上，您的应用可能渲染了最初期望存在的元素。 当这种情况发生时，截图可能会提供令人困惑的结果。虽然不太可能，但理论上存在这种可能性。

另一个需要注意的问题是，我们自己的命令日志在底层使用React，并且仅在动画帧期间异步渲染。 您可能会看到在命令日志完成渲染之前截取的截图。这意味着您可能看不到错误显示在截图中。 但这也是为什么我们允许录制视频 - 以显示完整的失败过程。

我们尽最大努力将截图与渲染器同步，但在此期间被测应用的当前状态可能已发生变化， 无法准确反映您想要捕获的内容。

全页截图和固定/粘性元素​

当向capture选项传递fullPage时，Cypress会从顶部到底部滚动被测应用， 在每个点截取截图并将它们拼接在一起。因此，position: fixed或position: sticky的元素 将在最终截图中多次出现。为防止这种情况，在大多数情况下，您可以在截图前以编程方式将元素更改为position: absolute， 然后在截图后更改回来，如下所示：

cy.get('.sticky-header').invoke('css', 'position', 'absolute')
cy.screenshot()
cy.get('.sticky-header').invoke('css', 'position', null)

Chromium特定行为与标签页相关​

当Cypress标签页的渲染器进程暂停时，Chromium不会截取截图。 这种情况最常见于通过点击带有target="_blank"的锚点打开新标签页时。 为了适应在此情况下截取截图，Cypress会在截图时尝试激活Cypress标签页。 我们通过Chromium扩展尽最大努力激活标签页。如果扩展被禁用， Cypress会将主标签页强制置前。这会导致浏览器在开放模式下窃取焦点。 为防止Cypress窃取焦点，请确保扩展已启用。

规则​

要求 了解命令链​

  • cy.screenshot()可以链式调用自cy或返回单个DOM元素的命令。

断言 了解断言​

  • cy.screenshot()仅会运行您链式调用的一次断言，并且不会 重试。

超时设置 了解超时机制​

  • cy.screenshot()不应超时。
caution

由于cy.screenshot()是异步的，技术上在与内部Cypress自动化API通信时可能存在超时。 但出于实际目的，这不应发生。

命令日志​

使用特定文件名截取截图

cy.screenshot('my-image')

上述命令将在命令日志中显示为：

命令日志截图

当点击命令日志中的screenshot时，控制台输出以下内容：

控制台日志截图

历史​

版本变更
3.5.0添加了对padding选项的支持。

另请参阅​

目录