Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use cy.screenshot() for an explicit capture in a Cypress test. Cypress also saves a screenshot automatically when a test fails in cypress run; that failure capture is enabled by default, while cypress open does not take failure screenshots automatically.
The sections below show both workflows, where files are written, how to keep artifacts between runs, how to choose capture scope, and how to avoid unstable visual snapshots.
Choose the screenshot behavior you need
Manual screenshots with cy.screenshot()
A manual screenshot is part of your test flow and works in both interactive and headless workflows. Place the command after the state you want to document:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsdescribe('checkout', () => {
it('shows the payment form', () => {
cy.visit('/checkout');
cy.get('[data-cy=payment-form]').should('be.visible');
cy.screenshot('checkout-payment-form');
});
});The command captures the application under test. With no name, Cypress generates a name; with a name such as checkout-payment-form, the file is written relative to the screenshots folder and the spec path. A slash in the supplied name creates nested directories. The command and naming rules are documented in the cy.screenshot() API.
Automatic screenshots when a test fails
In cypress run, Cypress takes a screenshot of a failed test by default. This behavior is controlled by screenshotOnRunFailure. The automatic image uses the runner capture mode, which includes the browser viewport and Cypress’s Command Log, subject to the exceptions in the API documentation. Failure screenshots are not automatically taken while using cypress open.
Configure failure captures and the output folder
Set the behavior explicitly in your Cypress configuration so a team does not have to rely on implicit defaults. In a CommonJS configuration file:
const { defineConfig } = require('cypress');
module.exports = defineConfig({
screenshotOnRunFailure: true,
screenshotsFolder: 'cypress/screenshots'
});true is the documented default for failure screenshots, and cypress/screenshots is the documented default folder. Set screenshotOnRunFailure: false when failed tests should not produce images. The same settings are available through Cypress.Screenshot.defaults() for runtime defaults:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Cypress.Screenshot.defaults({
screenshotOnRunFailure: true
});Use the configuration reference for the configuration-file format used by your Cypress version: Cypress configuration.
Add a reliable manual capture to a test
- Navigate to the required state. Use
cy.visit()or the actions that lead to the screen. - Wait for a meaningful assertion. Check the heading, form, table, or other element that proves the UI update has completed.
- Capture after the assertion. Call
cy.screenshot()or provide a stable name. - Run the spec. Use
cypress openwhile developing orcypress runin CI.
describe('dashboard', () => {
it('captures the loaded dashboard', () => {
cy.visit('/dashboard');
cy.get('[data-cy=dashboard-title]')
.should('have.text', 'Dashboard');
cy.screenshot('dashboard/loaded');
});
});Because capture is asynchronous, the pixels can reflect a later render than the instant at which the command was queued. Cypress recommends stabilizing the page and confirming the update with a functional assertion before taking a visual snapshot; otherwise an intermediate render can create a false visual failure. See Visual testing in Cypress and the screenshot API.
Select the capture scope and useful options
The screenshot command supports three capture modes. Choose one according to what the artifact is meant to show.
| Capture mode | What it contains | Typical use |
|---|---|---|
viewport |
The current application viewport. | A focused assertion about the visible screen. |
fullPage |
The application from the top to the bottom of the page. | Long pages, marketing layouts, and complete-page review. |
runner |
The browser viewport with the Cypress runner and Command Log, with documented exceptions. | Failure diagnostics and debugging context. |
Pass options as the second argument. For example:
cy.screenshot('account-full-page', {
capture: 'fullPage',
blackout: ['[data-cy=credit-card-number]'],
overwrite: true
});The API also supports clipping to a region, selectors to black out, overwrite control, and onBeforeScreenshot and onAfterScreenshot callbacks. The exact option names and version-specific behavior are maintained in the cy.screenshot() reference. Shared defaults such as capture mode, scaling, animation or timer handling, and failure behavior can be set with Cypress.Screenshot.defaults().
Know where files go and when they disappear
Folder and naming
Unless you change it, Cypress writes screenshots to cypress/screenshots. A named screenshot is organized under the spec’s path; names containing path separators create nested folders. This makes names such as checkout/payment-form useful when several screens belong to one spec.
Cleanup before a run
Before cypress run, Cypress clears configured asset folders by default because trashAssetsBeforeRuns defaults to true. The cleanup includes files and nested subfolders, not just image files. To retain artifacts from earlier runs, configure:
const { defineConfig } = require('cypress');
module.exports = defineConfig({
trashAssetsBeforeRuns: false,
screenshotsFolder: 'artifacts/cypress/screenshots'
});Generated artifact directories are commonly added to .gitignore because Cypress recreates them. If your CI system collects screenshots, upload the folder after the test command and before the workspace is discarded.
Interactive mode, headless mode, and CI
cypress open is intended for interactive development: manual commands run when the test reaches them, but failed tests do not automatically create failure screenshots. cypress run is the headless workflow in which the default failure capture applies. You can therefore keep manual snapshots for both workflows and use screenshotOnRunFailure to control diagnostic images in CI.
Recommended Free Tools
When reviewing CI failures, preserve the screenshots folder as a build artifact. Cypress documentation also describes viewing CI screenshots through Cypress Cloud; availability and retention depend on how your project is configured. The relevant guidance is in Screenshots and videos.
Troubleshoot missing or misleading screenshots
No image appears after a failed test
- Cause: The test ran with
cypress open, where automatic failure capture is not enabled. - Fix: Run the spec with
cypress run, or add an explicitcy.screenshot()at the state you need.
Earlier screenshots vanished
- Cause:
trashAssetsBeforeRunsis stilltrue, so the asset folder was emptied at the start of the run. - Fix: Set it to
falsewhen retaining prior artifacts is required, and archive the folder in CI.
The file is in an unexpected directory
- Cause: Cypress resolves names relative to the screenshots folder and spec path; slash characters in a name create subfolders.
- Fix: Use a predictable name such as
profile/settings-loadedand inspect the configuredscreenshotsFolder.
The screenshot catches a loading spinner or old data
- Cause: Screenshot capture is asynchronous and the page was still rendering when the command was queued.
- Fix: Wait for a deterministic selector or state assertion, disable or complete the relevant animation, and then capture. Do not use an arbitrary delay as the only synchronization signal when a functional assertion is available.
Sensitive information is visible
- Cause: The captured viewport includes real account or payment data.
- Fix: Use test fixtures with non-sensitive values and the API’s
blackoutselectors or clipping options for fields that must not appear.
Full-page output is unexpectedly tall or incomplete
- Cause: The page may use lazy rendering, fixed-position elements, or content that changes during scrolling.
- Fix: Assert that important sections are present before capture, test the layout at the intended viewport, and use
viewportor a clipped element when a full-page image is not the right artifact.
Or skip the browser setup
If you need a screenshot of a URL rather than a Cypress test artifact, ScreenshotNeo provides a single HTTP request that returns PNG, JPEG, WebP, or PDF. Its cleanup steps accept cookie and consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, 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.
Start with this cURL request (the complete API details are in the ScreenshotNeo documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same call in Python:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)And in Node.js:
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(`HTTP ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Its feature set includes full-page and element captures, dark mode, device presets, custom viewports, retina scale, PDF controls, custom CSS and JavaScript, clicks before capture, selector hiding, selector or delay waits, network-idle waits, request and resource blocking, headers, cookies, user agents, Authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, an OpenAPI specification, and compatibility with parameter names used by other screenshot APIs.
Free tools Windows power users keep installed
One-click scans. No signup required.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; Growth is $15 for 15,000, Pro is $39 for 60,000, Scale is $99 for 250,000, and Business is $249 for 1,000,000. Yearly billing gives two months free, and every feature is included on every plan. Create a free ScreenshotNeo account to start with the 1,000 monthly screenshots.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.A practical enablement checklist
- Decide whether you need explicit test evidence, automatic failure diagnostics, or both.
- Keep
screenshotOnRunFailure: truefor default failure images incypress run. - Use
cy.screenshot(name)after a deterministic assertion. - Choose
viewport,fullPage, orrunnerintentionally. - Set
screenshotsFolderto the location your CI artifact step collects. - Set
trashAssetsBeforeRuns: falseonly when retaining previous runs is necessary. - Black out sensitive selectors and keep generated folders out of source control.
FAQ
Can Cypress screenshots be reviewed outside the machine that ran the test?
Yes. Upload the configured screenshots folder as a CI artifact, or use the CI screenshot viewing workflow described in Cypress Cloud documentation. The files remain ordinary image artifacts, so your CI provider can retain them according to its own policy.
Does a screenshot command freeze the application at the exact call site?
No. Cypress queues commands and capture is asynchronous, so the rendered pixels can come from a subsequent render. A state assertion immediately before the command is the dependable way to define what should be captured.
What is the simplest way to separate diagnostic and visual-review images?
Leave failure capture enabled for headless runs, and give manual snapshots a naming convention such as visual/<feature>/<state>. That keeps runner-based failure evidence distinct from application-only visual images.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Frequently Asked Questions
Can Cypress screenshots be reviewed outside the machine that ran the test?
Yes. Upload the configured screenshots folder as a CI artifact, or use the CI screenshot viewing workflow described in Cypress Cloud documentation. The files remain ordinary image artifacts, so your CI provider can retain them according to its own policy.
Does a screenshot command freeze the application at the exact call site?
No. Cypress queues commands and capture is asynchronous, so the rendered pixels can come from a subsequent render. A state assertion immediately before the command is the dependable way to define what should be captured.
What is the simplest way to separate diagnostic and visual-review images?
Leave failure capture enabled for headless runs, and give manual snapshots a naming convention such as visual/<feature>/<state>. That keeps runner-based failure evidence distinct from application-only visual images.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
