ScreenshotNeo
Sign in Get a free key

BlogHow-to

How to Record Cypress Test Videos Manually

Enable Cypress video capture, save per-spec recordings, tune compression, and troubleshoot local and Cloud workflows.

By the ScreenshotNeo team1 October 20267 min read

Direct answer: set video: true in your Cypress configuration, then run npx cypress run. Cypress creates one video per spec file in cypress/videos by default. Video recording is a cypress run workflow; it does not record while using cypress open.

This guide shows the complete local workflow, selective spec recording, output retention, compression, CI usage, and the difference between local files and Cypress Cloud.

1. Enable video recording

For current Cypress projects, put the setting in cypress.config.js (CommonJS) or cypress.config.ts/cypress.config.mjs (TypeScript or ESM).

CommonJS

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  video: true,
})

TypeScript or ESM

import { defineConfig } from 'cypress'

export default defineConfig({
  video: true,
})

Cypress’s documented default is false, so an explicit setting is required. See the official screenshots and videos guide and configuration reference.

2. Run the tests that produce the video

Install Cypress in the project if it is not already present, then run the test suite in run mode:

npm install --save-dev cypress
npx cypress run

The command runs headlessly by default and records a separate video for each spec file. To record one spec while iterating:

npx cypress run --spec "cypress/e2e/checkout.cy.js"

You can use a visible browser with --headed when debugging, but video capture still comes from cypress run:

npx cypress run --headed --spec "cypress/e2e/checkout.cy.js"

The relevant CLI options are documented in Cypress’s command-line reference.

3. Find and keep the generated files

After the run, inspect:

cypress/videos/

Each spec normally has a matching video filename. Change the destination with videosFolder:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  video: true,
  videosFolder: 'artifacts/cypress-videos',
})

Be careful when rerunning. trashAssetsBeforeRuns defaults to true; Cypress clears the contents of the downloads, screenshots, and videos folders before a run, including nested folders and unrelated files placed there. Preserve artifacts outside those folders or disable cleanup:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  video: true,
  trashAssetsBeforeRuns: false,
})

Keeping cleanup enabled is usually safer for reproducible CI jobs. If you disable it, use unique artifact directories or a separate cleanup step so old recordings are not mistaken for the current run.

4. Choose video compression and chapters

The current configuration reference sets videoCompression to false by default. With compression off, Cypress avoids the extra encoding work and writes the uncompressed recording. Compression can reduce file size but increases processing time and can reduce quality.

Valid values are false, 0, or a CRF value from 1 through 51. Lower CRF values preserve more quality and create larger files. Setting true uses CRF 32.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  video: true,
  videoCompression: 32,
})

Compressed videos can contain chapter markers for test attempts. Cypress documents support for navigating those chapters in VLC, QuickTime, and IINA. Chapters require both video: true and a nonzero compression setting; compression set to false or 0 produces no chapters.

Practical choices

  • Local debugging: leave compression off when you want the quickest feedback.
  • CI artifacts: choose a CRF after checking your artifact-storage limit and acceptable image quality.
  • Long suites: compression saves storage, but budget additional CPU time after each spec.
  • Attempt navigation: enable compression so supported players can use chapter markers.

5. A complete project example

This example enables recording, stores files in a dedicated artifact directory, and uses moderate compression:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  video: true,
  videosFolder: 'artifacts/cypress-videos',
  videoCompression: 32,
  e2e: {
    baseUrl: 'http://localhost:3000',
    setupNodeEvents(on, config) {
      return config
    },
  },
})

Run it with:

npm run cy:run

# package.json
{
  "scripts": {
    "cy:run": "cypress run",
    "cy:run:checkout": "cypress run --spec cypress/e2e/checkout.cy.js"
  }
}

6. CI workflow: retain the video as an artifact

Run Cypress in your CI job and configure the CI provider to upload artifacts/cypress-videos/** after the command finishes. Upload videos on failure at minimum; upload every spec when you need a complete audit trail.

A generic shell sequence is:

npm ci
npm run build
npm run start:test &
npx cypress run
# Configure your CI system to archive artifacts/cypress-videos/

Make sure the artifact-upload step runs even when Cypress exits with a failing status. Otherwise the most useful recording can be discarded precisely when a test fails. Keep the application URL, browser version, commit SHA, and spec name alongside the video so a recording can be reproduced.

7. Local recording versus Cypress Cloud

Workflow Setup Evidence location Use it when
Local video file video: true, then cypress run Your configured videosFolder You need a file to inspect or archive locally
Cypress Cloud run Set up the project, then use cypress run --record with a project record key Cypress Cloud You need hosted run history and Cloud debugging features

Local recording does not require Cypress Cloud. The Cypress FAQ states that cypress run without --record does not communicate with Cypress’s external servers or record results. Cloud recording is an explicit opt-in:

CYPRESS_RECORD_KEY=your-record-key npx cypress run --record

Cloud-recorded runs can include test results, definitions, configuration excluding Cypress environment variables, screenshots, videos, standard output, and CI or Git environment data. Review Cypress’s data storage and controls before enabling it. Controls such as deleting videos before upload, --no-runner-ui, and suppressing selected command-log entries address different captured data; none is a blanket guarantee that every value is withheld.

When Test Replay is enabled, the Runner UI is hidden by default in the recording. Pass --runner-ui if it should appear. Cypress also documents that videoUploadOnPasses was removed; to avoid uploading successful-spec videos, delete them after the run according to the current CLI guidance.

8. Troubleshooting

No video appears

  • Cause: video is still false or the command was cypress open.
  • Fix: set video: true and run npx cypress run.

The video is in a different directory

  • Cause: videosFolder overrides the default.
  • Fix: inspect the configured path or remove the override; the default is cypress/videos.

Older videos disappeared after a rerun

  • Cause: trashAssetsBeforeRuns: true clears the asset folders before each run.
  • Fix: copy recordings elsewhere before rerunning or set it to false.

CI reports a failed test but has no recording

  • Cause: the artifact step did not run after Cypress returned a failure.
  • Fix: mark video upload as an always-run or post-job step and archive the configured folder.

Files are too large

  • Cause: compression is disabled or the CRF is too low.
  • Fix: set videoCompression to a CRF such as 32, then compare quality and processing time.

Compression takes too long

  • Cause: encoding adds CPU work after the test.
  • Fix: use false for local iteration, compress only in CI, or choose a higher CRF.

Cloud recording fails

  • Cause: --record was used without project setup or a valid record key.
  • Fix: complete Cloud project setup and provide the key through CYPRESS_RECORD_KEY; omit --record for local-only capture.

9. Performance, reliability, and cost notes

  • Runtime: recording adds video-writing work during the run; compression adds additional post-run CPU time.
  • Storage: estimate one file per spec and retain only the runs your debugging or audit policy requires.
  • Reliability: use a dedicated output directory, preserve artifacts after failures, and record the commit and browser details beside each file.
  • Repeatability: pin the Cypress version in your lockfile and use the same viewport, browser, and environment in CI.
  • Cost: local video capture needs no recording hardware or Cloud account. Cloud introduces a separate hosted workflow and data-retention decision.

10. Or skip the browser setup

If you need a screenshot of the application or a test result rather than a time-based test recording, ScreenshotNeo returns a clean image or PDF from one request. Its consent step accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for the full option list.

cURL

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

Python

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)

Node.js

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(`${res.status} ${res.statusText}`)
const fs = await import('node:fs/promises')
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()))

Every plan includes the capture features: full-page and element shots, device presets and custom viewports, retina scale, dark mode, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, resizing, caching, signed links, asynchronous jobs, webhooks, bulk capture, usage reporting, and PDF options. The free plan includes 1,000 shots each month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Does Cypress record while I use the interactive runner?

No. Cypress documents that videos are not recorded during cypress open. Use cypress run.

Is one video created for every test?

Cypress records one video per spec file, not one separate file per test.

Do I need Cypress Cloud for local videos?

No. Local capture works without --record or a Cloud record key.

Can I record only one spec?

Yes. Pass its path to --spec, for example npx cypress run --spec "cypress/e2e/login.cy.js".

Why would I enable compression?

Compression reduces artifact size and can add chapter markers, at the cost of encoding time and potentially lower image quality.

Keep reading

7 min read

Full-Page Capture Chrome Plugin

Capture an entire webpage in Chrome with extensions, understand their limits, and automate clean full-page screenshots with ScreenshotNeo.

7 min read

Facebook Open Graph Debugger

Use Facebook’s Open Graph debugger to refresh stale link previews, verify metadata, and fix incorrect titles, descriptions, and images.