Cypress offers screenshot options at three levels: on an individual cy.screenshot() call, as shared screenshot defaults, and in project configuration. Use capture: 'viewport' for the visible page, 'fullPage' for the page from top to bottom, or 'runner' to include the Cypress Command Log. Cypress also takes screenshots automatically when tests fail in cypress run unless you disable that behavior.
Choose the right Cypress screenshot setting
Start by deciding what you need to capture and how broadly the setting should apply. A per-call option is best for one special screenshot; shared defaults cover screenshot calls more generally; project configuration controls run behavior and artifact locations.
| Need | Use | Scope |
|---|---|---|
| Change one screenshot’s capture mode, filename, crop, or callbacks | cy.screenshot(...) |
That invocation |
| Set common screenshot behavior across calls, including failure screenshots | Cypress.Screenshot.defaults(options) |
Screenshot API defaults |
| Disable automatic failure captures or change artifact folders and cleanup | Project configuration | Run-level behavior |
| Compare images across builds and review visual differences | A visual-testing integration | Beyond capture |
The Cypress documentation consulted for these options does not identify a single release version. Defaults and behavior can differ across historical versions, so confirm them against the version installed in your project.
Take a screenshot with cy.screenshot()
The command reference documents four call forms: cy.screenshot(), cy.screenshot(fileName), cy.screenshot(options), and cy.screenshot(fileName, options). For example:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated 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 matchcy.screenshot('checkout/confirmation', {
capture: 'viewport',
blackout: ['.customer-email'],
overwrite: true
})The filename is relative to the screenshots folder and the spec path. Cypress can create nested directories for path segments such as checkout/confirmation. If you omit the name, Cypress chooses one based on the spec and command context.
Capture mode: viewport, full page, or runner
capture: 'viewport'captures the application as it appears in the current browser viewport.capture: 'fullPage'captures the application from top to bottom.capture: 'runner'captures the browser viewport together with the Cypress Command Log.
The documented command default is fullPage, though a shared default or project/version behavior may affect what your suite uses. The capture option is ignored for element screenshots. Failure screenshots are forced to runner. When Test Replay is enabled and the Runner UI is hidden, a runner capture instead includes only the application in the current viewport.
Crop, mask, scale, and stabilize
blackoutaccepts an array of CSS selectors whose matching elements should be blacked out. It does not apply to runner captures.clipcrops the final image using pixel coordinates and dimensions. The documented default isnull.scalecontrols whether the application is scaled to fit the browser viewport; its documented default isfalse. Runner captures always use scaling.disableTimersAndAnimationsdefaults totrue, which helps reduce changes while Cypress captures the page. Set it tofalseif the capture must preserve timer or animation behavior.paddingchanges image dimensions for element screenshots only; its documented default isnull.
Use blackout for sensitive or visually noisy regions when masking is suitable, but remember that it is not available for runner captures. Use clip when the goal is to crop the final image rather than target a specific element.
Other per-call options
| Option | Documented default | Purpose |
|---|---|---|
log |
true |
Controls whether the command is logged in the Command Log. |
blackout |
Empty array | CSS selectors for areas to black out, except in runner captures. |
capture |
'fullPage' |
Chooses viewport, full-page, or runner capture. |
clip |
null |
Crops the final image using pixel coordinates and dimensions. |
disableTimersAndAnimations |
true |
Reduces changes from timers and animations during capture. |
padding |
null |
Changes dimensions for element screenshots only. |
scale |
false |
Scales the application to fit the viewport; runner capture always scales. |
timeout |
responseTimeout |
Sets the command timeout. |
overwrite |
false |
Controls whether an existing screenshot file can be overwritten. |
onBeforeScreenshot |
Callback option | Runs a callback before capture. |
onAfterScreenshot |
Callback option | Runs a callback after capture. |
The command yields the same subject it received, but Cypress warns that chaining commands that rely on that subject after .screenshot() is unsafe. Put capture at the end of a chain or begin a new chain for subsequent subject-dependent work.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Set shared screenshot defaults
Use Cypress.Screenshot.defaults(options) when a behavior should apply across screenshot calls rather than only one invocation. The API reference also demonstrates defaults affecting automatic failure screenshots, including disabling failure captures.
Cypress.Screenshot.defaults({
blackout: ['.private-data'],
capture: 'runner',
disableTimersAndAnimations: false,
overwrite: true,
scale: true,
screenshotOnRunFailure: false
})Choose defaults carefully: a shared capture: 'runner', for example, is different from setting capture: 'viewport' for one targeted test. If you need a special image in a small part of a suite, prefer a per-call option so unrelated captures keep their normal behavior.
Configure automatic failure screenshots and artifact folders
Cypress automatically captures screenshots on test failure during cypress run, but not during cypress open. The project configuration reference lists screenshotOnRunFailure with a documented default of true. Set it to false in configuration to disable run-failure captures:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
screenshotOnRunFailure: false,
screenshotsFolder: 'cypress/screenshots',
trashAssetsBeforeRuns: true
}
})This example shows the setting names and a common configuration shape; check the configuration format supported by the Cypress version in your project. The documented default screenshots folder is cypress/screenshots. The screenshots-and-videos guide explains that Cypress clears the entire screenshots folder, including nested folders, before cypress run by default.
Keep screenshots between runs
trashAssetsBeforeRuns defaults to true and controls cleanup of the downloads, screenshots, and videos folders before a run. Set it to false if you need to preserve those assets:
module.exports = defineConfig({
e2e: {
trashAssetsBeforeRuns: false
}
})Preserving artifacts can be useful for local debugging, but it also means old files may remain beside new ones. Account for that when inspecting output or publishing artifacts in CI.
Manual screenshots, videos, and visual comparison
You can take manual screenshots in both cypress open and cypress run. Automatic failure screenshots, however, are a cypress run behavior. Video is separate from screenshots: recording is off by default, and setting video: true enables a video for each spec during cypress run, not cypress open. The documented default video folder is cypress/videos.
Cypress’s visual-testing guide says the built-in cy.screenshot() command captures images but does not compare them. For comparison and review workflows, that guide identifies integrations including Happo, Percy by BrowserStack, and Sauce Labs Visual. Choose a visual-testing integration when you need to detect or review image differences rather than merely save screenshots.
Recommended Free Tools
Or skip the browser setup
If you need a screenshot of a public URL outside a Cypress test, ScreenshotNeo offers a one-request API rather than a browser setup. Its API can return a screenshot or PDF; its capture flow can accept consent banners and remove known consent platforms, newsletter popups, and chat widgets. Failed loads, blank pages, bot checks, and cache hits are not billed, and response headers indicate the page verdict and billing status. An MCP server provides screenshot tools for AI agents and MCP clients. See ScreenshotNeo and the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpReplace the example URL with the page you want to capture and supply your API key. ScreenshotNeo’s Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Every feature is on every plan. Sign up for 1,000 free screenshots a month with no card.
Troubleshoot common screenshot problems
- No automatic screenshot appears in open mode: automatic failure screenshots are taken in
cypress run, notcypress open. Take a manual screenshot withcy.screenshot()when you need one during interactive work. - A screenshot is missing after a run: check whether the test failed in
cypress run, whetherscreenshotOnRunFailureis disabled, and whether the run cleared the screenshots folder before starting. - Older artifacts disappear: the default
trashAssetsBeforeRuns: trueclears contents of the downloads, screenshots, and videos folders. Set it tofalsewhen preserving them is intentional. - The image includes the Command Log unexpectedly: inspect the effective
capturesetting.runnerincludes the Runner UI; useviewportorfullPagefor application-only capture, noting that failure captures are coerced to runner. - Blackout selectors have no effect:
blackoutdoes not apply to runner captures. Use an application capture mode or another approach appropriate to the content. - Output already exists and is not replaced: the documented
overwritedefault isfalse. Setoverwrite: truefor that call or in shared defaults if replacing files is intended. - Animations make screenshots inconsistent: the documented default disables timers and animations. Check whether your call or shared defaults set
disableTimersAndAnimations: false; restoretruewhen a steadier capture is more important than showing motion. - Code after screenshot behaves unexpectedly: Cypress cautions against chaining commands that depend on the yielded subject after
.screenshot(). Start a fresh chain for subsequent work. - You have images but no visual-difference result: Cypress capture alone does not compare screenshots. Add a visual-testing integration if comparison and review are required.
Frequently asked questions
Can I take a screenshot of just one element?
The screenshot options documentation distinguishes element screenshots; for those, capture is ignored and padding can change the image dimensions. Use the element-specific Cypress command or syntax supported by your installed version.
Does cy.screenshot() return an image for chaining?
It yields the same subject it received, not a separate image object. Cypress advises against chaining commands that rely on that subject after the screenshot call.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Does a Cypress screenshot prove two page versions match?
No. The command creates an image; image comparison is a separate visual-testing workflow.
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.
