Use Cypress’s built-in .screenshot() command on a query that yields the element: cy.get('.post').first().screenshot(). You can add padding or a filename in the command options. The screenshot is saved in Cypress’s screenshots folder, relative to the spec path.
Capture one element
First select the target with a Cypress query, then chain .screenshot() from the element it yields:
As an Amazon Associate I earn from qualifying purchases.
cy.get('.post').first().screenshot()Cypress documents that .screenshot() can be chained from cy or from a command yielding a single DOM element. For an element capture, the query should resolve to the element you intend to capture. Cypress screenshot API
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 errorsSet padding or a filename
Add space around the element
Use padding to include space around the captured element. It accepts a number or an array of up to four values using CSS shorthand notation:
cy.get('.post').first().screenshot({ padding: 10 })Choose a screenshot name
Pass a name as the first argument when you want a recognizable artifact filename:
cy.get('.post').first().screenshot('post-card')By default, Cypress uses test-based names. If a name already exists, it adds a numeric suffix unless overwrite is enabled. Cypress screenshot API
Know what element capture options do
The capture option selects the application viewport, full page, or runner for other screenshot modes. Cypress ignores it for element captures, so it does not switch an element screenshot into a full-page or runner screenshot. The documented clip option describes cropping by an x/y position and width/height in pixels; it is separate from selecting an element subject. Check the API documentation for the option behavior relevant to your Cypress version. Cypress screenshot API
Find the output file
Cypress’s screenshotsFolder defaults to cypress/screenshots and can be changed in configuration. Screenshot paths are relative to that folder and the spec path. Cypress also saves screenshots taken for failures during cypress run there by default. Cypress screenshots and videos guide Cypress configuration reference
Account for asynchronous capture
Screenshot capture is asynchronous. Cypress describes it as taking around 100 ms, and warns that application state may change before the capture completes. Do not assume the image is an exact frame of the page at the instant the command was invoked. For non-failure screenshots, Cypress provides callbacks that can synchronously adjust the DOM before and after capture. Cypress screenshot API Cypress screenshot API
The command yields the same subject, but Cypress says it is unsafe to chain further commands that depend on that subject after .screenshot(). Chained assertions run once and are not retried. Keep subject-dependent queries or assertions before the screenshot command, or start a fresh query afterward. Cypress screenshot API
Troubleshoot common issues
- The wrong content appears: make the selector specific and, if the query can match several elements, select the intended match with a command such as
.first(). Cypress’s example uses the first.postelement. Cypress screenshot API - You expected full-page output:
capturedoes not change element capture. Use the appropriate non-element capture mode if the goal is a viewport or full-page image. Cypress screenshot API - You cannot find the file: check the configured
screenshotsFolderand the spec-relative path; the default folder iscypress/screenshots. Cypress configuration reference - The image reflects changed page state: allow for the asynchronous capture interval and use the documented callbacks to adjust the DOM synchronously when needed for a non-failure screenshot. Cypress screenshot API
- A following command behaves unexpectedly: do not rely on the subject yielded by
.screenshot()for further chained commands; run a new query instead. Cypress screenshot API
Capture with ScreenshotNeo instead
If you need an image from a URL without setting up a Cypress browser run, ScreenshotNeo provides a website screenshot API and MCP server. Its API returns an image or PDF from a single GET request. This captures a page by URL, not a DOM element selected inside your Cypress test.
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 & 11Install the Python dependency with python -m pip install requests, then run:
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)See the ScreenshotNeo API documentation for setup and options. Cookie banners, popups and chat widgets are removed before the shot; bot checks, blank pages and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan.
When you need visual regression testing
A Cypress screenshot is an image artifact; comparing it against a baseline and reviewing visual changes are separate workflows. Cypress’s visual testing guide describes Percy as capturing DOM snapshots and rendering them across browsers and responsive widths, and Sauce Labs Visual as offering baseline creation, region ignoring and review workflows. The guide also points to Applitools documentation as another Cypress option. These tools address comparison and review rather than simply taking an element screenshot. Cypress visual testing guide
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.
