Skip to main content
Cypress App

Screenshots and Videos

tip
Debugging Cypress Cloud Test Runs?

Don't rely on artifact representations or reproducing failing conditions locally. Replay the test as it executed during the recorded run with full debug capability using Test Replay.

Screenshots​

Cypress takes screenshots whether you are running via cypress open or cypress run, even in CI.

To take a manual screenshot you can use the cy.screenshot() command.

Additionally, Cypress automatically captures screenshots when a failure happens during cypress run. Cypress does not automatically take screenshots on failure during cypress open.

You can turn off screenshots on test failure entirely by setting screenshotOnRunFailure to false from within the Cypress configuration or by setting screenshotOnRunFailure to false in the Cypress.Screenshot.defaults().

Cypress stores screenshots in the screenshotsFolder, which defaults to cypress/screenshots.

Before cypress run, Cypress clears the entire contents of the screenshotsFolderβ€”every file and nested subfolder, not just images. If you do not want to clear your screenshots folder before a run, you can set trashAssetsBeforeRuns to false. See the trashAssetsBeforeRuns notes for more details.

Videos​

Video recording is disabled by default, but you can turn it on by setting video to true from within your configuration.

If enabled, Cypress records a video for each spec file when running tests during cypress run. Cypress does not record videos during cypress open.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
video: true,
})

Cypress stores videos in the videosFolder, which defaults to cypress/videos.

When using the --record flag while running your tests, Cypress processes, compresses, and uploads videos to Cypress Cloud after every spec file runs, successful or not. To change this behavior to only process videos in the case that tests fail, see how to delete videos for specs without failing or retried tests. Deleting the video prevents Cypress from uploading the video to Cypress Cloud.

Before cypress run, Cypress clears the entire contents of the videosFolderβ€”every file and nested subfolder, not just videos. If you do not want to clear your videos folder before a run, you can set trashAssetsBeforeRuns to false. See the trashAssetsBeforeRuns notes for more details.

Video encoding​

After Cypress records a video, Cypress encodes the video to a commonly digestable format. Part of this encoding process includes video compression.

Compression is disabled by default, meaning Cypress skips this step completely, so the file size of the video is larger, but the encoding process is faster. Setting videoCompression to true coerces the video compression value to 32 Constant Rate Factor (CRF), which takes longer to process, but results in a smaller video.

Enabling compression

const { defineConfig } = require('cypress')

module.exports = defineConfig({
videoCompression: true,
})

If your spec files have a long run duration and videoCompression is enabled, you might notice a time gap between a finished spec and a new spec starting during cypress run. During this time, Cypress is encoding the captured video and possibly uploading it to Cypress Cloud.

Change compression value from 32

const { defineConfig } = require('cypress')

module.exports = defineConfig({
videoCompression: 15,
})

In addition to enabling or disabling video compress, you can specify the CRF value used to compress the video. Here are some common scenarios:

  • If the machine is encoding the video slowly (which is often the case for virtual machines that use less CPU cores), try increasing the CRF value.

  • If your videos are extremely low quality, try decreasing the CRF value.

A lower videoCompression value spends less time compressing and results in a bigger video file size and higher quality video.

info

If you are an FFmpeg pro and want to see all the settings and debug messages during the encoding, run Cypress with the following system environment variable:

DEBUG=cypress:server:video

Video chapters​

While encoding a video, Cypress embeds chapter markers into the resulting .mp4 file, one for each test attempt in the spec. Video players that support chapters, such as VLC, QuickTime, and IINA, use these markers to skip to a specific test instead of scrubbing through the whole recording. Each chapter is titled with the full title of the test, including the titles of the suites it is nested in. When a test runs more than once because of test retries, each attempt gets its own chapter.

caution

Cypress writes chapters only during video compression, and videoCompression is disabled by default. To get chapters, enable both video and videoCompression.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
video: true,
videoCompression: true,
})

Setting videoCompression to a CRF value such as 15 also produces chapters. Setting it to false or 0 skips encoding entirely, so the video contains no chapters.

Chapters only help when you open the video file yourself. Record your runs to Cypress Cloud and you get this for free: Cypress Cloud lists every test in the run alongside its video, and selecting one takes you straight to that moment, with no chapters to configure and no scrubbing.

note

Skip the video and debug the run with Test Replay. Rather than watching a recording, you replay the test exactly as it executed in CI, so you can time travel to the point of failure and inspect the DOM, network requests, console logs, JavaScript errors, and element rendering, giving you the same debugging experience you have locally without reproducing the failure on your machine.

Control which videos to keep and upload to Cypress Cloud​

You may want to have more control over which videos you want to keep and upload to Cypress Cloud. Deleting videos after the run can save resource space on the machine as well as skip the time used to process, compress, and upload the video to Cypress Cloud.

To only process videos in the case that a test fails, you can delete videos for specs without failing or retried tests, which does not upload the video of passed runs to Cypress Cloud.

For more fine grained control, you can use Cypress's after:spec event listener that fires after Cypress runs each spec file and delete the video when certain conditions are met.

Delete videos for specs without failing or retried tests​

The example below shows how to delete the recorded video for specs that had no retry attempts or failures when using Cypress test retries.

const { defineConfig } = require('cypress')
const fs = require('fs')

module.exports = defineConfig({
// setupNodeEvents can be defined in either
// the e2e or component configuration
e2e: {
setupNodeEvents(on, config) {
on('after:spec', (spec, results) => {
if (results && results.video) {
// Do we have failures for any retry attempts?
const failures = results.tests.some((test) =>
test.attempts.some((attempt) => attempt.state === 'failed')
)
if (!failures) {
// delete the video if the spec passed and no tests retried
fs.unlinkSync(results.video)
}
}
})
},
},
})

Now What?​

So you are capturing screenshots and recording videos of your test runs, now what?

Share Them With Your Team​

Something you can take advantage of today is Cypress Cloud: our companion enterprise service that stores your artifacts and makes them viewable from any web browser and shareable with your team.

Visual Regression Test / Screenshot Diffing​

Another possibility is visual regression testing: comparing screenshots of past runs with the current run to ensure that nothing changed. Read about how to implement visual testing.

See also​