How to Run Cypress in CI Without Verification Failures

Cypress downloads a separate binary at install time and needs a set of Linux libraries to launch its bundled Electron browser.

The npm package and the Cypress binary are separate. In CI you must let the binary download (or restore it from cache) and provide the GTK/X11 libraries its Electron shell needs.

Why it fails in CI

The Cypress binary cache is empty and the download is blocked/slow → "verification timed out".
Missing Linux libs (libgtk, libgbm, libnss3, xvfb) → the browser will not start.
You cached node_modules but not ~/.cache/Cypress, so the binary is gone.

Install and run it reliably

Install the OS dependencies, install the binary, verify it, then run headless. Cache the Cypress binary directory separately from node_modules.

Terminal

apt-get update && apt-get install -y \
  libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev \
  libnss3 libxss1 libasound2 libxtst6 xauth xvfb

npm ci
npx cypress verify
npx cypress run

Cache & speed

Cache ~/.cache/Cypress keyed on the Cypress version so the binary is not re-downloaded. The binary download is a known flaky step; auto-retry on transient failures and larger managed runners help.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.cache/Cypress
    key: cypress-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}

Common errors

Cypress verification timed out → restore the binary cache or raise CYPRESS_VERIFY_TIMEOUT.
Cypress failed to start ... missing dependency → install the GTK/NSS/Xvfb libs above.
The Cypress App could not be downloaded → transient network; retry the install.

Key takeaways

Cache ~/.cache/Cypress separately so the binary survives runs.
Install the GTK/NSS/Xvfb libraries in slim images.
Run cypress verify before cypress run to surface issues early.