Configure Cypress screenshots in your project configuration with three settings: screenshotOnRunFailure controls automatic captures after failed tests, screenshotsFolder chooses where files are written, and trashAssetsBeforeRuns determines whether Cypress clears earlier artifacts before a run. Use cy.screenshot() for deliberate captures inside a test, and Cypress.Screenshot.defaults() for shared capture behavior. Cypress captures images but does not compare them, so visual regression requires a separate comparison workflow.
Set the core screenshot options in Cypress
Place screenshot configuration at the top level of your Cypress project configuration. In a CommonJS project, that is usually cypress.config.js:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotOnRunFailure: true,
screenshotsFolder: 'cypress/screenshots',
trashAssetsBeforeRuns: false,
})Use the equivalent configuration shape for your installed Cypress version and module system. The three settings have separate jobs:
| Need | Setting | Documented default | What it does |
|---|---|---|---|
| Capture failed tests automatically | screenshotOnRunFailure |
true |
Creates a screenshot when a test fails during cypress run. |
| Choose the artifact directory | screenshotsFolder |
cypress/screenshots |
Sets the root folder for automatic and manual screenshot files. |
| Retain earlier artifacts | trashAssetsBeforeRuns |
true |
When enabled, clears the contents of artifact folders before cypress run. |
Enable or suppress failure screenshots
Leave screenshotOnRunFailure at true when screenshots are useful in CI failure reports. Set it to false when screenshots contain sensitive data, consume storage you do not retain, or are not part of your test evidence. This automatic behavior applies to cypress run; Cypress does not automatically take a failure screenshot in cypress open. You can still call cy.screenshot() manually in either mode.
Move the output directory
screenshotsFolder is a project-relative path in normal use. For example, artifacts/cypress/screenshots keeps images beside other CI artifacts, while a path such as test-output/screens separates them from source-controlled files. Make the directory part of your test-artifact upload step if your CI system removes the workspace after a job.
Decide whether each run starts clean
With the default trashAssetsBeforeRuns: true, Cypress removes the entire contents of the relevant artifact folders before cypress run. That includes nested files and folders, not only image files. Set it to false when you need evidence from multiple runs in one workspace, such as a local investigation or a CI job that appends artifacts. If you retain files, give runs distinct locations or names so that old images are not mistaken for current results.
Capture a specific state with cy.screenshot()
Use the command inside a test when a failure screenshot alone is too late or too broad. It works in both interactive and headed/ headless execution modes and accepts a name plus capture options.
describe('checkout', () => {
it('records the payment form', () => {
cy.visit('/checkout')
cy.get('[data-cy="payment-form"]').should('be.visible')
cy.screenshot('checkout/payment-form', {
capture: 'viewport',
blackout: ['.customer-email'],
overwrite: true,
})
})
})Choose a capture mode deliberately
The documented default capture mode is fullPage. Select another mode when the artifact has a narrower purpose:
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteviewportcaptures the currently visible browser viewport.fullPagecaptures the complete scrollable page.runnercaptures the Cypress runner surrounding the application.
Failure screenshots are coerced to runner capture, so an automatic failure artifact is not equivalent to a manual full-page application capture.
Name files and target a subdirectory
The name is relative to screenshotsFolder and the spec path. Cypress creates the folder structure required by a path such as checkout/payment-form. If you omit a name, Cypress derives one from the spec and test. Duplicate names receive numeric suffixes by default; pass overwrite: true when replacing the previous file is intentional.
Clip an area or hide sensitive elements
Use clip to restrict the capture to a rectangle and blackout to cover matching elements. Blackout selectors are useful for account identifiers, changing timestamps, ads, and other pixels that should not enter an artifact. Keep selectors stable and verify that a blackout does not hide the UI state you are trying to diagnose.
cy.screenshot('dashboard/chart', {
capture: 'viewport',
clip: { x: 80, y: 120, width: 960, height: 540 },
blackout: ['[data-sensitive]', '.live-clock'],
})Set reusable defaults with Cypress.Screenshot.defaults()
When every screenshot in a project needs the same treatment, define shared defaults in a support file loaded by your tests. Individual cy.screenshot() options can still override them.
Cypress.Screenshot.defaults({
blackout: ['.cookie-banner', '[data-private]'],
capture: 'viewport',
overwrite: false,
})This API is also useful for central policies such as disabling automatic failure captures or choosing runner capture for a diagnostic suite:
Cypress.Screenshot.defaults({
screenshotOnRunFailure: false,
capture: 'runner',
})Keep project-wide defaults conservative. A global blackout selector that matches too broadly can make every diagnostic image less useful, while global overwrite can erase evidence from repeated states.
Make screenshot artifacts useful in CI
Run the mode that creates automatic failure images
Use cypress run in CI when you expect Cypress to capture failed tests automatically. A local cypress open session is interactive and does not provide that automatic failure behavior, so add an explicit cy.screenshot() while investigating interactively.
Upload the configured folder
Configure your CI artifact step to upload the exact value of screenshotsFolder. If you changed it from the default, an upload rule that still points to cypress/screenshots will appear to produce no screenshots even though Cypress wrote them elsewhere. When trashAssetsBeforeRuns is false, include the run identifier in the artifact destination or archive step to avoid mixing attempts.
Account for retries
When retries are enabled, Cypress can capture a screenshot for each failed attempt. New files include an attempt suffix, allowing you to distinguish an initial failure from a later retry. Treat those images as separate evidence rather than assuming the last file represents the only failure state.
Stabilize the page before capturing
A screenshot can record an intermediate state while the application is still rendering, animating, or waiting for data. Assert the relevant UI state before calling cy.screenshot(), use deterministic test data, and avoid capturing immediately after an action that has not completed. This matters especially when images are later used for visual comparison.
Understand the limit: Cypress captures but does not compare
The built-in cy.screenshot() command produces image files; it does not compare them with a baseline. For visual regression, add a separate comparison tool or service that fits your Cypress version, baseline-review process, and CI environment. Decide in advance how baseline updates are approved, where diffs are stored, and which dynamic regions are blacked out.
Rank #4
A reliable visual workflow separates three concerns:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →- State control: wait for the exact page state and use stable data.
- Capture policy: choose viewport, full-page, or runner capture and hide volatile fields.
- Comparison and review: let the external visual system calculate differences and provide an approval path.
Troubleshoot common screenshot problems
No image appears after a failed test
- Confirm you ran
cypress run, not onlycypress open. - Check that
screenshotOnRunFailureis not set tofalsein project configuration or screenshot defaults. - Look in the configured
screenshotsFolder, including the spec-based subfolders Cypress creates. - If the test is retried, inspect files with the attempt suffix instead of searching for one fixed filename.
Earlier screenshots disappeared
The usual cause is trashAssetsBeforeRuns: true. Cypress clears the folder contents before a run, including nested directories. Set the option to false for a workspace that must retain previous artifacts, and separate archived runs so names remain unambiguous.
The CI job says the folder is empty
Compare the artifact-upload path with screenshotsFolder in the active configuration. Also check whether the upload step runs after Cypress exits and whether a cleanup step removes the directory first. A successful test run may legitimately have no automatic screenshots because automatic capture is failure-only.
The image shows the wrong part of the page
Review the capture mode. fullPage, viewport, and runner produce different artifacts, and failure captures use runner capture. For a component or panel, use a deliberate viewport capture with clip rather than relying on the default.
Two captures overwrite or multiply unexpectedly
Cypress adds numeric suffixes to duplicate names by default. Use a unique name containing the state or attempt when you need every artifact, or set overwrite: true when one canonical file should be replaced.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Best Value
Visual diffs change between identical runs
First remove unstable inputs: wait for data and fonts, freeze or black out clocks and rotating content, and use repeatable fixtures. Then verify that the same capture mode, viewport, and clipping rectangle are used. Screenshot configuration cannot make an unstable application state deterministic by itself.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
For standalone URL captures outside a Cypress test, ScreenshotNeo provides a single screenshot API request. Before capture, it accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing result. Its MCP server supplies take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
See the ScreenshotNeo API documentation for the complete option list and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Every feature is available on every plan. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots, followed by Growth at $15 for 15,000, Pro at $39 for 60,000, Scale at $99 for 250,000, and Business at $249 for 1,000,000. Yearly billing gives two months free. Create a free ScreenshotNeo account to start with 1,000 screenshots a month and no card.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Frequently Asked Questions
Which Cypress setting controls cleanup of nested screenshot directories?
trashAssetsBeforeRuns controls the entire contents of the artifact folder, including nested files and folders; it is not limited to image files.
Why can a retry produce more than one screenshot for the same test?
Cypress can capture each failed retry attempt and adds an attempt suffix to the new filenames, so one test may legitimately have several failure artifacts.
What should a visual baseline review include besides the image itself?
Record the capture mode, viewport, test data, and any blackout selectors so reviewers can tell whether a difference represents a product change or an unstable capture.
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.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
