Recommended Free Tools
When a Cypress screenshot is missing from CI, check two separate things: whether Cypress created the file on the runner, and whether your workflow uploaded it as an artifact. Cypress normally captures failures during cypress run, but a file on the runner is not automatically downloadable from your CI service.
1. Confirm Cypress should have taken a screenshot
Automatic failure screenshots are taken during cypress run, not automatically during interactive cypress open. They are captured when a test fails; a passing test does not produce a failure screenshot. To capture an image deliberately, call cy.screenshot() in the test.
As an Amazon Associate I earn from qualifying purchases.
Start by checking the Cypress run output and whether the test actually failed. If you need to verify screenshot behavior independently of a failure, add an explicit cy.screenshot() call at the point you want to capture.
2. Check screenshot settings and the runner’s directory
In Cypress configuration, screenshotOnRunFailure defaults to true, and screenshotsFolder defaults to cypress/screenshots. A project setting, screenshot default, or runtime override may change either value. Check the effective configuration used by CI, then inspect that directory on the runner rather than assuming the default path.
For example, a customized folder means the upload step must use that folder too. If Cypress wrote the file somewhere other than the path your workflow uploads, the test can have a screenshot locally while the artifact contains none.
3. Check whether a run cleared earlier screenshots
trashAssetsBeforeRuns defaults to true, which clears the contents of the configured screenshots folder before cypress run. This is expected cleanup, not evidence that Cypress failed to create a new screenshot. If you need to retain files across runs, set it to false intentionally and account for possible stale files when reviewing results.
4. Upload the generated files as a CI artifact
Artifact creation is a separate step from Cypress screenshot creation. The uploader must run after Cypress, target the effective screenshotsFolder, and use the artifact mechanism for your CI provider. Cypress supports providers including GitHub Actions, CircleCI, GitLab CI, Jenkins, and AWS CodeBuild, but their pipeline syntax is not interchangeable.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
GitHub Actions example
The Cypress-maintained GitHub Action repository shows uploading screenshots after the Cypress run. This example uses GitHub Actions; ensure your repository and runner support the action versions shown. If you use a matrix, give each job a unique artifact name if they upload independently.
- name: Cypress run
uses: cypress-io/github-action@v7
- name: Upload screenshots
if: failure() # Optional: upload only when the preceding job steps have failed
uses: actions/upload-artifact@v7
with:
name: cypress-screenshots
path: cypress/screenshots
if-no-files-found: warnChange path if your configured screenshot folder differs. The upstream Cypress example uses if-no-files-found: ignore; GitHub’s upload action documents warn as the default. During diagnosis, warn or error makes a path mismatch visible instead of silently ignoring it. Check the workflow log for the uploader’s result and look for the artifact in that run’s artifact area.
The if: failure() condition is optional. It limits uploading to runs where a preceding step failed; remove or adjust it if your workflow needs screenshots from successful runs too. For another CI provider, use its current official artifact documentation rather than copying this GitHub Actions syntax.
5. Diagnose the symptom
| What you observe | Likely check | What to do |
|---|---|---|
| No screenshot file appears on the runner | Run mode, test outcome, screenshotOnRunFailure, effective folder, and pre-run cleanup |
Confirm a failing test ran under cypress run; check overrides and inspect the configured folder after the run. |
| A file exists on the runner but no downloadable artifact appears | Upload step, upload condition, artifact path, and uploader log | Run the upload after Cypress, point it at the actual folder, and check whether a failure-only condition skipped the step. |
| The uploader reports that no files matched | Path mismatch or no screenshot generated | Compare the upload path with the effective screenshotsFolder; then verify whether the test failure should have triggered a capture. |
| Files from a previous run disappeared | trashAssetsBeforeRuns |
Remember that the default is to clear the screenshot folder before each run. Disable cleanup only if retaining prior output is deliberate. |
| The failure happens only in CI | The test failure itself and differences between CI and local environments | Inspect screenshots, video, or Test Replay where available, then isolate environmental differences. Missing evidence and the cause of the failing test are separate problems. |
6. Choose where to inspect run evidence
Provider-native artifacts are useful when your team wants files attached to the CI run. Cypress Cloud can show screenshots from a CI run when that run is recorded; Test Replay can provide more execution context than a static image. These Cloud options depend on the project’s configuration and do not replace artifact setup when you want files retained through your CI provider.
Choose based on where teammates need to retrieve evidence, whether the project already records runs, and whether a static image is sufficient or execution context is useful. Artifact retention and access rules depend on the CI provider and project; confirm them in the provider’s current documentation.
Or skip the browser setup
If your goal is to capture a page rather than debug Cypress’s test-run screenshot behavior, ScreenshotNeo can return a screenshot with one GET request. See the ScreenshotNeo API documentation for options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. It also provides an MCP server for AI agents, with screenshot, page-info, and PDF-capture tools. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Try ScreenshotNeo for standalone page captures, or sign up free for 1,000 screenshots a month with no card.
Free tools Windows power users keep installed
One-click scans. No signup required.
Frequently Asked Questions
Where does Cypress save screenshots by default?
In cypress/screenshots, unless the effective screenshotsFolder configuration changes it.
Why is there no screenshot when a Cypress test passes?
Automatic run-failure screenshots are triggered by failing tests. Add cy.screenshot() when you need a deliberate capture.
Does Cypress automatically make screenshots downloadable from CI?
No. Cypress can create files on the runner; a separate provider-specific artifact step is needed to make them downloadable from the CI run.
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.
