How to Archive Website Screenshots from Cypress Test Runs

To archive Cypress screenshots, run your tests with cypress run, then upload the configured screenshots folder as a CI artifact—even when the test step fails. Cypress automatically captures screenshots for failed tests in run mode, saving them by default to cypress/screenshots. The folder is cleared before each run by default, so the CI upload should collect the current run’s files after Cypress exits.

You can also use Cypress Cloud to browse screenshots attached to recorded test results. Choose CI artifacts when downloadable files and your existing CI workflow are sufficient; consider Cloud when you want screenshots alongside managed test results. Confirm retention and access settings for your CI provider or Cypress account before relying on them.

1. Configure Cypress screenshot capture

Failure screenshots are enabled by default for cypress run. They are not automatically captured in cypress open. Set the folder and failure behavior explicitly if you want the workflow to be easy to recognize and maintain.

// cypress.config.js
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  screenshotOnRunFailure: true,
  screenshotsFolder: 'cypress/screenshots',
  trashAssetsBeforeRuns: true,
})

For an ES module configuration file, use import { defineConfig } from 'cypress' and export default defineConfig({...}) with the same options. Cypress also accepts configuration overrides on the command line; check the configuration reference for the syntax supported by your installed version.

Setting	Default	Use
`screenshotOnRunFailure`	`true`	Automatically capture screenshots when tests fail during `cypress run`. Set false to disable automatic failure screenshots.
`screenshotsFolder`	`cypress/screenshots`	Choose where generated screenshots are written. Configure the artifact uploader to collect this same location.
`trashAssetsBeforeRuns`	`true`	Clear generated assets before a run. Set false only when retaining prior files in that folder is intentional.

Cypress clears the entire screenshots folder before a run when trashAssetsBeforeRuns is enabled, including nested files. This helps avoid archiving stale screenshots, but means the folder is not a cross-run archive: upload each run’s output to durable storage before the job ends.

2. Add useful named screenshots when needed

Automatic failure screenshots cover the common case. Use cy.screenshot() when you also need a deliberately named capture at a meaningful point in a test. Cypress can save nested paths, but generated directory structure can depend on the spec paths in a run.

describe('checkout', () => {
  it('shows the order confirmation', () => {
    cy.visit('/checkout/confirmation')
    cy.get('[data-testid="order-number"]').should('be.visible')
    cy.screenshot('checkout/order-confirmation')
  })
})

The screenshot command is asynchronous; Cypress documents that capture takes around 100 ms, and the rendered page can change between issuing the command and capture. Wait for the state you need before calling it, and do not treat the image as an exact frame of the instant the command was issued.

For custom scripts that copy or rename captures, use file paths reported by Cypress screenshot callbacks or the after:screenshot and after:spec Node events. Avoid reconstructing paths from spec names: Cypress notes that the shared ancestor of spec paths can change when the set of specs changes.

3. Upload screenshots as a CI artifact

Run Cypress, then upload cypress/screenshots as a workflow artifact. Configure the upload step to run after failures where your CI provider supports it; otherwise, a failed test step may prevent the archive step from running. Artifact syntax and retention controls vary by provider, so use that provider’s current documentation.

GitHub Actions example

This example uses Cypress’s documented GitHub Actions workflow pattern and the artifact action. Pin action versions according to your repository’s policy and check current provider documentation for available retention settings.

name: Cypress tests

on:
  push:
  pull_request:

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx cypress run
        id: cypress
      - name: Archive Cypress screenshots
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: cypress-screenshots
          path: cypress/screenshots
          if-no-files-found: ignore

The always() condition lets the artifact step run after Cypress fails. if-no-files-found: ignore avoids turning a run with no screenshots into another failure. If you prefer to detect unexpected missing files, use the provider’s warning or error behavior and make that an intentional workflow choice.

If you change screenshotsFolder, update the artifact path too. A mismatch often looks like a successful test run with an empty downloadable artifact.

GitLab CI example

e2e:
  image: cypress/browsers:latest
  script:
    - npm ci
    - npx cypress run
  artifacts:
    when: always
    paths:
      - cypress/screenshots/
    expire_in: 1 week

Use an image and expiry policy suitable for your project. Verify artifact syntax and allowed expiry values against your GitLab version and account configuration.

Other CI providers

Use the provider’s artifact or workflow-output feature to collect the configured screenshots folder after Cypress completes. Check three details in that provider’s documentation:

How to run an upload step even when the test command fails.
How to set artifact retention and who can download the files.
How the provider handles a missing path when a run has no failures.

4. Decide between CI artifacts and Cypress Cloud

Question	CI-provider artifact	Cypress Cloud
Where do screenshots appear?	As files attached to a CI workflow or job.	Alongside recorded test results and other run data.
What is retention?	Set by provider controls, repository policy, and account configuration.	Depends on the applicable Cypress Cloud account and plan settings.
What is the workflow fit?	Teams that mainly need downloadable files in their existing CI.	Teams that want a managed interface for browsing recorded test runs and their artifacts.
What should you verify?	Failure-step behavior, retention, access and sharing controls.	Plan-specific retention, access and sharing behavior.

Neither route implies a universal retention duration or access policy. Review your provider or account settings before choosing how long screenshots remain available or who can view them. Cypress Cloud can attach screenshots to recorded runs; it is an alternative retention route, not a replacement for checking account-specific terms.

5. Handle privacy and repository cleanup

Screenshots can contain personal information, account data, or secrets rendered into a page. Review captures before sharing them broadly and limit artifact access according to your project’s requirements. Cypress supports screenshot blackout selectors, but documents that blackout applies only to viewport captures, not runner captures. Confirm the capture mode and validate the output rather than assuming sensitive content was hidden.

Generated downloads, screenshots, and videos are commonly excluded from source control. A typical .gitignore entry is:

cypress/screenshots/

Ignoring local generated files does not prevent CI from uploading them as artifacts. Keep the ignore rule aligned with your chosen screenshotsFolder if you change the path.

6. Troubleshooting

Symptom	Likely cause	Fix
No screenshot appears after a failed test.	You ran `cypress open`, disabled failure capture, or the failure happened outside the normal test failure capture path.	Run `cypress run`, confirm `screenshotOnRunFailure: true`, and inspect Cypress output for the saved path.
The artifact exists but contains no files.	The upload path differs from `screenshotsFolder`, or no test failed and no explicit screenshot was taken.	Align the CI artifact path with Cypress configuration. Decide whether an empty artifact should be ignored, warned on, or treated as an error.
Only some screenshots are present.	The upload step did not run after a failed test, or the job was canceled before artifact collection.	Use the provider’s always-run/after-failure condition and check cancellation behavior.
Old screenshots disappeared.	`trashAssetsBeforeRuns` defaults to true and clears the folder at run start.	Upload each run’s files before job completion. Set it false only if you deliberately manage stale files and distinguish runs.
Expected filename or directory is different.	Cypress organizes screenshots relative to specs, and that structure can shift as the spec set changes.	Use reported paths or Cypress Node events for file processing; do not assume a path derived from a spec name.
Sensitive text is visible in an archived image.	Blackout behavior may not apply to runner captures, or the relevant selector was not covered.	Check capture mode, validate the artifact, and avoid distributing images that expose sensitive values.
The screenshot shows a slightly later page state.	Capture is asynchronous and the page can render while Cypress takes the image.	Wait for the desired state before capture and use assertions to establish that state.

7. Performance, reliability, and cost

Screenshots add image files to the run and artifact upload, so job time and storage depend on how many captures are produced and their dimensions. Failure-only capture limits volume compared with taking images at every step. Keep named screenshots focused on states that help diagnose failures.

Cypress describes screenshot capture as taking around 100 ms; this is approximate documentation guidance, not a performance guarantee. CI artifact upload time depends on image count, file size, network conditions, and provider behavior. Artifact cost and retention limits are provider- and account-specific, so verify them in your CI plan.

Reliability comes from collecting after the test process and making artifact upload run despite test failure. For the most useful diagnosis, preserve the Cypress logs and test result context alongside screenshots where your CI or Cypress Cloud workflow supports them.

Or skip the browser setup

If you need screenshots of the site under test outside the Cypress run, ScreenshotNeo provides a website screenshot API and MCP server. It does not replace Cypress’s test failure artifacts; it is a separate way to capture a URL without managing a browser for that capture.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for the request 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, and paid plans start at $5 for 3,000. Learn more at ScreenshotNeo, or sign up free.

FAQ

Does Cypress make a ZIP archive automatically?

No. Cypress writes image files into a folder; your CI artifact feature or Cypress Cloud provides retention and browsing.

Can I archive screenshots from Cypress open?

You can take explicit screenshots with cy.screenshot(), but automatic failure screenshots are a cypress run behavior.

Should I set `trashAssetsBeforeRuns` to false?

Usually only when your workflow intentionally manages files across runs. Otherwise keep cleanup enabled and archive each run separately to avoid stale captures.

How long will Cypress Cloud keep screenshots?

Retention is account and plan dependent. Check the current settings for the account that stores the recorded runs.