ScreenshotNeo

BlogHow-to

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.

By the ScreenshotNeo team30 September 20266 min read

Disable Screenshot Generation When Creating a Cypress Report

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:

The Cypress report continues while the automatic failure-screenshot branch is disabled.
The Cypress report continues while the automatic failure-screenshot branch is disabled.
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 for cy.screenshot and gate or remove those calls.
  • Cause: The option was placed under the wrong testing type.
    Fix: Put it under e2e for end-to-end runs or component for component runs.
  • Cause: CI overrides project configuration.
    Fix: Inspect the command for --config values 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 confirm trashAssetsBeforeRuns behavior, 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.

A capture service can remove common overlays before producing a report-ready image.
A capture service can remove common overlays before producing a report-ready image.

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.screenshotOnRunFailure or component.screenshotOnRunFailure to false.
  • 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.