Run npx cypress run from your project root. Cypress saves screenshots from intentional cy.screenshot() calls and, by default, automatically captures a screenshot when a test fails during cypress run. The default output folder is cypress/screenshots.
Use cy.screenshot() when you want an image of a specific application state, such as a checkout page after it is ready. Use Cypress’s automatic failure capture to diagnose failed tests. The examples below show how to run a focused spec, choose screenshot scope and output location, handle cleanup, and publish images from CI.
Run Cypress in CLI mode
From the directory containing your Cypress project, run:
npx cypress runThis runs the suite headlessly by default. If Cypress is installed in the project, npx runs that project’s version. To investigate one test file rather than the whole suite, pass its path to --spec:
Recommended Free Tools
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
npx cypress run --spec cypress/e2e/checkout.cy.jsReplace the example path with the spec you need. A visible browser can help when diagnosing behavior that is difficult to understand from command-line output alone:
npx cypress run --headed--headed is a debugging choice; headless is the default for cypress run. Cypress documents equivalent commands for Yarn, pnpm, and Bun in its CLI documentation; use the command form appropriate to the package manager in your project.
Capture a specific application state with cy.screenshot()
Add cy.screenshot() after the test has reached and checked the state you want to preserve. For example:
it('captures the checkout state', () => {
cy.visit('/checkout')
cy.get('[data-cy=checkout-form]').should('be.visible')
cy.screenshot('checkout-ready')
})The assertion helps ensure the page has reached a meaningful state before capture. A screenshot command is asynchronous and Cypress says capture takes around 100ms; the application can change during that interval. Avoid placing the command immediately before a transition if the image must show the state before that transition. Synchronize on the relevant UI state first, then capture.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
The filename argument is optional. When provided, it is relative to the screenshot folder and the spec path; nested names create nested directories. For example:
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
cy.screenshot('actions/login/clicking-login')That path organizes the screenshot under nested folders rather than leaving every image at the top level. Cypress may add a file extension based on the configured screenshot format. If a repeated run can produce the same name, decide whether to allow replacement using the overwrite screenshot option.
Understand automatic screenshots when tests fail
During cypress run, Cypress automatically captures screenshots when a test fails. The configuration option screenshotOnRunFailure defaults to true. Cypress does not automatically take failure screenshots during cypress open.
Failure images are named with a (failed) suffix. This lets you distinguish a failure capture from a deliberately named image such as checkout-ready. If failure screenshots are not useful for your workflow, set the option in cypress.config.js:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotOnRunFailure: false,
})Alternatively, Cypress supports changing screenshot defaults from test code:
Cypress.Screenshot.defaults({ screenshotOnRunFailure: false })Choose one configuration approach that fits your project. Turning off this option affects automatic failure captures; it does not remove an explicit cy.screenshot() call from a test.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Choose what Cypress captures
By default, cy.screenshot() captures the application under test. To capture the entire Cypress browser view, including the Command Log, set the default capture mode to runner:
Cypress.Screenshot.defaults({ capture: 'runner' })Screenshot options also support capture: 'viewport' and capture: 'fullPage'. Use viewport capture when the visible browser area is the evidence you need; use full-page capture when content below the fold matters. The default application capture is usually appropriate for an application-state record without the Cypress runner interface.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows 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 reinstallOther controls let you tailor a capture to its purpose:
- Blackout selectors: mask matching page elements, which can be useful for hiding sensitive or changing content in the image.
- Scale: adjust the screenshot scale when the default dimensions are not suitable for review or comparison.
- Overwrite: decide how duplicate screenshot names are handled.
- Animation and timer handling: Cypress disables JavaScript timers and CSS animations by default while taking screenshots to reduce movement. Set
disableTimersAndAnimations: falseif preserving those effects is more important than minimizing motion. - Callbacks: use
onBeforeScreenshotandonAfterScreenshotwhen setup or follow-up work is needed around a capture.
For example, the following call requests a full-page capture while masking a selected element:
cy.screenshot('checkout-full-page', {
capture: 'fullPage',
blackout: ['[data-cy=customer-email]'],
})Use selectors that match only the content you intend to mask. A blackout hides that page content in the screenshot; it does not change the underlying test data or make sensitive information safe to store elsewhere.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Find screenshots and control cleanup
The default screenshotsFolder is cypress/screenshots. A named screenshot is stored under that folder, with its path also reflecting the spec path and any nested filename directories. You can change the folder through Cypress configuration or at run time:
npx cypress run --config screenshotsFolder=artifacts/screenshotsTo specify a configuration file explicitly, use:
npx cypress run --config-file cypress.config.jsBy default, Cypress clears the screenshots folder before cypress run, including nested files and directories. Therefore, do not rely on screenshots from a previous run still being present after a new one. If the run must preserve existing files, configure trashAssetsBeforeRuns: false. That cleanup setting also applies to the videos and downloads folders, so account for those assets as well.
Preserving old captures can make a workspace accumulate stale or duplicate files. If you disable cleanup, use run-specific folders or a deliberate cleanup policy so an image from an earlier run is not mistaken for current output.
Useful CLI commands at a glance
| Purpose | Command | What to expect |
|---|---|---|
| Run the project suite | npx cypress run |
Headless run by default; failure screenshots are enabled by default. |
| Run one spec | npx cypress run --spec cypress/e2e/checkout.cy.js |
Runs the selected spec path, useful when debugging. |
| Show the browser | npx cypress run --headed |
Runs with a visible browser window. |
| Change screenshot output folder | npx cypress run --config screenshotsFolder=artifacts/screenshots |
Writes screenshot output to the configured folder. |
| Select a configuration file | npx cypress run --config-file cypress.config.js |
Loads the named Cypress configuration file. |
Keep Cypress screenshots available in CI
Once the run finishes, publish the configured screenshot folder as a build artifact in your CI provider. With the default folder, the path to upload is cypress/screenshots; if you changed screenshotsFolder, upload that configured path instead. The exact artifact-upload setting depends on the CI provider, so use its documentation for the provider-specific configuration.
Failure screenshots and intentional cy.screenshot() images can also be viewed in Cypress Cloud. Use the local folder or a CI artifact when you need a build-specific file that can be downloaded or retained alongside the job. Use Cypress Cloud when that is where your team reviews run results.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteBest Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
If an artifact is empty, check whether the run produced a screenshot, whether Cypress wrote to a non-default folder, and whether the CI upload step targets that same folder. Also check that a subsequent run or cleanup step did not remove the files before artifact publication.
Troubleshoot missing or misleading screenshots
- No failure screenshot appears: confirm the test ran with
cypress run, not onlycypress open, and check thatscreenshotOnRunFailurehas not been set tofalse. - The file is not in the expected directory: check
screenshotsFolder, any--configoverride, and the spec-relative path created by Cypress. Nested screenshot names also create nested directories. - Older images disappeared: this is the default behavior before a run. Set
trashAssetsBeforeRuns: falseif preservation is required, or copy the files into an artifact before a later cleanup can remove them. - The screenshot shows the wrong page state: put the capture after an assertion that the intended UI is visible. Because capture is asynchronous and takes around 100ms, an immediate page transition can change what appears in the image.
- The image includes the Cypress Command Log: check whether the capture mode is set to
runner. The application is captured by default; use the appropriate application or viewport capture mode for the image you need. - Repeated images replace one another: make screenshot names unique or configure the
overwriteoption to match your desired duplicate-name behavior. - Animations or moving content differ between captures: Cypress disables timers and CSS animations by default during capture. Set
disableTimersAndAnimations: falseonly when the screenshot needs to retain those effects. - A sensitive field remains visible: configure a blackout selector that matches the actual element, then inspect the saved image. Masking is limited to the screenshot and is not a substitute for protecting the source data.
Or skip the browser setup
Cypress is the right route when the screenshot must show a state created by a Cypress test. If instead you need a clean screenshot of a publicly reachable webpage, ScreenshotNeo can return an image with one GET request. This does not replace Cypress for capturing test-specific application state.
Install no browser automation for this request: supply a ScreenshotNeo API key and the page URL. The example saves a WebP response to shot.webp:
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 API documentation for request options. ScreenshotNeo accepts cookie or consent banners as a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
Free tools Windows power users keep installed
One-click scans. No signup required.
ScreenshotNeo’s Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is available on every plan, and yearly billing gives two months free. Visit ScreenshotNeo for product details, or sign up free for 1,000 screenshots a month with no card.
Frequently Asked Questions
Can Cypress take a screenshot without failing a test?
Yes. Add an explicit cy.screenshot() call to a test wherever you want an intentional capture.
Does cypress run need a visible browser to capture screenshots?
No. Headless mode is the default. Use --headed when seeing the browser helps you debug.
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.
