Cypress Network Interception Patterns

Core Interception Architecture & Setup #

The foundation of deterministic testing relies on precise route matching and response aliasing. Implementing Cypress cy.intercept Best Practices for Flaky Tests ensures that network calls are captured synchronously, eliminating race conditions between UI rendering and data fetching. Configure intercepts at the beforeEach lifecycle to guarantee clean state isolation and prevent cross-test pollution.

Implementation Context (cypress.config.ts):

// cypress.config.ts
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    retries: { runMode: 2, openMode: 0 },
    // chromeWebSecurity: false is only needed when testing cross-origin iframes
    // or when your app loads resources from a different origin than baseUrl.
    // Do not disable it globally; it weakens browser security guarantees.
  },
});

Trade-offs: Global intercepts in support/e2e.ts reduce boilerplate but increase memory overhead and risk state leakage in parallel runners. Test-scoped intercepts (beforeEach) are safer for distributed CI execution but require stricter fixture management.

Dynamic Payload Manipulation & Stateful Mocking #

Static fixtures often fail to capture complex user journeys. By leveraging dynamic request handlers, engineers can mutate payloads in-flight based on test context. For GraphQL endpoints, parse req.body.operationName to identify the query and return operation-specific mock data without violating type contracts.

Production-Ready Example (cypress/e2e/checkout.spec.cy.ts):

// cypress/e2e/checkout.spec.cy.ts
describe('Checkout Flow', () => {
  beforeEach(() => {
    cy.intercept('POST', '/api/v1/checkout', (req) => {
      // Validate payload structure before mutating
      if (req.body.items?.length > 0) {
        req.reply({
          statusCode: 200,
          headers: { 'Content-Type': 'application/json' },
          body: {
            ...req.body,
            status: 'mocked_success',
            transactionId: `txn_${Date.now()}`,
            estimatedDelivery: new Date(Date.now() + 86400000).toISOString()
          }
        });
      } else {
        req.reply({ statusCode: 400, body: { error: 'Empty cart' } });
      }
    }).as('checkoutRequest');
  });

  it('processes checkout deterministically', () => {
    cy.get('[data-testid="checkout-btn"]').click();
    cy.wait('@checkoutRequest').its('response.statusCode').should('eq', 200);
  });
});

CI Pipeline Impact: Dynamic handlers eliminate backend dependency during load testing, reducing average test execution time significantly. The trade-off is increased maintenance overhead when API contracts change, necessitating automated schema validation.

CI/CD Pipeline Integration & Cross-Framework Alignment #

Reliable network interception must scale across execution environments. When migrating or maintaining polyglot test suites, aligning Cypress interception logic with Playwright Route Mocking Strategies creates a unified abstraction layer for QA teams. Furthermore, integrating API Contract Validation in E2E Tests directly into your mock handlers prevents schema drift from silently passing in CI, ensuring frontend expectations match backend specifications.

Environment-Aware Fixture Routing (cypress/support/e2e.ts):

// cypress/support/e2e.ts
// Register a global intercept that selects the correct fixture based on environment.
// Note: cy.intercept() in support files applies to all specs. Scope carefully.
before(() => {
  const isCI = Cypress.env('CI') === 'true';
  const fixturePath = isCI ? 'ci-mocks/products.json' : 'dev-mocks/products.json';
  cy.intercept('GET', '/api/products', { fixture: fixturePath });
});

CI Workflow Context (.github/workflows/ci.yml):

# .github/workflows/ci.yml
- name: Run Cypress E2E
  run: npx cypress run --env CI=true
  env:
    CYPRESS_BASE_URL: ${{ secrets.CI_BASE_URL }}
    CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}

Trade-offs: CI-specific fixture routing guarantees environment parity but requires strict version control of mock data.

Scaling to Distributed Systems & Microservices #

Monolithic stubbing breaks down when frontend applications consume dozens of independent services. Use wildcard routing, conditional response logic, and centralized fixture registries to maintain test velocity without sacrificing architectural fidelity.

Architectural Considerations:

• Wildcard Routing: Use cy.intercept('GET', '/api/v1/**') to catch service mesh traffic, but pair with strict req.headers validation to avoid over-matching.
• Centralized Registry: Store mocks in a versioned JSON schema repository. Inject via cy.fixture() to enable contract testing pipelines.
• Parallel Execution Safety: Avoid global cy.intercept() in support files when using Cypress Cloud parallelization. Scope intercepts to individual spec files to prevent race conditions across worker nodes.

Common Pitfalls & Engineering Mitigations #

Measurable Reliability Metrics & KPIs #

Track these metrics to quantify the ROI of network interception patterns in your CI/CD pipeline:

Frequently Asked Questions #

When should I use cy.intercept over cy.route? cy.route was removed in Cypress 12. Use cy.intercept, which provides full control over request and response lifecycles, supports dynamic handlers, and handles all HTTP methods including preflight requests.

How do I prevent mocked responses from caching in CI? Append a cache-busting query parameter to intercepted routes during CI execution, or set Cache-Control: no-store in the mock response headers. Cypress itself does not cache intercept responses between tests.

Can cy.intercept handle WebSocket traffic? No. cy.intercept only captures HTTP/HTTPS traffic. For real-time communication, use dedicated WebSocket mocking utilities or libraries designed for socket interception, such as mock-socket.

Related guides #

• Network & API Mocking for Reliable Tests
• Cypress cy.intercept Best Practices for Flaky Tests
• Aliasing and Waiting on cy.intercept Requests
• Playwright Route Mocking Strategies