How to Take Screenshots on Test Failure in Cypress

Cypress automatically captures a screenshot when a test fails during cypress run, including in CI. The feature is enabled by default with screenshotOnRunFailure: true, and screenshots are saved under cypress/screenshots unless you change screenshotsFolder. Automatic failure screenshots are not taken in cypress open. Use cy.screenshot() when you want a deliberate capture at a specific point in a test.

Configure automatic failure screenshots

In a current Cypress configuration file, set the relevant options in defineConfig. The example below uses the default behavior and changes the output directory:

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    // Keep or omit this setting to use the default: true.
    screenshotOnRunFailure: true,
    screenshotsFolder: 'artifacts/cypress/screenshots',
  },
})

Use the configuration structure appropriate to your project and Cypress version. screenshotsFolder controls screenshots created by both failure capture and cy.screenshot(). Cypress documents screenshotOnRunFailure as available since Cypress 4.1.0; avoid the obsolete screenshotOnHeadlessFailure setting. See the official Cypress configuration reference and screenshot and video guide.

Disable automatic failure captures

To stop Cypress from saving screenshots automatically when tests fail in cypress run, set the option to false:

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    screenshotOnRunFailure: false,
  },
})

The screenshot API also documents changing the default through Cypress.Screenshot.defaults(). Prefer configuration when you want a project-level setting that is easy to see and maintain. See Cypress.Screenshot.

Take a screenshot at a specific point in a test

Automatic failure captures help diagnose a failure, but sometimes you need a checkpoint before the failure, such as after a form is filled or a menu is opened. Use cy.screenshot() in the test:

describe('checkout', () => {
  it('shows the order summary before payment', () => {
    cy.visit('/checkout')
    cy.get('[name="email"]').type('dev@example.com')
    cy.get('[data-testid="continue"]').click()

    cy.get('[data-testid="order-summary"]').should('be.visible')
    cy.screenshot('checkout-order-summary')
  })
})

To capture automatically after an assertion fails, Cypress’s built-in run failure behavior is usually the simpler choice. A manually placed screenshot runs only if execution reaches that command. For command syntax, naming, capture modes and options, consult the cy.screenshot() API.

Choose a capture mode

The documented modes for manual screenshots are viewport, fullPage and runner. A manual call can select a mode, for example:

cy.screenshot('page-checkpoint', { capture: 'fullPage' })

viewport captures the browser viewport.
fullPage captures the full page.
runner captures the Cypress runner view.

Automatic failure captures are coerced to runner capture. They include the browser viewport and Cypress Command Log, subject to Test Replay behavior when the Runner UI is hidden. That makes them useful for debugging, but they are not necessarily equivalent to a clean, full-page production-page image. See the screenshot command documentation and screenshot API documentation.

Where does Cypress save screenshots?

By default, Cypress writes screenshots to cypress/screenshots. Set screenshotsFolder in configuration to choose another location, such as artifacts/cypress/screenshots. Screenshot paths are organized relative to the spec file. A failure image uses the test name with a (failed) suffix. If a name would collide with an existing screenshot, Cypress can add a numbered suffix unless overwrite behavior is selected.

Generated screenshot, video and download directories are commonly excluded from source control because test runs regenerate them. For CI, configure the CI provider to preserve the screenshot directory as an artifact, or use Cypress Cloud to view screenshots. Cypress discusses these workflows in Writing and organizing Cypress tests.

Retries and CI artifacts

When test retries are enabled, Cypress can capture a screenshot for each failed attempt. Attempt numbers distinguish the images. A test that fails once and then passes may therefore still have a failure screenshot. Make your artifact collection preserve multiple files per test rather than assuming one image per test. Cypress explains retry behavior in its test retries guide.

CI checklist

Run the tests with cypress run; automatic failure capture does not run in cypress open.
Keep screenshotOnRunFailure enabled unless you intentionally want to turn captures off.
Confirm the configured screenshotsFolder matches the path your CI artifact step collects.
Preserve retry screenshots and numbered duplicate filenames.
Check the CI artifact or Cypress Cloud after a failed run.

Timing, performance and reliability

Cypress screenshot capture is asynchronous. The application can change between the failure and when the screenshot is written, so treat the image as diagnostic evidence rather than a guaranteed frame-perfect record of the exact failure instant. Animations, unfinished rendering and in-flight data updates can also produce an intermediate image. For intentional visual checkpoints, wait for the page and the relevant content to stabilize before calling cy.screenshot(). Cypress covers this limitation in its visual testing guide.

Failure screenshots consume storage and add files to CI artifacts, especially when retries produce multiple images. Choose an artifact retention policy that fits your debugging needs. Cypress does not provide a cost figure for screenshot capture in the cited documentation, so costs depend on your CI storage and artifact policies.

Troubleshooting

Symptom	Likely cause	What to do
No automatic screenshot appears	The test ran in `cypress open`, where failure screenshots are not automatic, or `screenshotOnRunFailure` is false.	Run with `cypress run` and check the effective Cypress configuration.
The screenshot is in an unexpected directory	`screenshotsFolder` points somewhere other than the default.	Check the project configuration and collect that directory in CI.
The CI job has no screenshot artifact	The provider is collecting the wrong path, or artifacts are not configured to persist after failure.	Match the artifact path to `screenshotsFolder` and ensure the artifact step runs when tests fail.
There are several screenshots for one test	Retries captured failed attempts, or a duplicate filename required a suffix.	Keep all attempt files when diagnosing retries; check the test retry settings and screenshot naming.
The image shows a later or transitional page state	Capture is asynchronous, or rendering, animation or data updates were still underway.	Use the automatic image as diagnostic context. For a deliberate checkpoint, wait for a stable state and then call `cy.screenshot()`.
A manual screenshot is missing	The test failed or stopped before execution reached the screenshot command.	Use automatic run failure capture for failures, and put manual checkpoints after the state you need to inspect.

Or skip the browser setup

If you need screenshots of a live website outside a Cypress test run, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF; it does not replace Cypress’s test failure capture inside your test runner. See the ScreenshotNeo API documentation for options and configuration.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, popups and chat widgets before the shot. Bot checks, blank pages and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does Cypress take screenshots when a test fails in cypress open?

No. Automatic failure screenshots apply to cypress run. In interactive mode, add cy.screenshot() where you want a capture.

Can I change the name of an automatic failure screenshot?

Cypress derives the failure screenshot name from the test name and adds a failure suffix. Use cy.screenshot('name') when you need a chosen name for a manual checkpoint.

Are Cypress failure screenshots visual regression snapshots?

They are diagnostic captures. Cypress documents visual testing as a separate workflow; use a deliberate, stable checkpoint for visual comparisons.

Cypress behavior and links in this guide are based on the official Cypress documentation checked on October 3, 2026.