Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11To configure Cypress screenshots, set project-wide output and cleanup options in your Cypress configuration file, then use Cypress.Screenshot.defaults() in the support file for shared capture behavior. Use cy.screenshot() options when a particular test needs different settings. The key distinction: automatic failure screenshots are created during cypress run, not cypress open, and Cypress clears screenshot, video, and download artifacts before each run by default.
Choose the right configuration layer
Cypress screenshot behavior is controlled at three levels. Project configuration governs where artifacts go, whether Cypress automatically captures failures, and whether prior run assets are cleared. Cypress.Screenshot.defaults() sets reusable capture options. A specific cy.screenshot() call can supply options for that capture and override shared defaults. The current official documentation describes these APIs, but does not establish one precise Cypress release version for every referenced page; check the docs for the version installed in your project.
- Project configuration:
screenshotsFolder,screenshotOnRunFailure, andtrashAssetsBeforeRuns. - Support-file defaults: shared capture mode, animation handling, blackout selectors, and related screenshot options.
- Command options: one-off filename, capture mode, selector masking, callbacks, and other per-capture choices.
Official references: Cypress configuration, Cypress.Screenshot API, and cy.screenshot().
Set the screenshot folder and run cleanup behavior
In a CommonJS Cypress configuration file, such as cypress.config.js, configure project-level settings with defineConfig:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotsFolder: 'artifacts/screenshots',
screenshotOnRunFailure: true,
trashAssetsBeforeRuns: false,
})The example sends screenshots to artifacts/screenshots, keeps automatic failure screenshots enabled, and disables Cypress’s pre-run cleanup. Adapt the module syntax if your project uses a different configuration format. The documented default screenshot folder is cypress/screenshots.
Understand what cleanup removes
trashAssetsBeforeRuns defaults to true. Before cypress run, Cypress clears the contents of the screenshots, videos, and downloads folders, including nested files and directories. It does not perform this cleanup when you use cypress open. The official guide describes the behavior as: “Before cypress run, Cypress clears the entire contents of the screenshotsFolder—every file and nested subfolder, not just images.” See Capture screenshots and videos in Cypress.
Operating-system behavior differs: Cypress documents that it empties the contents directly on Linux; on macOS and Windows, items are moved to the system trash or Recycle Bin. If a CI job must retain artifacts between runs, turning cleanup off is only part of the solution: deliberately manage the artifact directory so old screenshots are not mistaken for current results.
Decide whether failures should be captured
screenshotOnRunFailure defaults to true. It enables automatic screenshots of test failures in cypress run, including CI runs. It does not trigger automatic failure screenshots in the interactive cypress open app. To disable automatic failure images, set screenshotOnRunFailure: false in project configuration. The Screenshot API also documents setting this option through Cypress.Screenshot.defaults().
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Set shared screenshot defaults
Place reusable screenshot defaults in the Cypress support file, which is loaded before test files are evaluated. For example:
Cypress.Screenshot.defaults({
capture: 'viewport',
disableTimersAndAnimations: true,
blackout: ['[data-sensitive]'],
})This is a separate layer from screenshotsFolder and run cleanup. It establishes defaults for screenshot captures; a command can pass its own options when it needs different behavior. The example captures the viewport, pauses timers and CSS animations during capture, and masks elements matching [data-sensitive] where blackout applies.
Choose a capture mode
The documented capture values are viewport, fullPage, and runner. Choose based on what the artifact needs to show, not just on image dimensions.
| Mode | What it captures | Useful when |
|---|---|---|
viewport |
The application’s current viewport. | You need a focused image of the visible UI state. |
fullPage |
The application from top to bottom; Cypress scrolls and stitches the capture. | You need a page-level artifact beyond the currently visible viewport. |
runner |
The browser viewport including the Cypress Command Log. | You need test-run context alongside the application view. |
Automatic test-failure screenshots are coerced to runner. When Test Replay is enabled and the Runner UI is hidden, a runner screenshot may show only the current application viewport. Treat the capture mode as part of the artifact’s meaning: a runner capture and an application-only capture are not interchangeable. See the Screenshot API documentation.
Control repeatability, scale, and sensitive content
Animations and timers
Cypress disables timers and CSS animations by default during capture to reduce changes while the screenshot is taken. This helps when a moving element would make otherwise equivalent captures differ. If the animation itself is the subject of the test, set disableTimersAndAnimations: false for that capture or in the shared defaults. Keep in mind that allowing movement can make the exact captured frame variable.
Image scaling
scale defaults to false for application captures. Runner capture coerces it to true. Cypress says the default for application screenshots avoids differences between screenshots on displays with different resolutions. If you change scaling, consider whether comparisons across machines remain meaningful.
Blackout selectors and Command Log visibility
blackout accepts CSS selectors and masks matching elements for viewport screenshots, but does not apply to runner captures. It is not a universal redaction guarantee: match the masking method to the capture type and inspect the resulting artifact before sharing it. Cypress Cloud’s data-control guidance separately discusses hiding Command Log content in screenshots; do not assume that blackout selectors hide runner UI or log content. See Data storage and controls in Cypress Cloud.
Name screenshots and predict their paths
By default, Cypress organizes images beneath the configured screenshot folder using spec path and test name. It removes common ancestor directories among the specs in a run to avoid unnecessarily deep paths, so the exact relative path can vary with which specs run together. The output structure is therefore not always a fixed mirror of the repository tree. See Writing and organizing Cypress tests.
A supplied filename replaces the test name in the output path, can include nested directories, and receives a .png extension. Duplicate names are numbered unless overwrite: true is passed. Default failure screenshot filenames append (failed) to the test-name filename. These naming rules are documented in the cy.screenshot() command reference.
For example, a one-off capture can set its own name and mode:
cy.screenshot('checkout/confirmation', {
capture: 'viewport',
overwrite: true,
})This uses a nested filename and permits replacement rather than duplicate numbering. Only use overwrite when replacing an earlier artifact is intentional; otherwise, numbered files can preserve multiple captures.
Adjust the page around a capture or handle its result
onBeforeScreenshot and onAfterScreenshot let a test make synchronous DOM adjustments around non-failure screenshots. One example is hiding a changing clock immediately before capture to reduce visual differences. The after callback receives screenshot details such as the resulting path and dimensions. These callbacks concern the capture operation; they are not a substitute for the separate Node event used when post-processing the file.
The after:screenshot Node event runs after a manual or failure screenshot and can access the file system. Cypress commands cannot be called from that event handler. Use it for Node-side work on the completed artifact, not for issuing browser commands. Details are in the after:screenshot event reference.
Troubleshoot common screenshot surprises
- The screenshot folder is empty after CI: Check whether the artifact upload step runs after Cypress, and whether the job uploads the configured
screenshotsFolderrather than assuming the defaultcypress/screenshots. - Earlier screenshots disappeared: Check
trashAssetsBeforeRuns. It defaults totrueforcypress runand clears screenshot, video, and download contents before the run. Disable it only if your job also handles stale artifacts. - No automatic screenshot appears in
cypress open: Automatic failure screenshots are associated withcypress run; use a manualcy.screenshot()call if an interactive-run capture is needed. - A “full page” capture is much taller or behaves differently than expected: Verify that
capture: 'fullPage'is intentional. Cypress scrolls through the application and stitches the result rather than capturing only the current viewport. - Sensitive text remains visible: Confirm the selector matches the intended element and that the capture is a viewport screenshot. Blackout does not apply to runner captures; verify the actual saved file before distributing it.
- Paths differ between test selections: Cypress trims common ancestor directories based on the specs in that run. Avoid assuming that every run produces identical spec-relative paths if the selected spec set changes.
- Two captures create multiple files: Duplicate names are numbered by default. Set
overwrite: trueonly if replacement is desired, or give captures distinct filenames. - A callback cannot invoke a Cypress command: The
after:screenshotNode event is not a test command context. Use it for file-system operations; use the screenshot callbacks for synchronous DOM adjustments around non-failure captures.
Or skip the browser setup
If you need a screenshot from a URL rather than a Cypress test artifact, ScreenshotNeo offers a one-request screenshot API. This cURL example saves a WebP image of Stripe; replace the target URL and API key with your own:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpFor setup and request options, see the ScreenshotNeo documentation. ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It removes cookie banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Start with the free ScreenshotNeo account.
Cost, performance, and artifact reliability
Cypress screenshot configuration itself does not establish a billed-per-image price in the cited documentation. For CI reliability, the consequential choice is artifact lifecycle: default cleanup gives a cleaner run boundary, while preserving artifacts requires your job to avoid mixing prior output with current results. Upload the folder Cypress actually uses, and retain enough run context to associate an image with its spec and test.
Recommended Free Tools
Capture scope also affects usefulness and processing: viewport captures keep the artifact focused, while full-page mode scrolls and stitches. The official sources cited here describe that behavior but do not provide a universal timing or memory cost, so measure your own suite if capture duration matters. Runner images add Command Log context but have different masking implications from viewport images. Treat screenshots as test artifacts whose paths, privacy, and retention rules belong in the CI design, rather than assuming a changed folder setting alone solves persistence.
Frequently Asked Questions
Can I change Cypress screenshots from PNG to JPEG?
The documented `cy.screenshot()` filename behavior adds a `.png` extension; the cited Cypress documentation does not establish a configurable JPEG output option.
Does Cypress take a failure screenshot when running tests interactively?
No automatic failure screenshot is taken in `cypress open`; the documented automatic behavior is for `cypress run`.
Where should shared Cypress screenshot defaults go?
Put `Cypress.Screenshot.defaults()` in the support file so it is evaluated before test files.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsQuick 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.
