Cypress cy.intercept Best Practices for Flaky Tests

Strict Route Matching & Specificity #

Overly broad glob patterns (**/api/**) cause route collisions and unpredictable mock resolution. Always define explicit HTTP methods and exact URL paths. Use regular expressions or req.query inspection for dynamic segments. Avoid chaining multiple intercepts on identical routes without times constraints to prevent non-deterministic fallbacks. For complex routing, consult Cypress Network Interception Patterns to map mocks to microservice boundaries.

Alias Binding & Wait Synchronization #

Flakiness typically occurs when cy.wait('@alias') executes before the network request dispatches. Bind aliases immediately after cy.intercept(), then trigger the UI action. Replace arbitrary cy.wait(2000) delays with Cypress’s automatic retry mechanisms and response assertions. Apply cy.intercept({ times: 1 }) for single-use endpoints to prevent stale mock data from contaminating subsequent assertions.

Response Lifecycle & Payload Control #

Intercept handlers must explicitly call req.reply() or req.continue() to prevent request hangs. Validate fixture structures against OpenAPI contracts before injecting complex JSON payloads. Use req.reply({ statusCode: 200, body: fixture }) for deterministic scenarios. Modify req.body or req.headers in-flight for dynamic cases instead of relying on external services. Verify mocked response shapes match frontend expectations to prevent silent UI failures.

Test Isolation & State Cleanup #

Global intercepts in support/e2e.js or cypress.config.js persist across files and cause cross-test pollution. Define route mocks inside beforeEach() or at the spec level to guarantee clean state. Use cy.intercept().as('alias') within pre-test hooks. Implement environment-specific routing when sharing base URLs to prevent staging mocks from executing in production-like CI pipelines.

Configuration & Implementation Snippets #

Deterministic Alias Wait Pattern #

cy.intercept('POST', '/api/v1/checkout', { fixture: 'checkout-success.json' }).as('checkoutReq');
cy.get('[data-testid=pay-button]').click();
cy.wait('@checkoutReq').its('response.statusCode').should('eq', 200);

Binds the alias before the triggering action, waits for the exact network call, and asserts status without arbitrary delays.

Strict Method & Path Matching #

cy.intercept({ method: 'GET', url: '/api/users?role=admin' }, { fixture: 'admin-users.json' }).as('getAdmins');

Prevents accidental interception of similar endpoints by enforcing exact HTTP method and query parameter matching.

Dynamic Payload Modification #

cy.intercept('GET', '/api/config', (req) => {
 req.reply((res) => {
 res.body.featureFlags.darkMode = true;
 res.send();
 });
}).as('getConfig');

Intercepts live responses and mutates specific fields without overriding the entire payload, reducing maintenance overhead.

Common Pitfalls & Resolutions #

• Late Intercept Binding: Define cy.intercept() before any UI interaction that triggers the network call. Cypress cannot retroactively capture requests that fire before the route is registered.
• Reusing Aliases Across Tests: Aliases reset per test. Never assume @alias persists between it() blocks. Re-declare intercepts in beforeEach() or at the top of each spec.
• Over-Mocking Third-Party CDNs: Avoid intercepting analytics, font, or CDN requests unless explicitly testing failure states. Unnecessary mocks increase execution time and introduce false positives.
• Ignoring Request Timing in CI: CI runners have variable latency. Replace cy.wait() with cy.intercept() response assertions and leverage Cypress’s built-in retry-ability for DOM and network states.

Frequently Asked Questions #

How do I fix ‘cy.wait() timed out waiting for @alias’? Verify the intercept registers before the request fires. Check for exact URL/method matches, ensure the alias isn’t overwritten, and confirm the frontend dispatches the request. Use the Cypress DevTools network tab to validate timing.

Should I mock all network requests in Cypress? No. Mock only external dependencies, third-party APIs, and non-deterministic services. Keep internal API calls real when testing data flow integrity, but use intercepts to assert payloads and handle edge cases.

How does cy.intercept handle concurrent identical requests? Cypress queues intercepts in registration order. Without times constraints, the last matching intercept wins. Use times: 1 or unique aliases per request to isolate concurrent calls and prevent race conditions.

Reliability Targets #

• Target flakiness rate: <0.5%
• Intercept binding success rate: 100%
• CI pass consistency threshold: >99.5%
• Average test execution time impact: <5% overhead vs real network
• False positive reduction target: Eliminate timing-based assertions entirely