Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Run Cypress with cypress run. Cypress automatically captures a screenshot when a test fails in run mode, including CI, and the default setting is enabled. The image is normally written to cypress/screenshots. Interactive cypress open does not take failure screenshots automatically; use cy.screenshot() there when you need a deliberate capture.
Automatic failure screenshots: the shortest path
From your project directory, run:
npx cypress runWhen a test fails, Cypress creates a screenshot for that failure. The default destination is cypress/screenshots, alongside any screenshots created manually with cy.screenshot(). This behavior is available without adding a plugin or writing screenshot code.
If Cypress is installed as a project script, the equivalent command may be:
npm run cypress -- runThe important distinction is the run mode, not the exact package-manager wrapper. A headed run (npx cypress run --headed) still uses run-mode failure capture.
Recommended Free Tools
Configure the behavior explicitly
Keep automatic screenshots enabled
screenshotOnRunFailure defaults to true. You can make that choice visible in Cypress configuration:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotOnRunFailure: true,
screenshotsFolder: 'cypress/screenshots',
trashAssetsBeforeRuns: false,
})The explicit folder above is also the default. Omitting these properties uses Cypress’s documented defaults.
Disable automatic captures
Set the option to false when failure images are not wanted:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotOnRunFailure: false,
})You can set the same default through the screenshot API:
Cypress.Screenshot.defaults({ screenshotOnRunFailure: false })Use one consistent configuration location in a project so a later config file or support file does not silently re-enable or disable the setting.
Where Cypress saves the files
Default and custom folders
Failure screenshots and manual captures are placed in cypress/screenshots unless you change screenshotsFolder:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotsFolder: 'artifacts/cypress/screenshots',
})Use a path that your CI system can collect. Cypress creates files beneath that directory using the spec and test names, so long names or characters that are awkward on your operating system can produce less convenient paths.
Why old images disappear
Before cypress run, Cypress clears the downloads, screenshots, and videos folders by default, including nested files and directories. This prevents an old failure from being mistaken for the current run. To preserve existing contents, set:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteconst { defineConfig } = require('cypress')
module.exports = defineConfig({
trashAssetsBeforeRuns: false,
})Preserving files is useful when several commands contribute artifacts to one directory, but it also means your CI upload can contain results from earlier runs. Prefer a run-specific workspace or cleanup step when retention and unambiguous reporting both matter.
Automatic failure capture versus cy.screenshot()
Use automatic capture for unexpected failures
The automatic image is designed to show the failed test in the Cypress runner. Cypress coerces automatic failure captures to the runner capture mode, which includes the browser viewport and Command Log. It is evidence of the failure context rather than a clean, application-only image.
Use a manual capture for a known checkpoint
Add cy.screenshot() when you want a screenshot at a specific point, whether or not the test eventually fails:
it('shows the completed checkout', () => {
cy.visit('/checkout')
cy.get('[data-cy=place-order]').click()
cy.get('[data-cy=confirmation]').should('be.visible')
cy.screenshot('checkout-confirmation')
})You can pass options such as a filename or capture mode. Manual screenshots follow your chosen capture settings; they are separate from Cypress’s automatic failure image.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsAccount for capture timing
Screenshot capture is asynchronous and takes roughly 100 ms according to Cypress documentation. A failure image may therefore show a state very close to, but not exactly, the instant a timed-out command failed. When diagnosing a transient UI change, combine the image with the Command Log, test steps, and (if enabled) video.
Why cypress open does not save a failure image
cypress open is interactive mode. Cypress does not automatically take failure screenshots there, even when screenshotOnRunFailure is true. Add a manual command at the point you want to inspect:
cy.screenshot('debug-state', { capture: 'runner' })For repeatable failure evidence, rerun the spec with cypress run. You can still use open mode to explore and then keep a deliberate screenshot command in the test.
Retries and multiple failure images
Retries are disabled by default. If you configure retries, Cypress can retain screenshots for failed attempts. The filenames identify retry attempts with an (attempt n) suffix, so one test can produce several images. Treat each attempt as separate evidence: the first attempt may expose a setup race that disappears on a retry, while the final attempt may show the persistent defect.
Free tools Windows power users keep installed
One-click scans. No signup required.
When reviewing artifacts, sort by spec, test name, and attempt suffix rather than opening only the last file. If your CI system applies its own artifact renaming, preserve the original path or include the attempt number in the resulting name.
CI: retain and inspect the screenshots
- Run the tests with
cypress runin the job. - Keep the configured
screenshotsFolderinside the workspace that remains after the test command exits. - Configure your CI provider to upload that directory as a job artifact, including files from failed jobs.
- If you record runs in Cypress Cloud, use its documented run and screenshot views as another way to review captured evidence.
Do not rely on a local developer’s filesystem in CI. A successful artifact-upload step is separate from Cypress’s screenshot creation; a missing image in the CI interface can mean upload configuration failed even though Cypress wrote the file correctly.
Rank #4
Optional video for the sequence before failure
Video is independent of screenshots and disabled by default. Set video: true to record a video per spec during cypress run:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
video: true,
})A screenshot gives a compact point-in-time view and is cheaper to inspect; video can reveal the interaction sequence, animation, or navigation that led there. Enabling video is not required for automatic failure screenshots, and it creates an additional artifact that your CI retention policy must handle.
Troubleshooting checklist
No screenshot after a failed test
- Check the command: confirm the job used
cypress run, not onlycypress open. - Check the setting: search configuration and support code for
screenshotOnRunFailure: falseorCypress.Screenshot.defaults({ screenshotOnRunFailure: false }). - Check the path: inspect the configured
screenshotsFolder, not just the default directory. - Check the exit sequence: make sure a cleanup script did not delete artifacts before CI uploaded them.
The folder is empty at the start of a run
trashAssetsBeforeRuns defaults to true. Set it to false when existing files must survive, or copy the previous run elsewhere before starting.
The image does not show the exact failed state
Automatic captures use the runner view and screenshotting is asynchronous. Add a manual checkpoint before a risky command, increase assertions around the state you need to observe, or enable video for sequence-level context.
There are several images for one test
Inspect retry attempts and their (attempt n) suffixes. Multiple files are expected when retries retain failed-attempt screenshots.
Local files exist but CI shows none
Verify that the artifact step runs even when tests fail, that its path matches screenshotsFolder, and that the job does not delete the directory afterward. Cypress Cloud is an alternative review location for recorded runs.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
Or skip the browser setup
If your goal is a screenshot service rather than Cypress’s own failure artifact, ScreenshotNeo returns an image or PDF from one GET request. It accepts cookies/consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and whether it was billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import 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)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for the remaining capture options, including full-page and element shots, device presets, custom CSS and JavaScript, waits, request blocking, authentication headers, caching, signed links, asynchronous jobs, bulk capture, and PDF output. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Frequently Asked Questions
Does Cypress take a screenshot for a passing test?
Not automatically. Automatic capture is tied to test failure in run mode; use cy.screenshot() for a passing-test checkpoint.
Can I change the screenshot image format?
The documented configuration here controls when and where Cypress captures. The supplied Cypress material does not establish a format setting, so choose format only where your installed Cypress version documents it.
Will a screenshot prove why a test failed?
It records visual context, not every cause. Pair it with the Command Log, test output, and, when useful, video or network diagnostics.
The Bottom Line
Use cypress run, leave screenshotOnRunFailure enabled, collect cypress/screenshots (or your configured folder), and account for cleanup and retry suffixes in CI.
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.
