The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Call cy.screenshot() at the point in your test where you want an image. Cypress saves it under cypress/screenshots by default. Choose capture: 'viewport', 'fullPage', or 'runner' to control what appears in the image. In cypress run, Cypress also captures screenshots automatically when tests fail; it does not do this automatically in cypress open.
Take a screenshot at a specific point in a test
Use cy.screenshot() after the page or state you want to inspect has been reached. It is a Cypress command, so it runs in the test’s command sequence rather than immediately like a synchronous image-save call.
cy.visit('/checkout')
cy.get('[data-cy=place-order]').should('be.visible')
cy.screenshot('checkout-ready')The optional first argument is a filename. Cypress saves the image in its configured screenshots folder and a directory associated with the spec. The name above therefore identifies the state in the output without requiring you to construct an absolute path.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
You can also capture a selected element by chaining from its query:
cy.get('.post').screenshot('post-card')This is useful when a whole-page image would obscure a small component’s layout. Screenshots are generated artifacts; Cypress recommends excluding generated asset folders from source control. If another part of your test tooling needs the resolved saved path, use screenshot callbacks or the after:screenshot Node event.
Choose the capture area
The capture option determines whether the image shows the current visible area, the full application page, or the Cypress runner around it.
| Option | What it captures | Use it when |
|---|---|---|
viewport |
The application’s current browser viewport. | You want to inspect what a user can currently see. |
fullPage |
The application from top to bottom, using scrolling and stitched captures. | You need a long-page overview rather than only the visible fold. |
runner |
The browser viewport together with the Cypress Command Log. | The surrounding test commands help explain a failure. |
cy.screenshot('visible-area', { capture: 'viewport' })
cy.screenshot('whole-page', { capture: 'fullPage' })
cy.screenshot('debug-context', { capture: 'runner' })Automatic screenshots taken for failures use runner capture. For a full-page image, inspect the result if the site has fixed or sticky elements: because Cypress scrolls and stitches captures, those elements may appear differently from how they behave in one live viewport.
Recommended Free Tools
Crop, cover, or stabilize the image
Crop to a pixel rectangle
Use clip when the target is a specific rectangular region. Its rectangle is expressed in pixels; choose dimensions and coordinates that fit the capture you intend to make.
cy.screenshot('cropped', {
clip: { x: 0, y: 0, width: 800, height: 600 }
})Black out sensitive or distracting regions
For viewport captures, the blackout option accepts selectors whose matching elements should be covered in the image.
cy.screenshot('account-page', {
capture: 'viewport',
blackout: ['[data-cy=account-email]', '.private-value']
})Blackout is ignored for runner captures, so do not rely on it to conceal matching content in an image that includes the Cypress runner.
Reduce animation and timer variation
Cypress disables timers and CSS animations by default during screenshot capture. This helps avoid images that differ only because an animation or timer advanced while the capture was taking place. Shared screenshot defaults can be set with Cypress.Screenshot.defaults() in a support file, so repeated choices do not need to be passed on every individual call.
Set a filename and manage duplicate captures
A filename can include a path to create nested folders under the screenshots folder. If Cypress encounters an existing screenshot with the same name, it adds a numbered suffix by default. Set overwrite: true when the intended behavior is to replace a previous image instead.
cy.screenshot('checkout/confirmation', { overwrite: true })Use a stable, descriptive name when the image is an artifact for later diagnosis. If you need to preserve multiple states from one test, give each capture a distinct name rather than relying on numbered duplicates whose order may be less obvious when reviewing artifacts.
Configure automatic screenshots on failure
When running tests with cypress run, Cypress captures screenshots when a test fails by default. This automatic behavior is not enabled in cypress open. In the project configuration, screenshotOnRunFailure controls failure captures and screenshotsFolder sets their destination.
// cypress.config.js
const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotOnRunFailure: true,
screenshotsFolder: 'cypress/screenshots',
})Those values match the documented defaults. To turn off automatic failure images, set screenshotOnRunFailure: false. You can also set shared capture defaults with Cypress.Screenshot.defaults() in a support file.
Know where files go and what happens before a run
The default screenshots folder is cypress/screenshots. Cypress clears the configured screenshot, video, and download asset folders before cypress run by default because trashAssetsBeforeRuns is true. This includes nested contents, not just files at the top level. Set trashAssetsBeforeRuns: false if you need existing assets to survive a run.
// cypress.config.js
const { defineConfig } = require('cypress')
module.exports = defineConfig({
trashAssetsBeforeRuns: false,
})Preserving files can be helpful for workflows that accumulate artifacts, but it also means older images can remain beside current-run output. In CI, make sure your artifact collection distinguishes files from the current execution so a stale screenshot is not mistaken for evidence from the latest test.
Find screenshots in local and CI workflows
Locally, inspect the configured screenshots folder after the run. In CI, the build system may expose that folder as a downloadable artifact. For recorded CI runs, Cypress Cloud can display screenshots alongside test results. The exact way to retain or download local artifacts depends on the CI provider’s artifact settings; Cypress’s screenshot folder is the output to collect.
Understand timing and screenshot reliability
A screenshot is an asynchronous operation. Cypress’s command notes estimate capture at around 100 ms, and the application can change during that interval. Consequently, a failure screenshot may not show precisely the instant at which a preceding command failed. If the image appears to show a later state, treat it as evidence of the page around capture time, not a guaranteed frame of the exact failure moment.
For more repeatable images, place the capture after assertions establish the intended state, use stable selectors, and avoid triggering it while the application is in a transient loading or animation state. Full-page capture also involves scrolling and stitching, so judge it as a composite representation rather than a single viewport frame.
Troubleshoot common screenshot problems
- No automatic image appears in interactive mode: automatic failure screenshots are for
cypress run, notcypress open. Add an explicitcy.screenshot()call when you want a capture during an interactive session. - A previous image disappeared after the run: Cypress clears configured asset folders before
cypress runby default. SettrashAssetsBeforeRuns: falseif preservation is required, and separate old artifacts from current ones in CI. - The image has an unexpected numbered suffix: a file with that name already existed and Cypress avoids overwriting by default. Choose a unique filename or explicitly set
overwrite: true. - Blackout selectors did not conceal content: blackout applies to viewport captures and is ignored for runner captures. Choose viewport capture for that redaction behavior, or ensure sensitive content is not present in the page state being captured.
- A full-page image looks odd around sticky elements: full-page mode scrolls and stitches. Review sticky or fixed elements in the resulting composite and use viewport capture if the desired evidence is the on-screen state at one position.
- A failure image seems later than the failure: capture is asynchronous and the app can update before the image is taken. Stabilize the state before capturing, and interpret an automatic image as a nearby diagnostic view rather than an exact frame.
- You cannot find the image in CI: confirm the configured
screenshotsFolderand configure the CI system to retain that directory as a build artifact. Recorded CI results can also be viewed with screenshots in Cypress Cloud.
Or skip the browser setup
If your goal is a screenshot of a public URL rather than a Cypress test artifact, ScreenshotNeo provides a one-request screenshot API. For example, using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for API details. A Python equivalent:
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)And 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}`);ScreenshotNeo accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, with response headers indicating the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month with no card.
When Cypress is the right capture method
Use Cypress screenshots when the image should document an application state reached by a test, support diagnosis of a failed test, or capture the runner context alongside the page. Use a standalone screenshot API when you need to capture a URL without setting up or running a browser test. The distinction is the workflow: Cypress ties the image to test execution; a URL-based service takes the address as its input.
Frequently Asked Questions
Can I take a screenshot of an element in Cypress?
Yes. Chain .screenshot() from a selected element, for example cy.get('.post').screenshot('post-card').
Can Cypress screenshots be committed to Git?
They are generated artifacts, and Cypress recommends excluding generated asset folders from source control.
Can I get the saved screenshot path in code?
Use screenshot callbacks or the after:screenshot Node event when code needs the resolved path.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
