{"__v":0,"_id":"589775ac8066520f00bb376d","category":{"__v":60,"_id":"569002f19ebef90d0087289d","pages":["56900352769f210d00132595","5690047121fcf0190071d943","569004924719c119002ce654","569004ceb700ce0d002f4b94","569023e518c3920d00be8b37","569023f748df220d004ca215","5690240af7eb9a0d00f4465d","5690241b48df220d004ca217","5690243e48df220d004ca219","56902453741e9c0d00af2fb5","56902463efcc380d0043a5a1","5690247b18c3920d00be8b39","56902492f7eb9a0d00f4465f","569024a16c49d70d00f18075","569024b2efcc380d0043a5a3","569024cc48df220d004ca21b","569024ea18c3920d00be8b3b","5690258618c3920d00be8b3f","5690259bf7eb9a0d00f44662","569025b06c49d70d00f18077","569029b418c3920d00be8b43","569029d4f7eb9a0d00f44667","569029e8e056c80d00fdec58","569029fb48df220d004ca221","56902a1c18c3920d00be8b46","56902a45f7eb9a0d00f44669","56902a6be056c80d00fdec5a","56902a78f7eb9a0d00f4466b","56902a8848df220d004ca224","56902aa018c3920d00be8b4b","56902ace6c49d70d00f18085","56902ae0741e9c0d00af2fc6","56902aee48df220d004ca226","56902af8f7eb9a0d00f44674","56902b26efcc380d0043a5b1","56902b8148df220d004ca22a","56902ba918c3920d00be8b55","56902bb96c49d70d00f1808b","56902bc818c3920d00be8b57","56902bd518c3920d00be8b59","56902be218c3920d00be8b5b","56902bf66c49d70d00f1808e","56902c05e056c80d00fdec5d","56902c196c49d70d00f18090","56902c2648df220d004ca22d","56902c34f7eb9a0d00f44678","56902c5518c3920d00be8b5d","56902c62741e9c0d00af2fcc","56902cde48df220d004ca230","56902cea741e9c0d00af2fcf","56902d0ae056c80d00fdec60","56902d20efcc380d0043a5b4","56902d3448df220d004ca232","5696c3fbf9203821005fe2fb","5696c3fb9e2d000d00947ab0","5696c3fbf9203821005fe2fa","5697efee8d2a770d00d2fd17","569802611c4dc823005426c7","56a65c82b3ffe00d00156eaf","56f01f88332da41700f24b74"],"project":"568fde81b700ce0d002f4b43","version":"568fde82b700ce0d002f4b46","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-08T18:41:53.562Z","from_sync":false,"order":1,"slug":"commands","title":"Commands"},"parentDoc":null,"project":"568fde81b700ce0d002f4b43","user":"568fffce769f210d0013258f","version":{"__v":23,"_id":"568fde82b700ce0d002f4b46","project":"568fde81b700ce0d002f4b43","createdAt":"2016-01-08T16:06:26.373Z","releaseDate":"2016-01-08T16:06:26.373Z","categories":["568fde82b700ce0d002f4b47","568ff0e504440a1700e4cbbd","569002f19ebef90d0087289d","569004f4769f210d00132599","5690056d9ebef90d008728a0","569005d394c5030d0028813a","5690067804440a1700e4cbe2","569137eb3c4f510d00ec9b92","56913815e56a790d008dbfe3","569138ba3c4f510d00ec9b93","5691392f3c4f510d00ec9b94","56913bbe72f2810d007e4cb0","56933b8d6ebadc0d005b71d2","56933b8d6ebadc0d005b71d3","569564facaa32519009c41e6","5696a319b6d61f0d00acfb40","5696a319a857080d0082e8e8","5697efe43503e40d0061f4d1","5697efe48d2a770d00d2fd16","569e9597ffccd10d00a05c59","56a7a1523d33bc2100793d5c","56a7a32ecf6d771700baeee8","56b8b0f7ddeb231700e69825"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"bar","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-02-05T18:57:48.115Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"auth":"required","params":[],"url":""},"isReference":false,"order":10,"body":"`cy.clock` overrides native global functions related to time, so you can test code using those functions in an easier, synchronous way. This includes the `setTimeout`, `clearTimeout`, `setInterval`, and `clearInterval` functions as well as controlling `Date` objects. Note that this only applies to the `top` window on a web page. It will not override the time functions on any iframes embedded on the web page.\n\n`cy.clock` automatically restores the native functions in between tests without you having to explicitly restore them. You can still manually restore the functions within a test by calling `.restore()` on the `clock` object that `cy.clock` yields.\n\n`cy.clock` pairs with [`cy.tick`](https://on.cypress.io/api/tick), which moves the clock along a certain number of milliseconds.\n\nSubsequent calls to `cy.clock` will yield the `clock` object without re-overriding the native time functions.\n\nIf you call `cy.clock` before visiting a page with [`cy.visit`](https://on.cypress.io/api/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`](https://on.cypress.io/api/tick). This also applies if, during the course of a test, the page under test is reloaded or changed.\n\n| | |\n|--- | --- |\n| **Returns** | a `clock` object. See [clock API](#section-clock-api) |\n\n***\n\n# [cy.clock()](#section-usage)\n\nReplaces `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` and `Date` and allows them to be controlled synchronously via [`cy.tick`](https://on.cypress.io/api/tick) or the yielded `clock` object (see [clock API](#section-clock-api)).\n\nThe 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`.\n\n***\n\n# [cy.clock( *now* )](#section-specify-the-now-timestamp)\n\nSame as above, but starts the clock at the specified timestamp.\n\n***\n\n# [cy.clock( *now*, *functionNames* )](#section-specify-which-functions-to-override)\n\nSame as above, but only overrides the functions in the array `functionNames`.\n\n***\n\n# clock API\n\n`cy.clock` yields a `clock` object with the following methods. You can also access the `clock` object via `this.clock` in a [`cy.then`](https://on.cypress.io/api/then) callback.\n\n## clock.tick(*milliseconds*)\n\nMove the clock the specified number of `milliseconds`. Any timers within the affected range of time will be called.\n\n## clock.restore()\n\nRestore all overridden native functions. This is automatically called between tests, so should not generally be needed.\n\n***\n\n# Options\n\nPass in an options object to change the default behavior of `cy.clock`.\n\n**cy.clock( *options* )**\n\n**cy.clock( *now*,  *options* )**\n\n**cy.clock( *now*, *functionNames*,  *options* )**\n\nOption | Default | Notes\n--- | --- | ---\n`log` | `true` | whether to display command in command log\n\n***\n\n# Usage\n\n## Create a clock and use it to trigger a setInterval\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// your app code\\nvar seconds = 0\\n\\nsetInterval(function(){\\n  $('#seconds-elapsed').text(++seconds + ' seconds')\\n}, 1000)\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// test code\\ncy\\n  .clock()\\n  .visit(\\\"/index.html\\\")\\n  .tick(1000)\\n  .get(\\\"#seconds-elapsed\\\")\\n    .should(\\\"have.text\\\", \\\"1 seconds\\\")\\n  .tick(1000)\\n  .get(\\\"#seconds-elapsed\\\")\\n    .should(\\\"have.text\\\", \\\"2 seconds\\\")\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## Specify the now timestamp\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// your app code\\n$('#date').text(new Date().toJSON())\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// test code\\nconst now = new Date(2017, 2, 14).getTime() // March 14, 2017 timestamp\\n\\ncy\\n  .clock(now)\\n  .visit(\\\"/index.html\\\")\\n  .get(\\\"#date\\\")\\n    .contains(\\\"2017-03-14\\\")\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## Specify which functions to override\n\nThis will only override `setTimeout` and `clearTimeout` and leave the other time-related functions as they are.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy.clock(null, [\\\"setTimeout\\\", \\\"clearTimeout\\\"])\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## Access the clock object to synchronously move time\n\nIn most cases, it's easier to [`cy.tick`](https://on.cypress.io/api/tick) to move time, but you can also use `clock` object yielded by `cy.clock`.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy.clock().then(function (clock) {\\n  clock.tick(1000)\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nYou can call `cy.clock` again for this purpose later in a chain if necessary.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy\\n  .clock()\\n  .get(\\\"#foo\\\")\\n  .type(\\\"Foo\\\")\\n  .clock().then(function (clock) {\\n    clock.tick(1000)\\n  })\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nThe clock object is also available via `this.clock` in any `.then` callback.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy\\n  .clock()\\n  .get(\\\"#foo\\\").then(function ($foo) {\\n    this.clock.tick(1000)\\n    // do something with $foo ...\\n  })\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## Access the clock object to restore native functions\n\nIn general, it should not be necessary to manually restore the native functions that `cy.clock` overrides, since this is done automatically between tests. But if you need to, the `clock` object yielded has `.restore` method.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy.clock().then(function (clock) {\\n  clock.restore()\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nOr via `this.clock`:\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy\\n  .clock()\\n  .get(\\\"#foo\\\").then(function ($foo) {\\n    this.clock.restore()\\n    // do something with $foo ...\\n  })\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## Example Recipe\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"[Check out our example recipe testing spying, stubbing and time](https://github.com/cypress-io/cypress-example-recipes/blob/master/cypress/integration/spy_stub_clock_spec.js)\",\n  \"title\": \"Using cy.clock and cy.tick\"\n}\n[/block]\n\n***\n\n# Command Log\n\n## Create a clock and tick it 1 second\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy\\n  .clock()\\n  .tick(1000)\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nThe command above will display in the command log as:\n\n<img width=\"448\" alt=\"screen shot of command log\" src=\"https://cloud.githubusercontent.com/assets/1157043/22437918/059f60a6-e6f8-11e6-903d-d868e044615d.png\">\n\nWhen clicking on the `clock` command within the command log, the console outputs the following:\n\n<img width=\"1059\" alt=\"screen shot of console output\" src=\"https://cloud.githubusercontent.com/assets/1157043/22437920/0786f9d8-e6f8-11e6-9e77-926b15aa8dae.png\">\n\n***\n\n# Related\n\n- [Guide: Stubs, Spies and Clocks ](https://on.cypress.io/guides/stubs-spies-clocks)\n- [Recipe: Controlling Behavior with Spies, Stubs, and Clocks](https://github.com/cypress-io/cypress-example-recipes#controlling-behavior-with-spies-stubs-and-clocks)\n- [tick](https://on.cypress.io/api/tick)\n- [spy](https://on.cypress.io/api/spy)\n- [stub](https://on.cypress.io/api/stub)","excerpt":"Control time in the browser","slug":"clock","type":"basic","title":"clock"}

clock

Control time in the browser

`cy.clock` overrides native global functions related to time, so you can test code using those functions in an easier, synchronous way. This includes the `setTimeout`, `clearTimeout`, `setInterval`, and `clearInterval` functions as well as controlling `Date` objects. Note that this only applies to the `top` window on a web page. It will not override the time functions on any iframes embedded on the web page. `cy.clock` automatically restores the native functions in between tests without you having to explicitly restore them. You can still manually restore the functions within a test by calling `.restore()` on the `clock` object that `cy.clock` yields. `cy.clock` pairs with [`cy.tick`](https://on.cypress.io/api/tick), which moves the clock along a certain number of milliseconds. Subsequent calls to `cy.clock` will yield the `clock` object without re-overriding the native time functions. If you call `cy.clock` before visiting a page with [`cy.visit`](https://on.cypress.io/api/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`](https://on.cypress.io/api/tick). This also applies if, during the course of a test, the page under test is reloaded or changed. | | | |--- | --- | | **Returns** | a `clock` object. See [clock API](#section-clock-api) | *** # [cy.clock()](#section-usage) Replaces `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` and `Date` and allows them to be controlled synchronously via [`cy.tick`](https://on.cypress.io/api/tick) or the yielded `clock` object (see [clock API](#section-clock-api)). 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`. *** # [cy.clock( *now* )](#section-specify-the-now-timestamp) Same as above, but starts the clock at the specified timestamp. *** # [cy.clock( *now*, *functionNames* )](#section-specify-which-functions-to-override) Same as above, but only overrides the functions in the array `functionNames`. *** # clock API `cy.clock` yields a `clock` object with the following methods. You can also access the `clock` object via `this.clock` in a [`cy.then`](https://on.cypress.io/api/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 not generally be needed. *** # Options Pass in an options object to change the default behavior of `cy.clock`. **cy.clock( *options* )** **cy.clock( *now*, *options* )** **cy.clock( *now*, *functionNames*, *options* )** Option | Default | Notes --- | --- | --- `log` | `true` | whether to display command in command log *** # Usage ## Create a clock and use it to trigger a setInterval [block:code] { "codes": [ { "code": "// your app code\nvar seconds = 0\n\nsetInterval(function(){\n $('#seconds-elapsed').text(++seconds + ' seconds')\n}, 1000)\n", "language": "javascript" } ] } [/block] [block:code] { "codes": [ { "code": "// test code\ncy\n .clock()\n .visit(\"/index.html\")\n .tick(1000)\n .get(\"#seconds-elapsed\")\n .should(\"have.text\", \"1 seconds\")\n .tick(1000)\n .get(\"#seconds-elapsed\")\n .should(\"have.text\", \"2 seconds\")\n", "language": "javascript" } ] } [/block] *** ## Specify the now timestamp [block:code] { "codes": [ { "code": "// your app code\n$('#date').text(new Date().toJSON())\n", "language": "javascript" } ] } [/block] [block:code] { "codes": [ { "code": "// test code\nconst now = new Date(2017, 2, 14).getTime() // March 14, 2017 timestamp\n\ncy\n .clock(now)\n .visit(\"/index.html\")\n .get(\"#date\")\n .contains(\"2017-03-14\")\n", "language": "javascript" } ] } [/block] *** ## Specify which functions to override This will only override `setTimeout` and `clearTimeout` and leave the other time-related functions as they are. [block:code] { "codes": [ { "code": "cy.clock(null, [\"setTimeout\", \"clearTimeout\"])\n", "language": "javascript" } ] } [/block] *** ## Access the clock object to synchronously move time In most cases, it's easier to [`cy.tick`](https://on.cypress.io/api/tick) to move time, but you can also use `clock` object yielded by `cy.clock`. [block:code] { "codes": [ { "code": "cy.clock().then(function (clock) {\n clock.tick(1000)\n})\n", "language": "javascript" } ] } [/block] You can call `cy.clock` again for this purpose later in a chain if necessary. [block:code] { "codes": [ { "code": "cy\n .clock()\n .get(\"#foo\")\n .type(\"Foo\")\n .clock().then(function (clock) {\n clock.tick(1000)\n })\n", "language": "javascript" } ] } [/block] The clock object is also available via `this.clock` in any `.then` callback. [block:code] { "codes": [ { "code": "cy\n .clock()\n .get(\"#foo\").then(function ($foo) {\n this.clock.tick(1000)\n // do something with $foo ...\n })\n", "language": "javascript" } ] } [/block] *** ## Access the clock object to restore native functions In general, it should not be necessary to manually restore the native functions that `cy.clock` overrides, since this is done automatically between tests. But if you need to, the `clock` object yielded has `.restore` method. [block:code] { "codes": [ { "code": "cy.clock().then(function (clock) {\n clock.restore()\n})\n", "language": "javascript" } ] } [/block] Or via `this.clock`: [block:code] { "codes": [ { "code": "cy\n .clock()\n .get(\"#foo\").then(function ($foo) {\n this.clock.restore()\n // do something with $foo ...\n })\n", "language": "javascript" } ] } [/block] *** ## Example Recipe [block:callout] { "type": "info", "body": "[Check out our example recipe testing spying, stubbing and time](https://github.com/cypress-io/cypress-example-recipes/blob/master/cypress/integration/spy_stub_clock_spec.js)", "title": "Using cy.clock and cy.tick" } [/block] *** # Command Log ## Create a clock and tick it 1 second [block:code] { "codes": [ { "code": "cy\n .clock()\n .tick(1000)\n", "language": "javascript" } ] } [/block] The command above will display in the command log as: <img width="448" alt="screen shot of command log" src="https://cloud.githubusercontent.com/assets/1157043/22437918/059f60a6-e6f8-11e6-903d-d868e044615d.png"> When clicking on the `clock` command within the command log, the console outputs the following: <img width="1059" alt="screen shot of console output" src="https://cloud.githubusercontent.com/assets/1157043/22437920/0786f9d8-e6f8-11e6-9e77-926b15aa8dae.png"> *** # Related - [Guide: Stubs, Spies and Clocks ](https://on.cypress.io/guides/stubs-spies-clocks) - [Recipe: Controlling Behavior with Spies, Stubs, and Clocks](https://github.com/cypress-io/cypress-example-recipes#controlling-behavior-with-spies-stubs-and-clocks) - [tick](https://on.cypress.io/api/tick) - [spy](https://on.cypress.io/api/spy) - [stub](https://on.cypress.io/api/stub)