Cypress Stubs

Two Kinds of Stubbing

Network stubbing (via cy.intercept(), covered in the previous lesson) replaces what a network request returns. Function stubbing (via cy.stub(), powered by Sinon.js) replaces the actual implementation of a JavaScript function, most useful in component testing or when testing code that calls a function you don't want to actually execute.

// Network stub: replaces an HTTP response
cy.intercept('GET', '/api/user', { fixture: 'user.json' });

// Function stub: replaces a JavaScript function's implementation
const onSave = cy.stub().as('onSave');
cy.mount(<Form onSave={onSave} />);
cy.get('[data-cy="submit"]').click();
cy.get('@onSave').should('have.been.calledOnce');

The function stub example is typical of component testing, where you pass a stub directly as a prop/callback.

cy.stub() Syntax

cy.stub()                          // a bare stub function
cy.stub().as('name')               // aliased for later assertions
cy.stub().returns(value)           // stub that returns a fixed value
cy.stub().resolves(value)          // stub that returns a resolved Promise
cy.stub(object, 'methodName')      // replace a method on an existing object

• A bare cy.stub() creates a new stub function you can pass anywhere a callback is expected.
• .returns()/.resolves()/.rejects() configure what the stub produces when called.
• cy.stub(obj, 'method') replaces an existing object's method temporarily, restored automatically after the test.
• Aliasing a stub with .as() lets you assert on it later with cy.get('@alias').should(...).

Stub Type Cheat Sheet

Network stubs versus function stubs, side by side.

Stubbing Native Browser Methods

cy.stub() can also replace native browser APIs like window.alert or window.confirm, which otherwise pause execution waiting for real user interaction, something a headless test cannot provide.

cy.window().then((win) => {
  cy.stub(win, 'confirm').returns(true).as('confirmStub');
});

cy.get('[data-cy="delete-item"]').click();
cy.get('@confirmStub').should('have.been.calledOnce');

Stubbing window.confirm to auto-return true lets the test proceed past what would otherwise be a blocking native dialog.

Asserting on How a Stub Was Called

Sinon-Chai assertions let you verify not just that a stub was called, but how: how many times, and with what arguments, useful for confirming a component calls a callback with exactly the expected data.

cy.get('@onSave').should('have.been.calledOnceWith', {
  email: 'user@example.com',
});

Common Mistakes

• Confusing network stubbing (cy.intercept()) with function stubbing (cy.stub()) as if they were interchangeable.
• Forgetting to alias a stub, making later assertions on its call count or arguments impossible.
• Stubbing a native browser dialog without asserting the stub was actually invoked, missing a chance to verify real behavior.
• Overusing function stubs in E2E tests where a network-level stub would more realistically represent the actual system.

Key Takeaways

• "Stub" refers to two related concepts in Cypress: network stubs and function stubs.
• Function stubs, powered by Sinon.js, replace a JavaScript function's implementation.
• Function stubs are especially useful in component testing and for native dialogs like window.confirm.
• Aliasing a stub enables later, expressive assertions on call count and arguments.