How to Disable Custom or Embedded Screenshots in Cypress
Turn off Cypress failure screenshots, remove explicit `cy.screenshot()` calls, or control what the captured image includes. Learn which setting handles each case.

To disable Cypress’s automatic screenshots when tests fail during cypress run, set screenshotOnRunFailure: false in your Cypress configuration. This does not disable explicit cy.screenshot() calls in your tests, change what an image captures, or turn off Cypress Cloud recording; those need separate changes.
1. Disable automatic failure screenshots
Cypress takes screenshots on test failure during cypress run by default. Add screenshotOnRunFailure: false to your configuration to turn off that behavior. It applies to failure screenshots in test runs; automatic failure screenshots are not taken during cypress open.

const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotOnRunFailure: false,
})
Place this in the project’s Cypress configuration file, such as cypress.config.js. If your configuration already contains other options, add the property to the existing config object rather than replacing it.
Cypress documents an API alternative for setting screenshot defaults. Put it in a support file that is loaded by your specs:
Cypress.Screenshot.defaults({
screenshotOnRunFailure: false,
})
Use one clear source of configuration where possible. If the setting appears in more than one place, check the loaded support file and project configuration when diagnosing unexpected behavior.
2. Remove or control explicit screenshots
cy.screenshot() is an explicit command authored in a spec, helper, or custom command. The failure-screenshot setting does not suppress it. Search your test code for calls and remove them, or condition the call on the circumstances where you still need an image.
// Remove this line if the test should never take this custom screenshot:
// cy.screenshot('checkout-state')
// Or keep it only when a condition makes it useful:
if (Cypress.env('SAVE_DEBUG_SCREENSHOTS')) {
cy.screenshot('checkout-state')
}
Search specs, support files, helper modules, and custom commands. A screenshot may be invoked indirectly by a shared helper, so searching only the currently failing spec can miss the source.
3. Hide runner content without disabling capture
If by “embedded screenshot” you mean that the Cypress runner or Command Log appears in the image, change the capture area. Set the screenshot default to capture: 'viewport' to capture the application viewport rather than a runner capture:
Cypress.Screenshot.defaults({
capture: 'viewport',
})
This changes what part of the browser is captured. It does not disable automatic failure screenshots or explicit cy.screenshot() calls. Combine it with screenshotOnRunFailure: false only if you also want to suppress automatic failure images.
4. Treat Cypress Cloud artifacts separately
Local screenshot configuration and Cypress Cloud run data are separate concerns. A run invoked with cypress run --record can create Cloud artifacts. If your goal is to stop data being available in Cloud or to limit what it contains, review the project’s Cloud controls for screenshot masking, data capture, and Test Replay. Changing screenshotOnRunFailure controls local automatic failure screenshots; do not assume it alone changes every recorded Cloud artifact.
5. Know what storage settings do
screenshotsFolderchanges where Cypress stores screenshot files. Its documented default iscypress/screenshots; changing the folder does not disable capture.trashAssetsBeforeRunsclears the relevant folder contents before acypress runwhen enabled. Cleanup is not a capture switch: screenshots can still be created during that run.
Use these settings to manage location and cleanup, not as substitutes for disabling capture.
6. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| A screenshot still appears when a test fails | The run is using a different config, or the option was added outside the config object. | Confirm the configuration file used by the run contains screenshotOnRunFailure: false. Check for a support-file default that also sets screenshot behavior. |
| Screenshots still appear after disabling failure captures | A spec, helper, or custom command explicitly calls cy.screenshot(). |
Search the project for cy.screenshot, then remove or condition the calls you no longer want. |
| The image still contains Cypress runner or Command Log content | The capture area has not been changed. | Set capture: 'viewport' in screenshot defaults. This changes the captured area, not whether screenshots are taken. |
| The screenshot folder is empty at the start but files appear after the run | Folder cleanup ran before capture; it does not prevent new captures. | Disable automatic failure captures and remove explicit screenshot calls as needed. |
| Cloud still shows run data or artifacts | Cloud recording and local screenshot settings are separate. | Review Cloud project controls for masking, data capture, and Test Replay, and check how the run was recorded. |
| Cypress does not recognize the setting | The project may use a different Cypress version or configuration format. | Check the configuration reference for the installed version and verify the file is loaded by the command you run. |
7. Performance, reliability, and cost considerations
Disabling failure screenshots avoids producing those local image artifacts, which can simplify artifact handling. Keep explicit screenshots that provide useful debugging evidence, or condition them so they run only when wanted. If a failure image is important to your workflow, turning it off removes that automatic visual record; choose the setting based on how your team investigates failures.
Folder cleanup affects retained files, not capture work during the run. Cloud recording and local capture should be reviewed independently when managing stored artifacts or recorded data.
8. Or skip the browser setup
If your goal is to capture a website outside Cypress, ScreenshotNeo is a website screenshot API and MCP server. A single request can return an image or PDF; see the API documentation.

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}`);
- Cookie banners are accepted and removed before the shot; 60+ known consent platforms, newsletter popups, and chat widgets can be removed. Each step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
- An MCP server lets AI agents use
take_screenshot,get_page_info, andcapture_pdf. - 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for 1,000 free screenshots a month, with no card required.
9. FAQ
Does this disable screenshots in Cypress open?
The setting concerns automatic failure screenshots during cypress run. Cypress does not take those automatic failure screenshots during cypress open.
Will it stop screenshots that a test explicitly requests?
No. Remove or condition the test’s cy.screenshot() call.
Does changing screenshotsFolder disable screenshots?
No. It changes the output location. Use screenshotOnRunFailure: false for automatic failure screenshots and edit explicit calls separately.
Does disabling local failure screenshots disable Cypress Cloud recording?
No. Review Cloud recording and project controls separately from local screenshot configuration.


