To control Cypress screenshots, set screenshotOnRunFailure to enable or disable automatic failure captures, screenshotsFolder to choose where they are saved, and trashAssetsBeforeRuns to preserve artifacts between cypress run executions. For a screenshot at a specific point in a test, call cy.screenshot(). These settings control capture and storage—not visual comparison.
Configure automatic screenshots and the output folder
In a current Cypress project, the screenshot settings belong in the top-level project configuration. Here is a CommonJS example for cypress.config.js:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotOnRunFailure: true,
screenshotsFolder: 'cypress/screenshots',
trashAssetsBeforeRuns: false,
})The example keeps automatic failure screenshots enabled, uses Cypress’s documented default directory, and prevents Cypress from clearing artifact folders before a run. Change only the settings you need. For example, to turn off automatic captures after failures, set screenshotOnRunFailure: false.
Cypress documents these defaults: screenshotOnRunFailure is true, screenshotsFolder is cypress/screenshots, and trashAssetsBeforeRuns is true. Confirm the configuration format and supported options against the reference for the Cypress version installed in your project; older projects may use a different configuration shape.
Choose whether failed tests create screenshots
screenshotOnRunFailure controls Cypress’s automatic failure screenshots during cypress run. Set it to false if those files are not useful in your workflow, or leave it enabled to retain a visual artifact when a test fails. This automatic behavior does not apply to failures in cypress open. You can still capture manually with cy.screenshot() in either mode.
Choose where screenshots are written
Set screenshotsFolder to the directory you want Cypress to use. The documented default is cypress/screenshots. Choose a path that fits your project’s artifact collection or CI setup, and make sure any process that uploads or archives screenshots looks in that same location.
Keep artifacts from earlier runs
By default, trashAssetsBeforeRuns is true. Before cypress run, Cypress clears the contents of its artifact folders, including nested files and folders. Set trashAssetsBeforeRuns: false if earlier screenshots must remain. This setting preserves old files, so consider whether your tests or other processes can produce duplicate names or accumulate artifacts over time.
What the screenshot settings control
| Need | Setting or command | Behavior |
|---|---|---|
| Enable or suppress automatic screenshots after failures | screenshotOnRunFailure |
Defaults to true; automatic failure capture applies to cypress run, not cypress open. |
| Change the screenshot directory | screenshotsFolder |
Defaults to cypress/screenshots. |
| Retain prior artifacts before a run | trashAssetsBeforeRuns |
Defaults to true; set it to false to stop the pre-run cleanup. |
| Capture at a chosen point in a test | cy.screenshot() |
Supports names and paths, capture modes, clipping, and blackout selectors. |
| Set reusable screenshot behavior | Cypress.Screenshot.defaults() |
Applies shared screenshot options, such as blackout selectors or overwrite behavior. |
Take a manual screenshot during a test
Use cy.screenshot() when you want an artifact at a particular point, not only after a failure. For example, put a capture after the application has reached the state you want to inspect:
describe('account page', () => {
it('shows the signed-in account', () => {
cy.visit('/account')
cy.get('[data-cy=account-heading]').should('be.visible')
cy.screenshot('signed-in-account')
})
})The assertion makes the intended state explicit before Cypress captures it. In a real test, use the selector and route that match your application. If the application is still loading data, animating, or rendering when the screenshot runs, the image may show an intermediate state rather than the stable result you meant to capture.
Names, paths, and duplicate files
The screenshot filename is resolved relative to the screenshots folder and the spec path. You may supply a name or path to organize captures; Cypress creates the required folder structure for paths. By default, duplicate names receive numeric suffixes. Set overwrite: true when you specifically want a later capture to replace a file with the same name. Be deliberate about overwriting when retaining artifacts across runs.
Capture mode, clipping, and blackout
The screenshot command supports capture modes including viewport, fullPage, and runner. Its documented default is fullPage; choose a mode that matches the artifact you need instead of assuming a screenshot is limited to the visible viewport. Failure screenshots are coerced to runner capture.
Use clip when the useful output is a defined region, and blackout when selected page elements should be obscured in the image. Blackout is useful for hiding dynamic or sensitive on-page content from an artifact, but it does not replace careful handling of screenshots that may contain private data elsewhere on the page.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Set shared screenshot defaults
For options that should apply to screenshots across tests, use Cypress.Screenshot.defaults() in the project’s support setup. For example, this configures selected elements to be blacked out and permits overwriting duplicate files:
Rank #4
Cypress.Screenshot.defaults({
blackout: ['[data-cy=dynamic-content]'],
overwrite: true,
})Use the selector that matches content in your application. Cypress also documents defaults for capture mode, failure screenshots, and whether timers and animations continue. Shared defaults are convenient, but they affect captures broadly: prefer a per-call option when only one screenshot needs different treatment. Confirm the exact option set in the reference for your installed Cypress version.
Failure screenshots, retries, and retained artifacts
With test retries enabled, Cypress can take screenshots for failed attempts as well as the final outcome. New screenshots include an attempt number in the filename. That distinction helps when investigating a flaky test: an image from an early failed attempt can differ from one produced by the eventual passing attempt.
If you need a history across separate cypress run executions, disabling pre-run cleanup is only one part of the workflow. Ensure that your artifact collection keeps the files you care about and that the naming behavior does not obscure which test, spec, run, or retry produced each image. Conversely, if old images would confuse diagnosis, leave cleanup enabled and collect artifacts at the end of each run.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
Can Cypress compare screenshots for visual changes?
No. Cypress’s built-in cy.screenshot() captures an image but does not compare it with a baseline. Visual regression requires a separate comparison tool or integration. When evaluating one, check that it works with your Cypress setup, supports the baseline creation and review process your team needs, and fits your CI workflow.
Reliable visual comparisons also depend on capturing the intended UI state. Wait for the relevant content rather than relying on an arbitrary delay where possible, use stable test data, and account for animations or other changing content. Otherwise, an image difference may reflect timing or dynamic content instead of a meaningful interface change.
Troubleshoot common Cypress screenshot problems
- No automatic screenshot after a failure: Check that
screenshotOnRunFailureis enabled and that you are runningcypress run. Cypress does not automatically capture failures incypress open; add a manualcy.screenshot()if you need a capture there. - Screenshots disappear when a new run starts: Check
trashAssetsBeforeRuns. Its default istrue, which clears artifact-folder contents beforecypress run. Set it tofalsewhen you need previous artifacts to remain. - Files are in an unexpected directory: Check
screenshotsFolderin the configuration actually used by the project, then check the path and spec structure used bycy.screenshot(). Cypress resolves screenshot paths relative to the screenshots folder and spec path. - A screenshot shows a loading or transitional state: Capture after an assertion confirms the specific content or state you need. The application may still be rendering, waiting for data, or animating when the capture runs.
- Several files appear for one retried test: Cypress can capture failed attempts and add an attempt suffix. Check the attempt number before treating the images as duplicate output.
- A later capture has a suffixed filename: Cypress adds numeric suffixes to duplicate names by default. Choose unique names or use
overwrite: trueif replacing the existing file is intentional. - A failure image does not match the requested capture mode: Failure screenshots are coerced to
runnercapture. Use a manual screenshot for a deliberately chosen capture mode.
Performance and artifact-management considerations
Screenshots add image files to the test run’s artifacts. Full-page captures can include substantially more page content than a viewport capture, so choose the smallest useful output for the investigation or review. If you preserve files between runs, plan how they will be named, collected, and eventually removed; otherwise the folder can become harder to inspect and manage. The right trade-off depends on whether you prioritize a clean per-run artifact set or a local history of previous captures.
For visual regression work, consistency is more important than taking many screenshots: capture after the page reaches a known state, keep test data stable, and use a separate image-comparison workflow. Cypress capture alone provides no pass/fail judgment about visual differences.
Recommended Free Tools
Or skip the browser setup
If the task is to capture a website outside a Cypress test—not to configure Cypress’s failure artifacts—ScreenshotNeo provides a screenshot API and MCP server for developers. One GET request returns an image or PDF, without setting up a browser locally. For example, save a PNG of a URL with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for setup and request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot; those cleanup steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. An MCP server lets AI agents use screenshot tools. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. ScreenshotNeo is for separate website captures, not a replacement for Cypress assertions, test retries, or test-failure screenshots.
Sign up for 1,000 free screenshots a month—no card required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →
