{ "doc": { "id": "app/guides/stubs-spies-and-clocks", "title": "Stubs, Spies, and Clocks: Cypress Guide", "description": "Learn how to use `cy.stub()`, `cy.spy()`, and `cy.clock()` in Cypress to manipulate your application's behavior and time.", "section": "app", "source_path": "/llm/markdown/app/guides/stubs-spies-and-clocks.md", "version": "e6988a974973e9090ce70406c38cb2b9e0eac9fa", "updated_at": "2026-05-15T15:50:22.536Z", "headings": [ { "id": "app/guides/stubs-spies-and-clocks#stubs-spies-and-clocks", "text": "Stubs, Spies, and Clocks", "level": 1 }, { "id": "app/guides/stubs-spies-and-clocks#what-youll-learn", "text": "What you'll learn", "level": 5 }, { "id": "app/guides/stubs-spies-and-clocks#libraries-and-tools", "text": "Libraries and Tools", "level": 2 }, { "id": "app/guides/stubs-spies-and-clocks#common-scenarios", "text": "Common Scenarios", "level": 2 }, { "id": "app/guides/stubs-spies-and-clocks#stubs", "text": "Stubs", "level": 3 }, { "id": "app/guides/stubs-spies-and-clocks#common-scenarios", "text": "Common Scenarios:", "level": 4 }, { "id": "app/guides/stubs-spies-and-clocks#spies", "text": "Spies", "level": 3 }, { "id": "app/guides/stubs-spies-and-clocks#clock", "text": "Clock", "level": 3 }, { "id": "app/guides/stubs-spies-and-clocks#common-scenarios", "text": "Common Scenarios", "level": 4 }, { "id": "app/guides/stubs-spies-and-clocks#control-setinterval", "text": "Control setInterval", "level": 5 }, { "id": "app/guides/stubs-spies-and-clocks#restore-the-clock", "text": "Restore the clock", "level": 5 }, { "id": "app/guides/stubs-spies-and-clocks#assertions", "text": "Assertions", "level": 3 }, { "id": "app/guides/stubs-spies-and-clocks#integration-and-extensions", "text": "Integration and Extensions", "level": 2 }, { "id": "app/guides/stubs-spies-and-clocks#see-also", "text": "See also", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Stubs, Spies, and Clocks" } ] }, { "type": "heading", "depth": 5, "children": [ { "type": "text", "value": "What you'll learn" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "How to use `cy.stub()`, `cy.spy()`, and `cy.clock()`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Common scenarios for using stubs, spies, and clocks" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "How to use assertions with stubs and spies" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress comes built in with the ability to stub and spy with " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/stub.md", "children": [ { "type": "text", "value": "`cy.stub()`" } ] }, { "type": "text", "value": ", " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/spy.md", "children": [ { "type": "text", "value": "`cy.spy()`" } ] }, { "type": "text", "value": " or modify your application's time with " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/clock.md", "children": [ { "type": "text", "value": "`cy.clock()`" } ] }, { "type": "text", "value": " - which lets you manipulate `Date`, `setTimeout`, `clearTimeout`, `setInterval`, or `clearInterval`." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "These commands are useful when writing both unit tests and integration tests." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Libraries and Tools" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress automatically bundles and wraps these libraries:" } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "What it does" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "http://sinonjs.org", "children": [ { "type": "text", "value": "`sinon`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "provides the " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/stub.md", "children": [ { "type": "text", "value": "`cy.stub()`" } ] }, { "type": "text", "value": " and " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/spy.md", "children": [ { "type": "text", "value": "`cy.spy()`" } ] }, { "type": "text", "value": " APIs" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "https://github.com/sinonjs/lolex", "children": [ { "type": "text", "value": "`lolex`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "provides the " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/clock.md", "children": [ { "type": "text", "value": "`cy.clock()`" } ] }, { "type": "text", "value": " and " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/tick.md", "children": [ { "type": "text", "value": "`cy.tick()`" } ] }, { "type": "text", "value": " APIs" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "https://github.com/domenic/sinon-chai", "children": [ { "type": "text", "value": "`sinon-chai`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "adds `chai` assertions for stubs and spies" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "You can refer to each of these libraries' documentation for more examples and explanations." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Common Scenarios" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Example test!" } ] }, { "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": "Stubs" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A stub is a way to modify a function and delegate control over its behavior to you (the programmer)." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A stub is most commonly used in a unit test but is still useful during some integration/e2e tests." } ] }, { "type": "code", "lang": null, "meta": null, "value": "// create a standalone stub (generally for use in unit test)cy.stub()// replace obj.method() with a stubbed functioncy.stub(obj, 'method')// force obj.method() to return \"foo\"cy.stub(obj, 'method').returns('foo')// force obj.method() when called with \"bar\" argument to return \"foo\"cy.stub(obj, 'method').withArgs('bar').returns('foo')// force obj.method() to return a promise which resolves to \"foo\"cy.stub(obj, 'method').resolves('foo')// force obj.method() to return a promise rejected with an errorcy.stub(obj, 'method').rejects(new Error('foo'))" }, { "type": "paragraph", "children": [ { "type": "text", "value": "You generally stub a function when it has side effects you are trying to control." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Common Scenarios:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You have a function that accepts a callback, and want to invoke the callback." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Your function returns a `Promise`, and you want to automatically resolve or reject it." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You have a function that wraps `window.location` and don't want your application to be navigated." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You're trying to test your application's \"failure path\" by forcing things to fail." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You're trying to test your application's \"happy path\" by forcing things to pass." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You want to \"trick\" your application into thinking it's logged in or logged out." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You're using `oauth` and want to stub login methods." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "cy.stub()" } ] }, { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/api/commands/stub.md", "children": [ { "type": "text", "value": "Read more about how to use `cy.stub()`" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Spies" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A spy gives you the ability to \"spy\" on a function, by letting you capture and then assert that the function was called with the right arguments, or that the function was called a certain number of times, or even what the return value was or what context the function was called with." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A spy does not modify the behavior of the function - it is left perfectly intact. A spy is most useful when you are testing the contract between multiple functions and you don't care about the side effects the real function may create (if any)." } ] }, { "type": "code", "lang": null, "meta": null, "value": "cy.spy(obj, 'method')" }, { "type": "paragraph", "children": [ { "type": "text", "value": "cy.spy()" } ] }, { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/api/commands/spy.md", "children": [ { "type": "text", "value": "Read more about how to use `cy.spy()`" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Clock" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "There are situations when it is useful to control your application's `date` and `time` in order to override its behavior or avoid slow tests." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "With " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/clock.md", "children": [ { "type": "text", "value": "cy.clock()" } ] }, { "type": "text", "value": " you can control:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`Date`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`setTimeout`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`setInterval`" } ] } ] } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Common Scenarios" } ] }, { "type": "heading", "depth": 5, "children": [ { "type": "text", "value": "Control `setInterval`" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You're polling something in your application with `setInterval` and want to control that." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "You have throttled or debounced functions which you want to control." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Once you've enabled " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/clock.md", "children": [ { "type": "text", "value": "`cy.clock()`" } ] }, { "type": "text", "value": " you can control time by ticking it ahead by milliseconds." } ] }, { "type": "code", "lang": null, "meta": null, "value": "cy.clock()cy.visit('http://localhost:3333')cy.get('#search').type('Acme Company')cy.tick(1000)" }, { "type": "paragraph", "children": [ { "type": "text", "value": "You can call " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/clock.md", "children": [ { "type": "text", "value": "`cy.clock()`" } ] }, { "type": "text", "value": " prior to visiting your application and we will automatically bind it to the application on the next " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/visit.md", "children": [ { "type": "text", "value": "`cy.visit()`" } ] }, { "type": "text", "value": ". The same concept applies to mounting a component with " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/mount.md", "children": [ { "type": "text", "value": "`cy.mount()`" } ] }, { "type": "text", "value": ". We bind before any timers from your code can be invoked." } ] }, { "type": "heading", "depth": 5, "children": [ { "type": "text", "value": "Restore the clock" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "You can restore the clock and allow your application to resume normally without manipulating native global functions related to time. This is automatically called between tests." } ] }, { "type": "code", "lang": null, "meta": null, "value": "cy.clock()cy.visit('http://localhost:3333')cy.get('#search').type('Acme Company')cy.tick(1000)// more test code here// restore the clockcy.clock().then((clock) => { clock.restore()})// more test code here" }, { "type": "paragraph", "children": [ { "type": "text", "value": "You could also restore by using " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/invoke.md", "children": [ { "type": "text", "value": ".invoke()" } ] }, { "type": "text", "value": " to invoke the `restore` function." } ] }, { "type": "code", "lang": null, "meta": null, "value": "cy.clock().invoke('restore')" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Assertions" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Once you have a `stub` or a `spy` in hand, you can then create assertions about them." } ] }, { "type": "code", "lang": null, "meta": null, "value": "const user = { getName: (arg) => { return arg }, updateEmail: (arg) => { return arg }, fail: () => { throw new Error('fail whale') },}// force user.getName() to return \"Jane\"cy.stub(user, 'getName').returns('Jane Lane')// spy on updateEmail but do not change its behaviorcy.spy(user, 'updateEmail')// spy on fail but do not change its behaviorcy.spy(user, 'fail')// invoke getNameconst name = user.getName(123)// invoke updateEmailconst email = user.updateEmail('jane@devs.com')try { // invoke fail user.fail()} catch (e) {}expect(name).to.eq('Jane Lane') // trueexpect(user.getName).to.be.calledOnce // trueexpect(user.getName).not.to.be.calledTwice // trueexpect(user.getName).to.be.calledWith(123)expect(user.getName).to.be.calledWithExactly(123) // trueexpect(user.getName).to.be.calledOn(user) // trueexpect(email).to.eq('jane@devs.com') // trueexpect(user.updateEmail).to.be.calledWith('jane@devs.com') // trueexpect(user.updateEmail).to.have.returned('jane@devs.com') // trueexpect(user.fail).to.have.thrown('Error') // true" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Integration and Extensions" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Beyond integrating these tools together, we have also extended and improved collaboration between these tools." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Some examples:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "We replaced Sinon's argument stringifier for a much less noisy, more performant, custom version." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "We improved the `sinon-chai` assertion output by changing what is displayed during a passing vs. failing test." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "We added aliasing support to `stub` and `spy` APIs." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "We automatically restore and tear down `stub`, `spy`, and `clock` between tests." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "We also integrated all of these APIs directly into the Command Log, so you can visually see what's happening in your application." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "We visually indicate when:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A `stub` is called" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A `spy` is called" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "A `clock` is ticked" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When you use aliasing with the " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/as.md", "children": [ { "type": "text", "value": "`.as()`" } ] }, { "type": "text", "value": " command, we also correlate those aliases with the calls. This works identically to aliasing " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/intercept.md", "children": [ { "type": "text", "value": "`cy.intercept()`" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When stubs are created by calling the method `.withArgs(...)` we also visually link these together." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When you click on a stub or spy, we also output remarkably helpful debugging information." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For instance we automatically display:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The call count (and the total number of calls)" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The arguments, without transforming them (they are the real arguments)" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The return value of the function" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The context the function was invoked with" } ] } ] } ] }, { "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": "https://example.cypress.io/commands/spies-stubs-clocks", "children": [ { "type": "text", "value": "Spies, stubs, and clocks" } ] }, { "type": "text", "value": " examples" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://www.cypress.io/blog/2021/02/23/cy-intercept-and-cy-clock/", "children": [ { "type": "text", "value": "Testing periodic network requests with cy.intercept and cy.clock combination" } ] } ] } ] } ] } ] }, "token_estimate": 1377 }