skip to content

In Cypress 16, what does `videoCompression` change about a spec's saved video?

level: middleimportance: nice to knowfreq 24%

answer

  1. It is a quality number, not a switch
  2. Off by default, so nothing is re-encoded
  3. true maps to a specific CRF value
  4. Lower number, better picture, bigger file
  5. Chapter markers are written while encoding

basics

~20 s

It sets the Constant Rate Factor used to encode the recording. It defaults to false, which skips encoding and leaves a larger file. True means CRF 32; a number from 1 to 51 sets the CRF, where lower means better quality.

solid answer

~40 s

`videoCompression` is the quality knob for the encoding pass Cypress runs after a spec's recording is captured. It defaults to `false`, which skips that pass completely: the `.mp4` is written as captured, so the file is larger but nothing has to be re-encoded. Setting it to `true` coerces the value to a CRF of 32; setting a number between 1 and 51 uses that CRF directly, and a lower number means better quality and a larger file. One side effect surprises people: Cypress embeds a chapter marker for each test attempt into the `.mp4`, and chapters are written **only** during encoding — so with compression at its default, the video has none. `videoCompression` does not decide whether a video exists at all; `video` does.

code

javascript · 14 lines
javascript
// cypress.config.js
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // record a video per spec (off by default)
  video: true,
  // encode at CRF 15: sharper than `true` (CRF 32), larger file,
  // and the encoding pass is what writes per-test chapter markers
  videoCompression: 15,
  videosFolder: 'cypress/videos',
  e2e: {
    specPattern: 'cypress/e2e/tickets/**/*.cy.js',
  },
})

go deeper

for a junior

Know that this option is about video quality and size, and that a separate option decides whether a video is recorded at all.

for a middle

Explain the CRF scale, what true and false each mean, and why chapters exist only when the encoding pass runs.

for a senior

Be ready to pick a value for a specific runner, and to say what you would check when a recording comes back unreadable.

for a principal

Decide whether spec recordings are worth keeping in your pipelines at all, and what the alternative gives a reviewer instead.

## What the option actually sets `videoCompression` is not a boolean switch dressed up as a number — it is the **Constant Rate Factor (CRF)** handed to the encoder that runs after a spec's video has been captured. | Value | What Cypress does | |---|---| | `false` or `0` | Skips the encoding pass entirely; the recording is written as captured | | `true` | Encodes at CRF 32 | | `1`–`51` | Encodes at that CRF — lower means better quality and a larger file | The default is **`false`**. In Cypress 16 the TypeScript type definitions were corrected to say so: they had documented a default of `32`, while the runtime behaviour has been to skip compression. ## Why the default is "off" Skipping the pass means the file lands as soon as the spec finishes and nothing is re-encoded. Turning compression on inserts a processing step between one spec and the next, which is visible in the run output as a gap after a long spec while the encoder works. That trade — a bigger file now against processing time then — is the whole of the option. A practical way to reason about the number: - If the machine encodes slowly, which is common on small CI containers with few cores, **raise** the CRF. Less work, smaller file, coarser picture. - If the recording is too blurry to read the ticket queue's status column, **lower** the CRF. More work, larger file, sharper picture. - `DEBUG=cypress:server:video` prints the encoder's settings and messages if you want to see what the pass is actually doing. ## The chapter markers, and why they vanish While encoding, Cypress embeds **chapter markers** into the resulting `.mp4` — one for each test attempt in the spec. Each chapter is titled with the test's full title, including the titles of the suites it sits in, and a test retried three times contributes three chapters. Players that understand chapters — VLC, QuickTime and IINA among them — then let you jump straight to a test instead of scrubbing through a twenty-minute recording of an entire support-ticket suite. The catch follows directly from where the markers are written: 1. Chapters are written **during** the encoding pass. 2. The encoding pass only runs when compression is enabled. 3. `videoCompression` defaults to `false`. So the default configuration produces a chapterless video, and "my Cypress video has no chapters" is almost always "I never turned compression on". To get them you need both `video: true` and `videoCompression` set to `true` or a CRF number; `false` or `0` skips encoding and therefore skips the markers. ## What the option does not control - **Whether anything is recorded.** That is `video`, which defaults to `false`. With no recording there is nothing to compress. - **Where the file goes.** That is `videosFolder`, `cypress/videos` by default, and it is emptied before each `cypress run` while `trashAssetsBeforeRuns` is on. - **How many files there are.** Cypress records one video per **spec file**, in `cypress run` only; compression changes the size of each one, not their number. - **What is in frame.** There is no video equivalent of the screenshot `capture` option, and `blackout` selectors do not apply to a recording. ## Saying it well in an interview - Name it as a CRF, not as an on/off flag — that is the detail that shows you have actually configured it. - State the default correctly: compression off, so the file is bigger and no chapter markers exist. - Mention that `true` means 32, since that is the value nearly everyone quotes as the default. - Say what you would tune it for on a small CI container, and what you would look at first if the recording were unreadable.

  • Your Cypress spec video has no per-test chapter markers. Why?
    Because `videoCompression` is at its default of `false`, so the encoding pass is skipped, and the markers are only embedded during encoding. Set `videoCompression` to `true` or to a CRF number alongside `video: true` and each test attempt gets its own titled chapter.
  • What does setting `videoCompression: 51` instead of `15` do?
    51 is the coarsest end of the CRF scale: much less encoding work and a much smaller file, at visibly worse quality. It is the direction to move on a CPU-starved runner; 15 is the direction to move when the recording is too blurry to read.

saying these in an interview costs you the question

  • States the default as 32 rather than false
  • Treats videoCompression as the switch that records video
  • Says a lower CRF produces a smaller file
  • Expects chapter markers with compression disabled
  • Thinks compression changes what is in frame