cy.intercept: Control Network Traffic in Cypress Tests

Why it exists

Modern web apps are constantly making network requests. To test frontend behavior reliably, you need to control the responses from those requests. Waiting for a real backend is slow, flaky, and makes it hard to simulate specific edge cases like network errors or empty data sets.

The mental model

Think of cy.intercept() as a traffic cop standing between your application and the network. It can simply watch requests go by (spying), stop a request and provide a fake response (stubbing), or even change the request before letting it proceed. This gives you complete control over the network layer during your tests.

How it works

You define an intercept by specifying what to match and what to do. Matching can be a simple URL string, a glob pattern, or a complex RouteMatcher object with properties like method, hostname, and headers. Once matched, you have three options. First, do nothing, which just spies on the request. Second, provide a StaticResponse object to immediately return a canned response, like { statusCode: 404, body: 'Not Found' }. Third, provide a routeHandler function that receives the request object (req), allowing you to inspect it, modify it, and dynamically decide what response to send back.

When to use it

Use cy.intercept() to test how your UI reacts to different network conditions. For example, stubbing a response to show a loading spinner, then an error message when the request fails with a 500 status code. It's also perfect for providing consistent data to your tests, ensuring they don't break if the backend database changes. You can also use it to wait for a specific request to complete before making an assertion with cy.wait('@alias').

When not to use it

Avoid cy.intercept() for true end-to-end tests where you explicitly want to verify the contract between your frontend and a live backend. Over-stubbing can create tests that pass even when the real application is broken because the frontend and backend have drifted apart. For these scenarios, let requests go through to a real, controlled test environment.

One canonical example

To test a 'user not found' scenario, you can intercept a GET request and force a 404 response. First, intercept the route: cy.intercept('GET', '/api/users/123', { statusCode: 404 }).as('getUser'). Then, visit the page: cy.visit('/users/123'). Next, wait for the call: cy.wait('@getUser'). Finally, assert the UI changed: cy.contains('User not found').should('be.visible'). This verifies the UI correctly handles the error state.