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.

Matching Precisely Enough, and No More #

Most interception problems are matcher problems. A pattern that is too broad intercepts requests the test did not intend to control; one that is too narrow silently fails to match and the real request goes through, which produces a test that passes locally with a warm cache and fails in CI.

Three properties should be as specific as the behaviour requires. Method matters whenever an endpoint serves both reads and writes: a pattern without it will happily answer a POST with a list payload. Path specificity matters on any endpoint with variants — a matcher covering /api/invoices* will intercept /api/invoices/summary as well as the list, and whichever alias was registered first wins. Query parameters matter for anything paginated or filtered, since the response differs and the URL is the only thing distinguishing the calls.

The counter-pressure is that over-specific matchers break on harmless changes: a cache-busting parameter, an added analytics tag, a client version field in the body. The workable balance is to match on method plus path plus the query keys that change the answer, and to use a predicate for bodies where only some fields matter rather than a literal object.

// Specific enough to be unambiguous, loose enough to survive harmless additions.
// Trade-off: a predicate is more code than a literal match and it does not break
// when the client adds a version field to the body.
cy.intercept({
  method: 'POST',
  pathname: '/api/orders',
  query: { tenant: 'acme' },
}, (req) => {
  expect(req.body).to.include({ currency: 'EUR' });   // assert what matters
  req.reply({ statusCode: 201, body: { id: 'ORD-1' } });
}).as('createOrder');

The diagnostic when something matches unexpectedly is the command log: it shows which alias handled a request, which turns “the mock is not working” into “the wrong matcher won” in a few seconds.

Waiting on Aliases Without Coupling to Counts #

An alias is more than a label — it is the handle that lets a test wait for a specific request and assert on what was sent. Used well it removes fixed sleeps entirely; used carelessly it introduces a different fragility.

The common trap is depending on how many times a request occurs. A test that waits for an alias twice because the component currently fetches twice will break when someone adds caching, deduplication or a prefetch, even though the user-visible behaviour is unchanged. Waiting once and then asserting on the rendered consequence is more robust, because it depends on what the user sees rather than on the network chatter behind it.

The second trap is asserting on request bodies for their own sake. Verifying that a payload contains the fields the API requires is valuable; verifying the exact serialisation of every field couples the test to an implementation detail and produces failures on refactors that changed nothing observable. The useful line is to assert on the parts of the request that carry meaning — the identifier, the amount, the operation — and to ignore the rest.

There is also a sequencing subtlety worth knowing: intercepts must be registered before the action that triggers the request, and a spec that visits the page and then registers an intercept will miss anything fired during load. This is the same before-bootstrap ordering constraint that governs storage seeding, and it accounts for a large share of “the intercept never fired” reports.

Where a test genuinely needs to observe a sequence — a retry, a poll, a debounced series — a counter inside the handler expresses it clearly, and that counter must live inside the test so it cannot leak into the next one. The wider set of interception patterns is covered in Cypress cy.intercept Best Practices for Flaky Tests.

Common Pitfalls & Engineering Mitigations #

Third-Party Traffic Is a Reliability Decision #

The requests a suite does not control cause more instability than the ones it does. Analytics tags, consent platforms, session recorders, chat widgets and experiment scripts all load from infrastructure you do not own, mutate the DOM on their own schedule, and contribute nothing to any assertion.

Their effects are concrete rather than theoretical. A consent overlay renders across the viewport and intercepts the click a test was about to make — the timing of which varies with the vendor’s response time, producing a failure that looks like a race in your own application. A chat launcher occupies the corner where a submit button sits. A session recorder wraps event handlers and can delay them. And every one of these produces console errors and failed requests of its own, which makes any strict error checking noisy enough that teams disable it, losing a genuinely useful signal.

Blocking them at the interception layer is one of the highest-yield stability changes available to a browser suite, and it usually shortens the run as well, since vendor scripts are often the slowest requests on the page. The important companion step is stubbing the globals those scripts would have defined, so application code calling them does not throw — and that stub turns into coverage, because the analytics contract becomes assertable: a purchase event with the right value is a real product requirement that is otherwise verified by nobody.

The one thing worth preserving is a small, tagged spec that loads the real tags against a staging property, so a broken tracking configuration still fails somewhere. Intercepting Third-Party Analytics Scripts in Cypress covers the blocking policy, the consent seeding and the event assertions.

Frequently Asked Questions #

Why does my intercept never fire? Almost always ordering or specificity. An intercept registered after the visit misses requests fired during page load, and a pattern that does not match — a missing method, a path that differs by a trailing segment, a first-party proxy domain instead of the vendor’s — silently lets the real request through. The command log shows which requests were matched and by which alias, which resolves both cases quickly.

Should every request in a spec be intercepted? No — intercept what the test depends on and what would otherwise be non-deterministic, and let same-origin traffic you control proceed. Intercepting everything makes specs long and couples them to request patterns that change for reasons unrelated to behaviour. The exception is third-party traffic, which is worth blocking wholesale.

How do I model a request that fails once and then succeeds? Keep a counter in the handler and decide the outcome per attempt, declaring that counter inside the test so it cannot leak. This makes the retry itself the thing under test: the spec can assert that exactly two attempts occurred and that the interface recovered without a reload, which is a stronger statement than “it eventually worked”.

Is stubbing responses better than pointing at a test backend? For determinism, yes; for contract fidelity, no. Stubs give exact control of shape, status and timing, and they drift from the real API unless something checks them. A test backend keeps the contract honest and reintroduces availability and data-sharing concerns. Most suites want stubs by default with a small number of real-backend checks running on a schedule.

One further habit is worth adopting early: give every intercept an alias, even the ones no test waits on. The alias appears in the command log, which turns an unexplained response into a one-glance answer about which handler matched — and it costs a single argument. Unaliased intercepts are the reason “why did this request return that” investigations take minutes rather than seconds.

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.

A related habit that pays for itself: assert on the request as well as stubbing the response. A handler that checks the outgoing body contains the fields the API requires turns the mock from something that always agrees into a check on the client, which is the only place a suite will notice that a request has drifted out of contract.

Interception and Test Isolation Interact #

Interception state is per-spec, and the interaction with the runner’s isolation model produces a few behaviours worth knowing before they cause a confusing hour.

Intercepts registered in a beforeEach are re-registered for every test, which is what you want; those registered in a before hook survive across tests in the spec and can answer requests in a test that expected different behaviour. Aliases behave the same way, so waiting on an alias registered in a previous test yields a request that already happened rather than a new one — a subtle source of assertions that pass for the wrong reason.

The session-caching mechanism adds another wrinkle. A cached session restores cookies and storage without replaying the login flow, so any intercept written to observe login requests will not fire on subsequent specs that restore rather than perform the login. That is usually desirable, and it means a spec asserting on authentication traffic must opt out of the cache or perform the flow explicitly.

Disabling the runner’s per-test isolation compounds all of this: the page persists, in-flight requests from a previous test can land during the next one, and the intercept that was meant to handle them may already have been superseded. It is another reason the default is worth keeping, beyond the storage-leakage argument made in Clearing Browser Storage Between Tests.

The habit that avoids the whole family: register intercepts in beforeEach or inside the test, never in before, and keep any counter or scenario state in the same scope as the intercept that reads it.

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