Mastering Cypress Network Stubbing: Reliable Integration Tests with `cy.intercept`

Why Stub Network Calls?

When writing end‑to‑end tests, the application under test often talks to a remote API. Flaky responses, slow servers, or missing test data can make a test unreliable. Instead of hitting the real backend, you can intercept the HTTP request and return a predictable response. Cypress’ cy.intercept makes this trivial.

Setting Up an Intercept

Define the stub before the request is made – that is, before the user action that triggers the network call. The syntax is simple:

// In your test file
cy.intercept('GET', '/api/users', {
  statusCode: 200,
  body: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }],
  headers: { 'x-custom-header': 'stubbed' }
}).as('getUsers');

Key points:

• Method & URL – match the HTTP verb and endpoint pattern. Use wildcards (**) for dynamic segments.
• Response object – you can set statusCode, body, headers, and even delay to simulate latency.
• Alias – attaching .as('aliasName') lets you reference the request later for assertions.

Triggering the Request

After the stub is registered, perform the UI action that causes the request:

cy.get('#load-users').click();

Cypress automatically waits for the request to finish before proceeding to the next command. No cy.wait() is needed.

Asserting the Stubbed Response

Use the alias to access the intercepted request and validate the mocked data:

cy.wait('@getUsers').then((interception) => {
  expect(interception.response.statusCode).to.eq(200);
  expect(interception.response.body).to.have.length(2);
  expect(interception.response.body[0].name).to.eq('Alice');
});

The interception object contains the full request/response cycle, so you can assert headers, query parameters, or body structure.

Common Pitfalls & Trade‑offs

• Timing – If you add an interceptor after the request has already been dispatched, Cypress will ignore it and the real network call will go through. Always place cy.intercept before the UI action.
• Complex chains – Stubbing many endpoints in a single test can clutter the command log and make debugging harder. Keep your stubs focused and consider splitting tests if the logic diverges.
• State leakage – Stubs persist for the duration of the test. If a later test needs a different response, explicitly reset or override the stub with a new cy.intercept call.
• Stubbing vs. API mocking services – For large systems, external mock servers (e.g., Mockoon, WireMock) can provide more realistic networks, but Cypress stubs are great for quick, UI‑centric tests.

Verifying Your Stubs Work

During development, the Cypress Command Log will show the intercepted request. It should display the mocked status and body instead of a network error. For headless runs, add --reporter mochawesome to capture the log, then check that the test passes consistently across multiple executions.

Practical Checklist

1. Define cy.intercept before any UI action that triggers the request.
2. Use aliases to reference and assert the intercepted call.
3. Keep the stub payload simple and realistic for the test scenario.
4. Verify the Command Log or headless report shows the mocked response.
5. Reset or override stubs between tests to avoid cross‑test contamination.

Conclusion

Network stubbing with cy.intercept turns flaky, backend‑dependent tests into deterministic, fast integration tests. By placing the interceptor early, assigning aliases, and asserting the response, you gain full control over the data flow without touching the server. Remember the timing caveat and keep your stubs focused – the result is reliable, maintainable tests that let you focus on UI behavior, not network hiccups.