ScreenshotNeo

BlogHow-to

How to Capture Cypress Screenshots in CLI Mode

Run Cypress screenshots from the CLI, capture failures automatically, configure output and CI artifacts, and troubleshoot common screenshot issues.

By the ScreenshotNeo team30 September 20267 min read

How to Capture Cypress Screenshots in CLI Mode

Run npx cypress run from your project root. Add cy.screenshot() inside a test when you need an intentional image. During cypress run, Cypress also captures a screenshot automatically when a test fails unless screenshotOnRunFailure is disabled. By default, files are written to cypress/screenshots.

This guide covers intentional captures, failure screenshots, CLI flags, configuration, naming, cleanup, masking, CI artifacts and common errors.

1. Install Cypress and run it from the CLI

Install Cypress in the project that contains your tests:

npm install --save-dev cypress
npx cypress open

The interactive command creates the standard folder structure. Once a spec exists, run tests headlessly from the project root:

npx cypress run

Equivalent package-manager commands are:

yarn cypress run
pnpm cypress run
bunx cypress run

cypress run uses a headless browser by default. Add --headed when you need to watch the browser while diagnosing a problem.

2. Capture an intentional screenshot

Place cy.screenshot() after the page has reached the state you want to document. Assertions and explicit waits make the capture repeatable:

An intentional Cypress screenshot moves from a stable test state to an artifact file.
An intentional Cypress screenshot moves from a stable test state to an artifact file.
describe('checkout', () => {
  it('captures the ready checkout state', () => {
    cy.visit('/checkout')
    cy.get('[data-testid="checkout-form"]').should('be.visible')
    cy.screenshot('checkout-ready')
  })
})

The command is asynchronous and takes roughly 100 ms. The page can change during that interval, so issue it only after the relevant state is asserted and stable. See the official cy.screenshot() reference.

Run only the spec you are working on

npx cypress run --spec cypress/e2e/checkout.cy.js

You can pass more than one spec with a comma-separated list or a glob supported by your shell. Use --config-file to select a different Cypress configuration:

npx cypress run --config-file cypress.config.js
npx cypress run --headed --spec cypress/e2e/checkout.cy.js

3. Understand automatic screenshots on failure

When a test fails during cypress run, Cypress automatically captures a screenshot. Failure screenshots are not automatically taken during cypress open. The default configuration value for screenshotOnRunFailure is true.

Cypress captures evidence automatically when a test fails in CLI mode.
Cypress captures evidence automatically when a test fails in CLI mode.
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    screenshotOnRunFailure: true
  }
})

Disable failure images when they are too large for a particular pipeline:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    screenshotOnRunFailure: false
  }
})

You can also set the default through Cypress’s screenshot API:

Cypress.Screenshot.defaults({ screenshotOnRunFailure: false })

Automatic failure files include a (failed) suffix, which makes them easy to identify in an artifact directory.

4. Find, name and preserve the files

The default location is cypress/screenshots. A name passed to cy.screenshot() is relative to that directory and the spec path:

cy.screenshot('actions/login/clicking-login')

This creates nested folders beneath the screenshots directory. Use stable names that describe the state rather than timestamps when the files will be compared or uploaded by CI.

Before a cypress run, Cypress clears the screenshots folder by default. Set trashAssetsBeforeRuns: false if a run must retain images from an earlier run:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  trashAssetsBeforeRuns: false,
  e2e: {
    screenshotsFolder: 'artifacts/cypress-screenshots'
  }
})

The same cleanup setting affects videos and downloads. Confirm the configured folder in the run log before writing a CI upload step.

5. Select the capture scope and options

Cypress captures the application under test by default. Configure the scope per call:

cy.screenshot('viewport-only', { capture: 'viewport' })
cy.screenshot('full-page', { capture: 'fullPage' })
cy.screenshot('runner-view', { capture: 'runner' })
  • viewport captures the visible application viewport.
  • fullPage captures the complete scrollable page.
  • runner captures the complete Cypress browser view, including the Command Log.

Useful options include:

Option Use
blackout Hide matching selectors, such as account numbers or email addresses.
overwrite Allow a later capture to replace an existing file with the same name.
scale Scale the resulting image for smaller artifacts.
disableTimersAndAnimations Keep Cypress’s default animation and timer suppression, or set it to false when the animated state itself matters.
onBeforeScreenshot Run preparation code immediately before capture.
onAfterScreenshot Run cleanup or reporting code after the image is written.
cy.screenshot('account-page', {
  capture: 'fullPage',
  blackout: ['[data-sensitive]', '.private-email'],
  scale: true,
  overwrite: true
})

Cypress disables JavaScript timers and CSS animations by default while taking screenshots to reduce movement. If a transition must be visible, use disableTimersAndAnimations: false and wait for a deterministic point in that transition.

6. Make captures deterministic

Most inconsistent screenshots come from capturing too early. Build the test state in a predictable order:

  1. Visit the route.
  2. Set the viewport and any required cookies or local storage.
  3. Wait for a meaningful selector, not an arbitrary long delay.
  4. Assert text, data or visibility.
  5. Hide volatile content or mask secrets.
  6. Capture the screenshot.
it('captures the dashboard', () => {
  cy.viewport(1440, 900)
  cy.visit('/dashboard')
  cy.get('[data-testid="dashboard"]', { timeout: 15000 }).should('be.visible')
  cy.get('[data-testid="loading"]').should('not.exist')
  cy.screenshot('dashboard-ready', {
    blackout: ['[data-testid="current-time"]']
  })
})

Prefer application-level readiness signals over cy.wait(5000). A fixed delay can be too short on a busy CI runner and unnecessarily slow on a fast one.

7. Publish screenshots from CI

Upload the screenshots directory as a build artifact after the Cypress command, even when tests fail. The exact YAML differs by CI provider, but the path is the same:

npx cypress run
# artifact path: cypress/screenshots

If you configured screenshotsFolder, upload that path instead. Keep the upload step configured to run after failures so automatic failure images remain available. Cypress Cloud can also display screenshots produced by cy.screenshot() and failure captures; provider-specific artifact instructions belong in your CI system’s documentation.

8. Common problems and fixes

Symptom Cause Fix
No screenshot appears The test never reached cy.screenshot(), or it was run with cypress open and you expected an automatic failure image. Run npx cypress run, inspect the command log, and add an intentional capture.
Images disappear before each run Cypress clears screenshot assets before a run. Set trashAssetsBeforeRuns: false or copy artifacts elsewhere before the next run.
Wrong directory is uploaded screenshotsFolder was overridden. Check cypress.config.js and upload the configured path.
Capture shows a spinner or blank panel The command ran before the application was ready. Assert a ready selector and the absence of loading UI before taking the screenshot.
Secret data is visible Sensitive elements were not masked. Use blackout selectors or render test-safe data.
Duplicate names overwrite files The same name was reused with overwrite enabled. Use nested, state-based names or remove overwrite.
Full-page image is unexpectedly tall capture: 'fullPage' includes the entire scrollable document. Use viewport for a fold-only image, or design the page and artifact limits around full-page output.
Animation differs between runs The page changes during the asynchronous capture window. Wait for a stable state and keep animation suppression enabled unless animation is the subject of the test.

9. Performance, reliability and storage

  • Run a focused spec with --spec while iterating; run the complete suite in CI.
  • Use viewport captures when a full document is unnecessary. Full-page images consume more disk space and take longer to inspect and upload.
  • Capture intentional checkpoints only where the image answers a debugging or review question. Failure screenshots already provide evidence for unexpected states.
  • Use stable selectors and readiness assertions to reduce retries caused by timing races.
  • Keep screenshots as CI artifacts with an appropriate retention period. Since Cypress clears them before a new run by default, retention is controlled by your artifact system after upload.
  • Mask personal or secret data before uploading artifacts.

10. Or skip the browser setup

If you need a screenshot of a URL rather than a screenshot tied to a Cypress test, ScreenshotNeo provides a single HTTP request. Its capture service removes cookie and consent banners, newsletter popups and chat widgets before the shot. Bot checks, blank pages and failed loads are not billed, and response headers identify the page verdict and billing result. The service also offers an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.

See the ScreenshotNeo API documentation for all options.

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}`);

There are 1,000 screenshots per month on the free plan with no card required. Paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.

FAQ

Does Cypress take screenshots when I run cypress open?

Not automatically on failure. Automatic failure screenshots apply to cypress run; add cy.screenshot() for an intentional capture.

Can I capture the Cypress Command Log?

Yes. Use capture: 'runner' instead of the default application capture.

What is the default screenshot format?

Cypress writes PNG screenshot files in the configured screenshots folder.

How do I keep screenshots from previous runs?

Set trashAssetsBeforeRuns: false, or copy and upload the directory before starting another run.

Should I use a fixed wait before taking a screenshot?

Use a readiness selector and assertions whenever possible. Fixed waits are less reliable across machines.

Primary references: Cypress screenshot command, Cypress configuration, and Cypress CI and Cloud guidance.