{
  "doc": {
    "id": "api/commands/stub",
    "title": "stub | Cypress Documentation",
    "description": "Replace a function, record its usage and control its behavior in Cypress.",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/stub.md",
    "version": "6a908a532b1fca4ed18538a4c1c5a9bc7f24f403",
    "updated_at": "2026-05-01T19:25:18.656Z",
    "headings": [
      {
        "id": "api/commands/stub#stub",
        "text": "stub",
        "level": 1
      },
      {
        "id": "api/commands/stub#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/stub#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/stub#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/stub#yields-learn-about-subject-management",
        "text": "Yields Learn about subject management",
        "level": 3
      },
      {
        "id": "api/commands/stub#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/stub#method",
        "text": "Method",
        "level": 3
      },
      {
        "id": "api/commands/stub#create-a-stub-and-manually-replace-a-function",
        "text": "Create a stub and manually replace a function",
        "level": 4
      },
      {
        "id": "api/commands/stub#replace-a-method-with-a-stub",
        "text": "Replace a method with a stub",
        "level": 4
      },
      {
        "id": "api/commands/stub#replace-a-method-with-a-function",
        "text": "Replace a method with a function",
        "level": 4
      },
      {
        "id": "api/commands/stub#specify-the-return-value-of-a-stubbed-method",
        "text": "Specify the return value of a stubbed method",
        "level": 4
      },
      {
        "id": "api/commands/stub#replace-built-in-window-methods-like-prompt",
        "text": "Replace built-in window methods like prompt",
        "level": 4
      },
      {
        "id": "api/commands/stub#disable-logging-to-command-log",
        "text": "Disable logging to Command Log",
        "level": 4
      },
      {
        "id": "api/commands/stub#more-cy-stub-examples",
        "text": "More cy.stub() examples",
        "level": 4
      },
      {
        "id": "api/commands/stub#aliases",
        "text": "Aliases",
        "level": 3
      },
      {
        "id": "api/commands/stub#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/commands/stub#restores",
        "text": "Restores",
        "level": 3
      },
      {
        "id": "api/commands/stub#automatic-reset-restore-between-tests",
        "text": "Automatic reset/restore between tests",
        "level": 4
      },
      {
        "id": "api/commands/stub#differences",
        "text": "Differences",
        "level": 3
      },
      {
        "id": "api/commands/stub#difference-between-cy-spy-and-cy-stub",
        "text": "Difference between cy.spy() and cy.stub()",
        "level": 4
      },
      {
        "id": "api/commands/stub#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/stub#history",
        "text": "History",
        "level": 2
      },
      {
        "id": "api/commands/stub#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "stub"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Replace a function, record its usage and control its behavior."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cy.stub()` is a utility function, and is not a Cypress command, query or assertion. It is not retryable, chainable, or timeout-able."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Note: `.stub()` assumes you are already familiar with our guide: "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/guides/stubs-spies-and-clocks.md",
            "children": [
              {
                "type": "text",
                "value": "Stubs, Spies, and Clocks"
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.stub()cy.stub(object, method)"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Usage"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Correct Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.stub(user, 'addFriend')cy.stub(user, 'addFriend').as('addFriend')"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Arguments"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "object (Object)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The `object` that has the `method` to be replaced."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "method (String)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The name of the `method` on the `object` to be wrapped."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Yields "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management",
            "children": [
              {
                "type": "text",
                "value": "Learn about subject management"
              }
            ]
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.stub()` is synchronous and returns a value (the stub) instead of a Promise-like chain-able object. It can be aliased."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.stub()` returns a "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "http://sinonjs.org",
                    "children": [
                      {
                        "type": "text",
                        "value": "Sinon.js stub"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": ". All methods found on "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "http://sinonjs.org",
                    "children": [
                      {
                        "type": "text",
                        "value": "Sinon.js"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " spies and stubs are supported."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Method"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Create a stub and manually replace a function"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// assume App.start calls util.addListenersutil.addListeners = cy.stub()App.start()expect(util.addListeners).to.be.called"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Replace a method with a stub"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// assume App.start calls util.addListenerscy.stub(util, 'addListeners')App.start()expect(util.addListeners).to.be.called"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Replace a method with a function"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// assume App.start calls util.addListenerslet listenersAdded = falsecy.stub(util, 'addListeners').callsFake(() => {  listenersAdded = true})App.start()expect(listenersAdded).to.be.true"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Specify the return value of a stubbed method"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// assume App.start calls util.addListeners, which returns a function// that removes the listenersconst removeStub = cy.stub()cy.stub(util, 'addListeners').returns(removeStub)App.start()App.stop()expect(removeStub).to.be.called"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Replace built-in window methods like prompt"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "In end-to-end tests, replacing built-in `window` methods needs to happen after the page is visited, but before the application under test is loaded. You can do this by stubbing functions inside the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/visit.md",
            "children": [
              {
                "type": "text",
                "value": "`cy.visit()`"
              }
            ]
          },
          {
            "type": "text",
            "value": " command `onBeforeLoad` function."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "In Component tests, because the page isn't being reloaded, all you need to do is stub functions before mounting your component."
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "End-to-End Test"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Component Test"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.visit('http://localhost:3000', {  onBeforeLoad(win) {    // Stub your functions here    cy.stub(win, 'prompt').returns('my custom message')  },})App.start()cy.window().its('prompt').should('be.called')cy.get('.name').should('have.value', 'my custom message')"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// Stub your functions herecy.mount()cy.stub(window, 'prompt').returns('my custom message')// After that, mount your componentcy.mount(<MyComponent />)cy.window().its('prompt').should('be.called')cy.get('.name').should('have.value', 'my custom message')"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Disable logging to Command Log"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can chain a `.log(bool)` method to disable `cy.stub()` calls from being shown in the Command Log. This may be useful when your stubs are called an excessive number of times."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const obj = {  foo() {},}const stub = cy.stub(obj, 'foo').log(false)"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "More `cy.stub()` examples"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/recipes.md#Stubbing-and-spying",
            "children": [
              {
                "type": "text",
                "value": "Check out our example recipe testing spying, stubbing and time"
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Aliases"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can alias stubs, similar to how "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/as.md",
            "children": [
              {
                "type": "text",
                "value": "`.as()`"
              }
            ]
          },
          {
            "type": "text",
            "value": " works. This can make your stubs easier to identify in error messages and Cypress's command log, and allows you to assert against them later using `cy.get()`."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const obj = {  foo() {},}const stub = cy.stub(obj, 'foo').as('anyArgs')const withFoo = stub.withArgs('foo').as('withFoo')obj.foo()expect(stub).to.be.calledcy.get('@withFoo').should('be.called') // purposefully failing assertion"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You will see the following in the command log:"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Notes"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Restores"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Automatic reset/restore between tests"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cy.stub()` creates stubs in a "
          },
          {
            "type": "link",
            "title": null,
            "url": "http://sinonjs.org/releases/v8/sandbox/",
            "children": [
              {
                "type": "text",
                "value": "sandbox"
              }
            ]
          },
          {
            "type": "text",
            "value": ", so all stubs created are automatically reset/restored between tests without you having to explicitly reset/restore them."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Differences"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Difference between cy.spy() and cy.stub()"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The main difference between `cy.spy()` and "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/stub.md",
            "children": [
              {
                "type": "text",
                "value": "`cy.stub()`"
              }
            ]
          },
          {
            "type": "text",
            "value": " is that `cy.spy()` does not replace the method, it only wraps it. So, while invocations are recorded, the original method is still called. This can be very useful when testing methods on native browser objects. You can verify a method is being called by your test and still have the original method action invoked."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Command Log"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Create a stub, alias it, and call it"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const obj = {  foo() {},}const stub = cy.stub(obj, 'foo').as('foo')obj.foo('foo', 'bar')expect(stub).to.be.called"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The command above will display in the Command Log as:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When clicking on the `(stub-1)` event within the command log, the console outputs the following:"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "History"
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Version"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Changes"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#0-20-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "0.20.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `.log(bool)` method"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#0-18-8",
                    "children": [
                      {
                        "type": "text",
                        "value": "0.18.8"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.stub()` command added"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "See also"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/as.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`.as()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/clock.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.clock()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/spy.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.spy()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/guides/stubs-spies-and-clocks.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Guide: Stubs, Spies and Clocks"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/recipes.md#Stubbing-and-spying",
                    "children": [
                      {
                        "type": "text",
                        "value": "Recipe: Stubbing, Spying"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/recipes.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Recipe: Unit Test - Stubbing Dependencies"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 872
}