How to Stub Network Request in Cypress for Testing

In Cypress, you can stub a network request using cy.intercept() to intercept and control HTTP calls. This lets you simulate server responses by providing a stubbed reply, making tests faster and more reliable without hitting the real backend.

Syntax

The basic syntax of cy.intercept() to stub a network request is:

• method: HTTP method like GET, POST, etc.
• url: The URL or pattern to match the request.
• response: The stubbed response data or object.

You can also add an alias to reference the stub later in your test.

javascript

cy.intercept(method, url, response).as('aliasName')

Example

This example shows how to stub a GET request to /api/users and return a fake user list. The test visits a page and waits for the stubbed request to complete.

javascript

describe('Stub network request example', () => {
  it('stubs GET /api/users with fake data', () => {
    cy.intercept('GET', '/api/users', {
      statusCode: 200,
      body: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }],
    }).as('getUsers')

    cy.visit('/users')

    cy.wait('@getUsers')

    cy.get('.user').should('have.length', 2)
    cy.get('.user').first().should('contain.text', 'Alice')
  })
})

Output

Test passes if the page shows 2 users named Alice and Bob from the stubbed response.

Common Pitfalls

Common mistakes when stubbing network requests in Cypress include:

• Not using the correct HTTP method or URL pattern, so the stub never matches.
• Forgetting to add .as() alias and then trying to cy.wait() on a non-existent alias.
• Stubbing after the request has already been sent, which means the real request goes through.
• Not returning a proper response object with statusCode and body, causing unexpected test failures.

Always define the stub before the action that triggers the request.

javascript

/* Wrong way: stub after visit - real request sent */
cy.visit('/users')
cy.intercept('GET', '/api/users', { statusCode: 200, body: [] }).as('getUsers')

/* Right way: stub before visit */
cy.intercept('GET', '/api/users', { statusCode: 200, body: [] }).as('getUsers')
cy.visit('/users')

Quick Reference

Feature	Usage	Example
Stub GET request	cy.intercept('GET', url, response)	cy.intercept('GET', '/api/data', { body: [] })
Alias stub	Add .as('name') to intercept	cy.intercept(...).as('getData')
Wait for stub	cy.wait('@alias')	cy.wait('@getData')
Stub with status	Include statusCode in response	{ statusCode: 404, body: {} }
Match URL pattern	Use string or regex	cy.intercept('GET', /\/api\/users\?page=\d+/)

Key Takeaways

Use cy.intercept() before triggering the network request to stub it successfully.

Always specify the HTTP method and URL or pattern to match the request.

Add an alias with .as() to wait for and verify the stubbed request.

Provide a complete response object with statusCode and body for predictable tests.

Check your URL and method carefully to avoid unmatched stubs.