Cypress can capture screenshots, but it does not compare them with an approved image on its own. To catch visual regressions in GitHub Actions, add a Cypress-compatible visual-diff tool, make an approved baseline available to the job, and preserve each run’s screenshots and diffs as artifacts for review. Keep the baseline separate from run artifacts unless your workflow explicitly retrieves the approved version.
What Cypress screenshot tests do—and do not do
cy.screenshot() captures the rendered page or a selected element. Cypress also captures screenshots when tests fail during cypress run by default; its default output folder is cypress/screenshots. A screenshot is only an image, not a visual assertion. Cypress states that it does not perform image comparison itself, so you need a plugin or hosted service to compare the current image with an approved baseline and fail the test when the difference exceeds the configured tolerance. See Cypress visual testing and the screenshot command reference.
As an Amazon Associate I earn from qualifying purchases.
The usual sequence is: set the application to a known state, capture a snapshot, compare it against the baseline, and inspect or approve intentional changes. A passing test means the comparison tool’s configured rule passed; it does not mean Cypress independently judged the image.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose where approved baselines live
Commit baselines with the repository
For a small or straightforward project, storing baseline images beside the test code makes changes visible in pull requests and keeps the expected image tied to a code revision. The visual-diff plugin determines its baseline directory and update workflow, so follow that tool’s configuration rather than assuming Cypress uses a universal baseline path.
Use a hosted visual-testing service
A hosted service can manage baseline history, approvals, and review in a dashboard. Cypress lists integrations such as Sauce Labs Visual and SmartBear VisualTest; evaluate their current workflow, rendering behavior, retention, and pricing before choosing one. The comparison tool’s own documentation determines how snapshots are submitted and approved.
Use artifacts for run output, not as an implicit baseline
GitHub Actions artifacts preserve files generated by a particular workflow run and can transfer files between jobs. They are useful for screenshots, diffs, and videos that reviewers need to inspect. They do not automatically become the approved baseline for the next run. If baselines are not committed or held by a visual-testing service, explicitly retrieve the intended approved baseline, identify its version, and make it available before the comparison step. See GitHub’s artifact documentation.
Configure a deterministic visual comparison
False diffs often come from changes in the capture conditions rather than a meaningful UI regression. Before snapshotting, drive the app to the exact state under test and wait for the relevant content to appear. Use fixtures or intercepted API responses for data that would otherwise vary. Keep the browser, operating system, fonts, viewport, and test data consistent between baseline creation and CI.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →- Set a fixed viewport and use the same browser for baseline generation and CI.
- Wait for a meaningful readiness condition, such as a visible element or completed data load, instead of relying on an arbitrary short delay.
- Disable animations or wait until they finish; mask only regions that genuinely cannot be stabilized.
- Prefer a component or element snapshot when it makes the comparison more focused and easier to review than a full-page image.
- Choose a difference threshold deliberately. A permissive threshold can hide real defects, while an overly strict one can flag harmless rendering variation.
There is a timing detail worth accounting for: Cypress documents that screenshot capture is asynchronous and takes around 100 ms, so the page can change between issuing the command and the image being captured. Avoid triggering state changes at the same time as a snapshot; wait for the intended stable state first.
Run Cypress in GitHub Actions and upload the output
The Cypress-maintained GitHub Action provides a supported way to install dependencies and run Cypress in CI. Its current guide recommends the v7 major action version and demonstrates ubuntu-24.04; both action and runner versions can change, so check the Cypress GitHub Actions guide when setting up a new workflow. The example below assumes the project has npm run build and npm start scripts and that a visual-diff tool writes output to cypress-image-diff. Replace that path with the actual directory configured by your tool.
name: Cypress visual tests
on:
pull_request:
push:
branches: [main]
jobs:
cypress:
runs-on: ubuntu-24.04
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Run Cypress
uses: cypress-io/github-action@v7
with:
build: npm run build
start: npm start
browser: chrome
- name: Upload screenshots and visual diffs
if: always()
uses: actions/upload-artifact@v7
with:
name: cypress-visual-output
path: |
cypress/screenshots
cypress-image-diff
if-no-files-found: ignoreThis is an illustrative workflow, not a tested configuration for every project. Confirm that the selected plugin runs its baseline comparison as part of the Cypress command, and adjust the directories to match its output. Cypress’s action documentation also shows artifact upload patterns for screenshots and videos, including failure-only uploads. If reviewers only need screenshots when a test fails, change the upload condition to if: failure(); use if: always() when successful-run output is useful too. See the Cypress GitHub Action repository.
If the workflow has multiple jobs
Artifacts can move files between jobs, but make the handoff explicit. Give each artifact a descriptive name, upload the generated output in the producing job, and use actions/download-artifact in the dependent job. If a comparison job needs an approved baseline, download that baseline from a deliberate, versioned source; do not substitute the screenshots from the current run.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Updating an approved baseline
- Run the test against the existing approved baseline and inspect the generated difference.
- Decide whether the change is intended. Fix the application or test setup if the difference is an unintended regression or a nondeterministic capture.
- If the change is intentional, use the visual tool’s documented baseline-approval or update process.
- For repository-stored baselines, commit the replacement image with the relevant code change so reviewers can inspect both. For a hosted service, approve the snapshot through its documented review process.
- Run the comparison again to verify the approved baseline now produces the expected result.
Or skip the browser setup
If you need a clean image of a public page rather than a Cypress regression comparison, ScreenshotNeo is a website screenshot API and MCP server. A single request can return PNG, JPEG, WebP, or PDF. It does not replace a Cypress visual-diff plugin or manage your application’s approved regression baseline.
For example, capture a page to WebP with 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 API documentation for request parameters. Cookie banners and consent prompts, newsletter popups, and chat widgets are removed before capture; those cleanup steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides screenshot and PDF tools for AI agents. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card required.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting common failures
The test captures an image but never fails on a visual change
cy.screenshot() only saves an image. Add and configure a comparison plugin or service, and make sure its assertion is part of the test or CI command.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsThe comparison cannot find a baseline
Check the plugin’s configured baseline path, whether the file is present in the checked-out repository, and whether the expected browser or snapshot name matches. In a multi-job workflow, confirm the baseline was explicitly transferred or retrieved before the comparison runs.
Artifacts are missing
Check the workflow’s output paths against the plugin’s actual configuration and the Cypress screenshot folder. An artifact upload step with if: failure() will intentionally skip successful runs; use if: always() when output should be retained regardless of the test result. if-no-files-found: ignore suppresses an upload error when no matching files exist, so verify the paths rather than treating a successful workflow as proof that files were uploaded.
There are noisy or inconsistent diffs
Compare the baseline and CI browser, operating system, fonts, viewport, data, and application state. Wait for images and dynamic content to settle, control API responses, and disable animations or narrowly mask unavoidable volatile regions. Avoid broad masks that could hide real regressions.
The page is captured before it is ready
Wait on the page condition that matters to the snapshot—for example, a specific element becoming visible or a loading indicator disappearing. Cypress screenshot capture is asynchronous, so do not issue a screenshot immediately before another command changes the same visible state.
The action or runner behaves differently over time
Confirm the Cypress action major version and GitHub-hosted runner image against the current Cypress CI guide. The example uses the guide’s recommended @v7 and example ubuntu-24.04 at the time checked; action and runner support can evolve.
Frequently Asked Questions
Does Cypress automatically compare screenshots with a baseline?
No. Cypress captures screenshots; a plugin or hosted visual-testing service must perform image comparison.
Where does Cypress save screenshots in CI by default?
The default Cypress screenshot folder is cypress/screenshots.
Are GitHub Actions artifacts the same as approved visual baselines?
No. Artifacts preserve outputs from a workflow run; an approved baseline must be available independently or explicitly retrieved.
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.
