CI Resource Contention & Headless Mode Differences #
CI runners operate with constrained CPU, memory, and network bandwidth compared to local machines. Headless Chrome executes rendering and JavaScript differently than headed mode, exposing timing vulnerabilities. Mitigate this by configuring appropriate CI resource limits and enabling experimentalMemoryManagement. Disable heavy UI animations during execution to reduce rendering overhead.
Unhandled Async State & Network Timing #
Cypress commands auto-retry, but application state updates often lag behind network responses. When API payloads arrive out of order or hydration completes unpredictably, assertions fire prematurely. Proper Async State Management in E2E Tests requires explicit waiting on network responses via cy.intercept(). Avoid arbitrary cy.wait() timeouts, as they introduce non-deterministic delays.
Parallel Execution & Test Isolation Leaks #
Running specs in parallel without strict isolation causes shared state pollution across cookies, localStorage, and IndexedDB. Cypress resets state between specs, but custom plugins or unstubbed third-party scripts can bypass this mechanism. Enforce testIsolation: true in your configuration and clear browser context explicitly in beforeEach. Eliminate cross-spec dependencies to guarantee deterministic execution.
DOM Mutation Races & Virtual DOM Batching #
Modern frameworks batch DOM updates for performance, causing Cypress to query stale or detached nodes. If an element re-renders mid-assertion, Cypress throws a detached DOM error. Use stable selectors like data-cy and leverage Cypress’s built-in retry mechanisms. Never query elements immediately after navigation without waiting for the framework to settle.
Configuration & Code Solutions #
Stabilize Network Intercepts #
cy.intercept('GET', '/api/data', { fixture: 'stable-payload.json' }).as('getData');
cy.visit('/dashboard');
cy.wait('@getData');
cy.get('[data-cy=row]').should('have.length', 5);Deterministic network stubbing eliminates latency-induced flakiness and ensures predictable UI rendering.
Optimize CI Configuration #
export default defineConfig({
retries: { runMode: 2, openMode: 0 },
video: true,
screenshotOnRunFailure: true,
testIsolation: true,
defaultCommandTimeout: 8000
});Configures automatic retries, enforces isolation, and extends timeouts to accommodate CI resource constraints.
Common Pitfalls #
- Using hardcoded
cy.wait()instead of waiting on network aliases - Relying on visual DOM order rather than semantic
data-cyattributes - Disabling
testIsolationto speed up execution, causing state leakage - Ignoring headless vs headed rendering differences in CI pipelines
- Failing to stub or mock third-party analytics and tracking scripts
FAQ #
Why do my Cypress tests pass locally but fail intermittently in CI? CI environments typically have lower CPU/memory allocation, different network latency profiles, and run browsers in headless mode. These factors expose unhandled async races and resource contention that local machines mask.
How do I fix detached DOM errors in Cypress CI runs? Detached DOM errors occur when the application re-renders an element while Cypress is querying it. Use stable selectors, wait for network responses to complete before asserting, and avoid chaining commands across navigation boundaries.
Should I increase defaultCommandTimeout to fix flaky tests? No. Increasing timeouts only masks underlying race conditions. Instead, implement explicit waits on network intercepts, enforce test isolation, and verify that application state updates are fully resolved before assertions.
Reliability Metrics #
Track these metrics to quantify and reduce flakiness across pipelines:
- Flakiness Rate: Percentage of tests failing on first run but passing on retry (Target: <2%)
- Retry Success Rate: Ratio of passed tests after automatic retries vs initial failures
- CI Execution Variance: Standard deviation of test suite duration across 10+ CI runs
- Test Isolation Pass Rate: Percentage of specs passing when run independently vs in parallel