## TL;DR

CI-only failures come from environment differences, not from the tests being wrong. Diff the environments systematically: base URL, test data, parallelism, viewport, and browser version, then reproduce the CI conditions locally with the same container image.

## Error

```text
Cypress run exits with code 1 in CI; the same spec passes with `cypress open` locally.
(No single error string; the failing spec varies run to run.)
```

## Steps

1. Run the exact CI command locally, including the same browser in headless mode: `npx cypress run --browser chrome`. Expected: reproduces some CI-only failures immediately.
2. Run inside the CI container image locally with docker. Expected: eliminates "works on my machine" environment drift.
3. Check for parallelism issues: run the failing spec alone in CI (`--spec`). Expected: if it passes alone, the cause is cross-spec interference (shared DB, ports, files).
4. Compare test data URIs CI often seeds a different dataset. Dump the seed counts in both environments. Expected: row counts match; if not, the seed step differs.
5. Check the browser version Cypress used in CI logs versus local. Expected: identical major versions; a mismatch explains rendering and timing differences.

## When to use

- Green locally, red in CI, with no code change between the two.
- Failures move between specs from run to run.

## When not to use

- The failure reproduces locally (debug it locally; faster).
- CI fails at install or verify time (environment setup issue).

## Tool compatibility

- Cypress 10 through 14; any CI provider; docker for local reproduction.

## Variant phrasings

### Cypress passes headed but fails headless

Headless rendering and timing differ; treat as an environment difference, not a test bug.

### Cypress fails only with --record --parallel

Parallel runners share state; look for cross-spec interference.

## Why it happens

Local and CI differ in CPU count, memory, screen size, fonts, timezone, seeded data, and network speed. Tests that depend on any of these implicitly fail only where the assumption breaks.

## Edge cases

- Timezone differences break date-sensitive tests; pin `TZ` in CI and locally.
- Font rendering differs between macOS and Linux CI; visual tests need platform-specific baselines.
- CI machines are slower; timeouts tuned on a fast laptop fail under load. Tune timeouts on CI timings.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_r5dxXCMTrHOGHfCBSOXbHA