cypress/docs/source/api/commands/clock.md

title, comments, description

title	comments	description
clock	true

.clock() overrides native global functions related to time allowing them to be controlled synchronously via .tick() or the yielded clock object. This includes controlling:

• setTimeout
• clearTimeout
• setInterval
• clearInterval
• Date Objects

The clock starts at the unix epoch (timestamp of 0). This means that when you instantiate new Date in your application, it will have a time of January 1st, 1970.

Syntax

.clock()
.clock(now)
.clock(now, functionNames)
.clock(options)
.clock(now, options)
.clock(now, functionNames, options)

Usage

.clock() cannot be chained off any other cy commands, so should be chained off of cy for clarity.

{% fa fa-check-circle green %} Valid Usage

cy.clock()

Arguments

{% fa fa-angle-right %} now (Date)

A timestamp specifying where the clock should start.

{% fa fa-angle-right %} functionNames (Array)

Name of native functions that clock should override.

{% fa fa-angle-right %} options (Object)

Pass in an options object to change the default behavior of .clock.

Option	Default	Notes
log	true	whether to display command in command log

Yields

.clock() yields a clock object with the following methods. You can also access the clock object via this.clock in a cy.then callback.

clock.tick(milliseconds)

Move the clock the specified number of milliseconds. Any timers within the affected range of time will be called.

clock.restore()

Restore all overridden native functions. This is automatically called between tests, so should generally not be needed.

Timeout

Examples

Clock

Create a clock and use it to trigger a setInterval

// your app code
var seconds = 0

setInterval(function(){
  $('#seconds-elapsed').text(++seconds + ' seconds')
}, 1000)

cy
  .clock()
  .visit('/index.html')
  .tick(1000)
  .get('#seconds-elapsed')
    .should('have.text', '1 seconds')
  .tick(1000)
  .get('#seconds-elapsed')
    .should('have.text', '2 seconds')

Access the clock object to synchronously move time

In most cases, it's easier to .tick() to move time, but you can also use the clock object yielded by .clock().

cy.clock().then(function (clock) {
  clock.tick(1000)
})

You can call .clock() again for this purpose later in a chain if necessary.

cy
  .clock()
  .get('#foo')
  .type('Foo')
  .clock().then(function (clock) {
    clock.tick(1000)
  })

The clock object is also available via this.clock in any .then callback.

cy
  .clock()
  .get('#foo').then(function ($foo) {
    this.clock.tick(1000)
    // do something with $foo ...
  })

Access the clock object to restore native functions

In general, it should not be necessary to manually restore the native functions that .clock() overrides, since this is done automatically between tests. But if you need to, the clock object yielded has a .restore method.

cy.clock().then(function (clock) {
  clock.restore()
})

Or via this.clock:

cy
  .clock()
  .get('#foo').then(function ($foo) {
    this.clock.restore()
    // do something with $foo ...
  })

Now

Specify a now timestamp

// your app code
$('#date').text(new Date().toJSON())

const now = new Date(2017, 2, 14).getTime() // March 14, 2017 timestamp

cy
  .clock(now)
  .visit('/index.html')
  .get('#date')
    .contains('2017-03-14')

Function Names

Specify which functions to override

This example below will only override setTimeout and clearTimeout and leave the other time-related functions as they are.

cy.clock(null, ['setTimeout', 'clearTimeout'])

{% note info Using cy.clock and cy.tick %} Check out our example recipe testing spying, stubbing and time {% endnote %}

Notes

iframes not supported

Note that this only applies to the top window on a web page. It will not override the time functions on any iframe embedded on the web page.

clock behavior before .visit()

If you call cy.clock before visiting a page with cy.visit, the page's native global functions will be overridden on window load, before any of your app code runs, so even if setTimeout, for example, is called on page load, it can still be controlled via cy.tick. This also applies if, during the course of a test, the page under test is reloaded or changed.

Command Log

Create a clock and tick it 1 second

cy
  .clock()
  .tick(1000)

The command above will display in the command log as:

When clicking on the clock command within the command log, the console outputs the following:

See also

• Guide: Stubs, Spies and Clocks
• Recipe: Controlling Behavior with Spies, Stubs, and Clocks
• tick
• spy
• stub