Diagnosing Common Network Interception Issues in Cypress.io

Why Intercepts Fail to Work

When a test that uses cy.intercept behaves unpredictably, the most common culprits are:

• Request pattern mismatch: the URL or HTTP method you specified doesn’t match the real request.
• Timing error: the intercept is registered after the request has already been sent.
• Missing or wrong route ID: without an alias you can’t wait for or assert on the request.
• Version incompatibility: older Cypress releases lack support for certain intercept options.

Diagnostic Checklist

Condition	Typical Symptom	Diagnostic Check
Pattern Mismatch	Stub not applied; real backend response appears.	Verify the cy.intercept URL and method match the actual request.
Timing Error	Request fires before cy.intercept is defined.	Inspect the test flow to ensure the intercept is registered before the UI action that triggers the request.
Missing Route ID	Flaky cy.wait or assertion failures.	Check that the intercept has an alias via .as('routeName').
Version Mismatch	Unsupported options cause errors or silent failures.	Confirm the Cypress version supports the options you’re using.

Step 1 – Inspect the Network Tab

Run the test in headed mode (cypress open) and open the browser’s Network panel. Look for the request you expect to stub:

GET /api/users 200 12ms

If the status code or body differs from what you defined in cy.intercept, the stub isn’t being applied.

Step 2 – Verify the Intercept Pattern

Ensure the pattern you passed to cy.intercept is exact. Common pitfalls include:

• Using a relative path when the request is absolute.
• Missing query parameters or using a wildcard that doesn’t capture the actual value.
• Wrong HTTP method (e.g., GET vs POST).

Example of a correct definition:

cy.intercept('GET', '/api/users', {
  statusCode: 200,
  body: [{ id: 1, name: 'Alice' }],
}).as('getUsers');

Step 3 – Check Timing of Intercept Registration

Interceptors must be registered before the request is triggered. If you trigger a request in a beforeEach or during a UI interaction that occurs earlier, the stub will be bypassed.

Reorder your test like this:

cy.intercept('GET', '/api/users', { statusCode: 200, body: [] }).as('getUsers');
// Now trigger the action that causes the request
cy.get('#load-users').click();

Step 4 – Confirm the Route ID

Without an alias, you can’t reliably wait for or assert on the request. Always alias your intercept:

cy.intercept('GET', '/api/users', { statusCode: 200, body: [] }).as('getUsers');
cy.wait('@getUsers').its('response.statusCode').should('eq', 200);

Step 5 – Verify Cypress Version Compatibility

Options such as response.statusCode overrides were added in Cypress 6.0. If you’re on an older release, the intercept may silently ignore these props. Run

npx cypress --version

to check your version. Upgrade if necessary.

Fixes Tied to Findings

• Pattern Mismatch – Update the URL or method to match the real request. Use cy.intercept({ url: '**/api/users*', method: 'GET' }) for flexible matching, but avoid full wildcards that capture unintended traffic.
• Timing Error – Move cy.intercept to the top of the test or into a beforeEach hook that runs before any UI actions.
• Missing Route ID – Add .as('aliasName') and use cy.wait('@aliasName') for deterministic assertions.
• Version Mismatch – Upgrade to the latest Cypress LTS or adjust the test to use options supported by your current version.

Escalation Criteria

If all the above checks pass and the stub still isn’t applied:

• Confirm that the application isn’t bypassing the request via caching or service workers. Disable service workers in Cypress with chromeWebSecurity: false and retry.
• Check for network-level proxies or VPNs that might alter the request path.
• Inspect any global cy.intercept definitions in cypress/support that could override the local stub.
• If the issue persists, file a ticket with Cypress support, providing the test file, cypress.json, and a minimal reproducible example.

Practical Verification

After applying a fix, re-run the test in headed mode and observe the Network tab. The stubbed request should show the status code and body you specified. Additionally, cy.wait('@aliasName').its('response.statusCode').should('eq', 200) should pass without timing out.

Always clean up after the test by resetting any global state or clearing local storage to avoid side effects in subsequent tests.