How to Record Test Artifacts from Any CI Provider in Cypress

Short answer: Cypress creates screenshots and, when enabled, videos inside the CI job. To keep them after the job ends, configure your CI provider to upload the generated folders as job artifacts, including when tests fail. Cypress uses cypress/screenshots and cypress/videos by default.

This guide shows how to enable and locate the files, wire artifact retention into a job, adapt the pattern across CI providers, and troubleshoot missing output.

1. Configure Cypress to create the evidence you need

During cypress run, Cypress automatically takes screenshots when a test fails unless screenshot capture is disabled. You can also take a screenshot explicitly with cy.screenshot(). Video recording is disabled by default; enable it with video: true. The runner writes screenshots and videos to cypress/screenshots and cypress/videos by default. See the Cypress configuration reference and screenshot command documentation.

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

module.exports = defineConfig({
  video: true,
  screenshotOnRunFailure: true,
  screenshotsFolder: 'cypress/screenshots',
  videosFolder: 'cypress/videos',
});

These are the default output folder names, written explicitly here so the CI upload paths are easy to match. If your configuration already sets these options, retain its existing values. You can set video: false to avoid video files, or set screenshotOnRunFailure: false if failure screenshots are not wanted. To capture one deliberately during a test:

it('shows a manual screenshot in the run output', () => {
  cy.visit('/');
  cy.screenshot('home-page');
});

Before choosing video, decide whether replaying the sequence leading to a failure is useful enough to justify the storage and upload volume. Screenshots may be sufficient when a static failure state is enough. Cypress clears the screenshots and videos folders before a run by default. Treat the folders as that run’s generated output; do not rely on previous files remaining there.

2. Understand generation versus retention

Cypress writes files to the job workspace. That alone does not preserve them: the CI provider must upload or retain those paths before the workspace is discarded. Configure the provider’s native artifact feature and make sure its upload step runs even if Cypress exits with a test failure. Cypress supports CI environments including GitHub Actions, CircleCI, GitLab CI, Jenkins, and AWS CodeBuild, but the provider configuration syntax differs. See the Cypress CI overview.

Run Cypress in the job with the command your project uses, commonly npx cypress run.
Confirm the configured screenshot and video output folders.
Upload those folders using the CI provider’s artifact mechanism, with failure-safe behavior.
Open a completed job and verify that the artifact can be downloaded or browsed.

3. GitHub Actions example

Use the official Cypress GitHub Action or your existing install and run steps. The important retention detail is that the upload action must execute after a failed test step. if: always() asks GitHub Actions to run the artifact upload step regardless of earlier step outcomes. This example uses the official upload-artifact action; check the current action documentation for supported versions and options.

name: Cypress
on: [push, pull_request]
jobs:
  cypress:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - name: Run Cypress
        run: npx cypress run
      - name: Upload Cypress screenshots and videos
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: cypress-test-artifacts
          path: |
            cypress/screenshots/**
            cypress/videos/**
          if-no-files-found: ignore

If you configure non-default folders in cypress.config.js, update the artifact paths. If the workflow has separate jobs, GitHub documents using upload-artifact and download-artifact to pass files between jobs; see the Cypress GitHub Actions guide.

4. GitLab CI example

GitLab job artifacts can preserve the generated directories. Cypress’s documented pattern uses when: always so artifacts are collected regardless of job result. Adjust the paths if you changed the Cypress output folders.

cypress:
  image: cypress/browsers:latest
  script:
    - npm ci
    - npx cypress run
  artifacts:
    when: always
    paths:
      - cypress/videos/**/*.mp4
      - cypress/screenshots/**/*.png

See Cypress’s GitLab CI guide and GitLab job artifacts documentation. Set an appropriate artifact expiration policy using your project’s GitLab configuration and requirements; retention duration is not universal.

5. Adapt the setup to another CI provider

For CircleCI, Jenkins, AWS CodeBuild, or another provider, the steps are the same in principle: run Cypress, then configure that service’s current artifact upload or preservation feature to include the actual output folders. Consult its official documentation for YAML or UI syntax, failure behavior, retention period, size limits, access controls, and how to download artifacts. Those details vary by service and configuration, so do not copy another provider’s artifact syntax as if it were interchangeable.

Check	What to configure or verify
Paths	Include the configured screenshots folder and, if enabled, videos folder.
Failure behavior	Ensure artifact upload runs when the Cypress command fails.
Retention	Choose a duration that meets debugging and data-handling needs; check provider policy and project settings.
Limits	Check file-size, total storage, and upload limits for the selected provider.
Access	Confirm who can view and download artifacts, especially for pull requests from forks.
Cross-job use	If another job needs the files, configure artifact download or dependency behavior explicitly.

Generated screenshots and videos are usually excluded from source control because Cypress regenerates them. Job artifacts provide a separate persistence mechanism; committing generated output should not be the default. See Cypress’s test organization guidance.

6. Choose provider artifacts or Cypress Cloud

Provider-managed artifacts keep files with the job or build in your CI service. They are a direct fit when your team wants to retrieve the output from the completed job and already manages CI access there. Check retention, storage limits, sharing, and failure handling for your provider.

Cypress Cloud is an optional hosted service for recording runs and browsing test results with associated screenshots and videos. It can make run review and sharing more convenient, while introducing a separate hosted data destination. Review your organization’s data-handling requirements and the applicable retention period and plan terms before using it. The available retention period depends on the applicable terms; there is no single duration to assume. See the Cypress Cloud recorded runs documentation.

Teams can use both if they have a reason to keep a CI copy and a Cloud record. Decide based on retrieval workflow, access controls, retention needs, and storage policy rather than enabling duplicate storage automatically.

7. Troubleshooting missing or incomplete artifacts

Symptom	Likely cause	Fix
No screenshot after a failure	The test ran with `cypress open`, screenshot capture was disabled, or the failure occurred before Cypress could capture a page.	Confirm CI uses `cypress run`, check `screenshotOnRunFailure`, and inspect the job log for the actual failure stage. Use `cy.screenshot()` for a deliberate capture when appropriate.
No video files	Video recording is off by default.	Set `video: true` in the Cypress configuration used by CI and confirm that the browser/run supports the configured mode.
Artifact step reports no files	The upload path does not match the configured folder, the run produced no files, or an earlier cleanup removed output.	Check Cypress configuration and job workspace paths; list the directories after the run before uploading.
Files exist locally but disappear after CI	They were generated but never uploaded, or upload did not run after a failed test command.	Add the provider’s unconditional/failure-safe artifact behavior, such as `if: always()` in GitHub Actions or `when: always` in GitLab.
Only some files are retained	Artifact glob patterns omit nested files or one output type.	Use patterns covering the configured folders and check the provider’s glob syntax. Include screenshots and videos separately if needed.
Upload fails or is too large	Video output increases artifact size, or a provider limit, quota, or permission applies.	Check the provider error and storage policy. Disable video if replay is not needed, reduce how many jobs upload it, or adjust retention and access according to your policy.
Artifacts are unavailable to a later job	Artifact upload does not automatically make files available across all jobs.	Configure the provider’s download/dependency step and use the matching artifact name or build reference.

8. Performance, reliability, and cost considerations

Video adds output and upload work. Enable it when replay is valuable. If storage or upload time matters, begin with failure screenshots and add video for workflows where it helps.
Uploads must survive test failure. Verify the provider’s step or job conditions rather than assuming later steps run after a nonzero test exit.
Retention and quotas are provider-specific. Check limits and cleanup policies before depending on long-term availability.
Artifacts contain page content. Screenshots and recordings may capture sensitive test data. Restrict access and choose a retention policy consistent with your data rules.
Folder cleanup is expected. Cypress clears screenshot and video folders before a run by default, which helps avoid mixing stale files with current output.

9. Or skip the browser setup

If you need a screenshot of a website as part of a test or documentation workflow, ScreenshotNeo provides a screenshot API and MCP server. This does not replace retaining Cypress failure screenshots or videos; it is an option for capturing a web page without managing a browser instance in your code.

See the ScreenshotNeo API documentation. One GET request returns an image or PDF; this example saves a WebP response:

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo returned ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for free and get 1,000 screenshots a month with no card.

10. FAQ

Can Cypress artifacts be retained if the test job fails?

Yes. Configure the provider’s upload step to run after a failed test command, then verify the artifact appears on a failed job.

Should I commit screenshots and videos to Git?

Usually no. Cypress regenerates these outputs; use CI artifacts or Cypress Cloud when you need them retained.

Does enabling video change where screenshots are saved?

No. Videos and screenshots use separate output folders by default: cypress/videos and cypress/screenshots.

How long will an artifact remain available?

That depends on the CI provider, project settings, and applicable service terms. Check the current policy for your selected setup.