Disable Screenshot Generation When Creating a Cypress Report
Set screenshotOnRunFailure to false to stop Cypress failure screenshots while keeping reports and explicit screenshots under your control.

To disable Cypress screenshots created automatically when a test fails, set screenshotOnRunFailure: false in your Cypress configuration. Cypress enables this option by default during cypress run. The setting affects automatic failure screenshots; it does not remove screenshots explicitly requested with cy.screenshot().
1. Disable automatic failure screenshots
For a TypeScript project using the current Cypress configuration format, edit cypress.config.ts:

import { defineConfig } from 'cypress'
export default defineConfig({
e2e: {
screenshotOnRunFailure: false,
},
})
This keeps Cypress test execution and report generation enabled while preventing the automatic image written after a failed test.
CommonJS JavaScript configuration
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
screenshotOnRunFailure: false,
},
})
Component testing configuration
If the screenshots come from component tests, put the option in the component block instead:
import { defineConfig } from 'cypress'
export default defineConfig({
component: {
devServer: {
framework: 'react',
bundler: 'vite',
},
screenshotOnRunFailure: false,
},
})
Use the testing type that actually produces the artifact. A setting under e2e does not configure a separate component runner.
2. Set the option with Cypress.Screenshot.defaults()
Cypress also documents the screenshot API form:
Cypress.Screenshot.defaults({
screenshotOnRunFailure: false,
})
Place this in support code that is loaded before tests run. Project configuration is usually easier to audit because the behavior is visible in one configuration file. The documented API and configuration approaches control the same automatic failure capture behavior.
See the Cypress screenshot API and Cypress configuration reference for version-specific details.
3. Disable it for one CI command
For a one-off run, pass the configuration value through the Cypress CLI:
npx cypress run --config screenshotOnRunFailure=false
This is useful when a CI job should avoid image artifacts but local debugging should keep them. When combining values, use the syntax required by your shell and CI provider, for example:
npx cypress run --config screenshotOnRunFailure=false,video=false
Keep the permanent setting in source control when the policy should apply to every developer and pipeline.
4. Understand what this setting does not disable
| Behavior | Controlled by | Effect of screenshotOnRunFailure: false |
|---|---|---|
Screenshot automatically captured after a failed test in cypress run |
screenshotOnRunFailure |
Disabled |
| Screenshot explicitly requested by a test | cy.screenshot() |
Still enabled |
| Screenshot location | screenshotsFolder |
Unchanged |
| Cleanup before a run | trashAssetsBeforeRuns |
Unchanged |
| Video recording | video |
Unchanged |
| Reporter output | reporter and reporter options |
Unchanged |
Explicit screenshots still run
Search your tests, support files and plugins for explicit calls:
cy.screenshot('checkout-state')
Remove, guard or configure those calls separately if the requirement is to produce no screenshots at all. A useful conditional pattern is:
if (Cypress.env('SAVE_SCREENSHOTS')) {
cy.screenshot('checkout-state')
}
Run with --env SAVE_SCREENSHOTS=true only when you need the diagnostic image.
5. Keep reporters, folders and videos separate
Reporters do not control failure screenshots
Mocha reporters and custom Cypress reporters format test results. Changing reporter does not turn failure screenshots on or off. Configure the reporter for result output and configure screenshotOnRunFailure independently.
Changing the screenshot directory
Cypress writes screenshots to cypress/screenshots by default. You can move them, but this does not disable capture:
import { defineConfig } from 'cypress'
export default defineConfig({
screenshotsFolder: 'artifacts/cypress-screenshots',
e2e: {
screenshotOnRunFailure: false,
},
})
Cleaning assets before each run
trashAssetsBeforeRuns defaults to true and clears configured downloads, screenshots and videos before cypress run, including nested directories. Cleanup is not the same as disabling capture: a failed test can still create a new screenshot unless screenshotOnRunFailure is false.
Video is independent
Cypress documents video as false by default. If video is enabled, disabling failure screenshots does not change video recording:
export default defineConfig({
video: false,
e2e: {
screenshotOnRunFailure: false,
},
})
6. CI and Cypress Cloud considerations
Use the local configuration switch to control automatic failure-image creation. Cypress Cloud data and runner-display controls are separate concerns. Options such as --no-runner-ui and command logging settings affect what is visible in captures; they do not replace screenshotOnRunFailure: false.
Before changing a pipeline, check whether another job expects files under cypress/screenshots. If a report publisher uploads that directory, update the publisher only after confirming that explicit screenshots are no longer required.
7. Troubleshooting
Screenshots still appear after setting the option
- Cause: A test calls
cy.screenshot()directly.
Fix: Search the repository and support files forcy.screenshotand gate or remove those calls. - Cause: The option was placed under the wrong testing type.
Fix: Put it undere2efor end-to-end runs orcomponentfor component runs. - Cause: CI overrides project configuration.
Fix: Inspect the command for--configvalues and print the effective CI command in job logs. - Cause: You are looking at files from a previous run.
Fix: Remove the artifact directory or confirmtrashAssetsBeforeRunsbehavior, then run again.
The config option is reported as unknown
Check the Cypress version and configuration shape used by the project. Older projects may use a legacy configuration file or a different testing-type layout. Compare the installed version with the current configuration reference, then move the option into the supported block.
The report is missing screenshots that were expected
Disabling automatic failure screenshots removes an artifact that some report integrations attach to failed tests. Keep explicit, conditional cy.screenshot() calls for the cases your team wants to publish, or leave automatic capture enabled for diagnostic CI jobs.
Disk usage remains high
Failure screenshots may be disabled while videos, downloads, browser recordings or explicit screenshots continue to consume storage. Review each artifact directory and set retention in the CI system as well as Cypress configuration.
8. Performance, reliability and cost notes
- Performance: Avoiding automatic PNG creation and upload can reduce artifact work after failures, especially in large parallel runs. The test itself still runs and the reporter still writes its result.
- Reliability: A configuration value in source control gives every run the same default. A CLI override is useful for exceptional jobs but can be lost when a pipeline command changes.
- Debugging: Failure screenshots are valuable when diagnosing visual state. Consider disabling them only for jobs where storage, privacy or artifact volume matters, and retain an opt-in diagnostic job.
- Cost: Local screenshots have no Cypress API charge, but CI storage, artifact retention and upload time can cost money. Removing unused images reduces those operational costs; it does not change reporter or test execution costs.
9. Or skip the browser setup
If your workflow needs screenshots for a report or audit rather than Cypress’s own failure artifact, ScreenshotNeo provides a single HTTP request. It accepts the cookie or consent banner like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets before capture, and lets you turn each step off. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.

See the ScreenshotNeo API documentation for all options, including full-page or element capture, device presets, custom CSS and JavaScript, waits, request blocking, cookies, headers, geolocation, PDFs, caching, signed links, async jobs and bulk capture.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webp
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)
const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://stripe.com',
})
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`)
ScreenshotNeo also includes an MCP server so Claude, Cursor and other MCP clients can use take_screenshot, get_page_info and capture_pdf. There are 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
10. Checklist
- Set
e2e.screenshotOnRunFailureorcomponent.screenshotOnRunFailuretofalse. - Check for explicit
cy.screenshot()calls. - Keep reporter, video, folder and cleanup settings separate.
- Check CI command-line overrides.
- Confirm whether report publishing expects screenshot files.
- Run one failure case and inspect the artifact directories.
FAQ
Is the default true?
Yes. Cypress’s current configuration reference lists screenshotOnRunFailure as true by default.
Does this disable screenshots in interactive cypress open?
The option is documented for automatic screenshots when a test fails during cypress run. Explicit screenshot commands remain a separate mechanism.
Can I disable screenshots only in CI?
Yes. Use npx cypress run --config screenshotOnRunFailure=false in the CI job while leaving local configuration unchanged.
Will my JUnit or HTML report stop working?
No. Reporters produce test-result output independently. Only the automatic failure-image artifact is disabled.


