Spies, Stubs & Clocks

cy.spy()

To wrap a method in a spy, use the cy.spy() command.

const obj = {
  foo () {},
}

const spy = cy.spy(obj, 'foo').as('anyArgs')

obj.foo()

expect(spy).to.be.called

cy.spy() retries until the assertions that follow it pass.

const obj = {
  foo () {},
}

cy.spy(obj, 'foo').as('foo')

setTimeout(() => {
  obj.foo()
}, 500)

setTimeout(() => {
  obj.foo()
}, 2500)

cy.get('@foo').should('have.been.calledTwice')

cy.stub()

To create a stub and/or replace a function with a stub, use the cy.stub() command.

let obj = {
  foo () {},
}

const stub = cy.stub(obj, 'foo').as('foo')

obj.foo('foo', 'bar')

expect(stub).to.be.called

cy.clock()

To control time in the browser, use the cy.clock() command.

// create the date in UTC so it's always the same
// no matter what local timezone the browser is running in
const now = new Date(Date.UTC(2017, 2, 14)).getTime()

cy.clock(now)
cy.visit('https://example.cypress.io/commands/spies-stubs-clocks')
cy.get('#clock-div').click()
cy.get('#clock-div')
  .should('have.text', '1489449600')

cy.tick()

To move time in the browser, use the cy.tick() command.

// create the date in UTC so it's always the same
// no matter what local timezone the browser is running in
const now = new Date(Date.UTC(2017, 2, 14)).getTime()

cy.clock(now)
cy.visit('https://example.cypress.io/commands/spies-stubs-clocks')
cy.get('#tick-div').click()
cy.get('#tick-div')
  .should('have.text', '1489449600')
cy.tick(10000) // 10 seconds passed
cy.get('#tick-div').click()
cy.get('#tick-div')
  .should('have.text', '1489449610')

cy.stub() matches depending on arguments

See all possible matchers at Sinonjs.org

const greeter = {
  /**
    * Greets a person
    * @param {string} name
  */
  greet (name) {
    return `Hello, ${name}!`
  },
}

cy.stub(greeter, 'greet')
  .callThrough() // if you want non-matched calls to call the real method
  .withArgs(Cypress.sinon.match.string).returns('Hi')
  .withArgs(Cypress.sinon.match.number).throws(new Error('Invalid name'))

expect(greeter.greet('World')).to.equal('Hi')
expect(() => greeter.greet(42)).to.throw('Invalid name')
expect(greeter.greet).to.have.been.calledTwice

// non-matched calls goes the actual method
expect(greeter.greet()).to.equal('Hello, undefined!')

matches call arguments using Sinon matchers

See all possible matchers at Sinonjs.org

const calculator = {
  /**
    * returns the sum of two arguments
    * @param a {number}
    * @param b {number}
  */
  add (a, b) {
    return a + b
  },
}

const spy = cy.spy(calculator, 'add').as('add')

expect(calculator.add(2, 3)).to.equal(5)

// if we want to assert the exact values used during the call
expect(spy).to.be.calledWith(2, 3)

// let's confirm "add" method was called with two numbers
expect(spy).to.be.calledWith(Cypress.sinon.match.number, Cypress.sinon.match.number)

// alternatively, provide the value to match
expect(spy).to.be.calledWith(Cypress.sinon.match(2), Cypress.sinon.match(3))

// match any value
expect(spy).to.be.calledWith(Cypress.sinon.match.any, 3)

// match any value from a list
expect(spy).to.be.calledWith(Cypress.sinon.match.in([1, 2, 3]), 3)

// expect the value to pass a custom predicate function
// the second argument to "sinon.match(predicate, message)" is
// shown if the predicate does not pass and assertion fails
const isEven = (x) => x % 2 === 0

expect(spy).to.be.calledWith(Cypress.sinon.match(isEven, 'isEven'), 3)

// you can combine several matchers using "and", "or"
const isGreaterThan = (limit) => (x) => x > limit
const isLessThan = (limit) => (x) => x < limit

expect(spy).to.be.calledWith(
  Cypress.sinon.match.number,
  Cypress.sinon.match(
    isGreaterThan(2), '> 2').and(Cypress.sinon.match(isLessThan(4), '< 4'))
)

expect(spy).to.be.calledWith(
  Cypress.sinon.match.number,
  Cypress.sinon.match(isGreaterThan(200), '> 200').or(Cypress.sinon.match(3))
)

// matchers can be used from BDD assertions
cy.get('@add').should('have.been.calledWith',
  Cypress.sinon.match.number, Cypress.sinon.match(3)
)

// you can alias matchers for shorter test code
const { match: M } = Cypress.sinon

cy.get('@add').should('have.been.calledWith', M.number, M(3))