{"__v":0,"_id":"589775ad8154840f00c72b1b","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:49.584Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"auth":"required","params":[],"url":""},"isReference":false,"order":56,"body":"A stub is used to replace a function, record its usage and control its behavior. You can track calls to the functions and what arguments the function was called with. You can also control what the function returns and even cause it to throw an exception.\n\n`cy.stub` returns a [sinon.js stub](http://sinonjs.org/docs/#stubs). All methods found on sinon.js spies and stubs are supported. `cy.stub` creates stubs in a [sandbox](http://sinonjs.org/docs/#sandbox), so all stubs created are automatically reset/restored between tests without you having to explicitly reset/restore them.\n\nCypress has built-in [sinon-as-promised](https://github.com/bendrucker/sinon-as-promised) support, so the stubs returned by `cy.stub` supports the `.resolves` and `.rejects` API provided by `sinon-as-promised`.\n\nCypress also has built-in [sinon-chai](https://github.com/domenic/sinon-chai) support, so any [assertions](https://github.com/domenic/sinon-chai#assertions) supported by `sinon-chai` can be used without any configuration.\n\nUnlike most Cypress commands, `cy.stub` is *synchronous* and returns a value (the stub) instead of a Promise-like chain-able object.\n\n| | |\n|--- | --- |\n| **Returns** | the stub |\n\n***\n\n# [cy.stub()](#section-usage)\n\nCreates and returns a stub. See the [sinon.js stub docs](http://sinonjs.org/docs/#stubs) for methods on the stub.\n\n***\n\n# [cy.stub( *object*, *\"method\"* )](#section-replace-a-method-with-a-stub)\n\nReplaces the `method` on the `object` with a stub and returns the stub. See the [sinon.js stub docs](http://sinonjs.org/docs/#stubs) for methods on the stub.\n\n***\n\n# [cy.stub( *object*, *\"method\"*, replacerFn )](#section-replace-a-method-with-a-function)\n\nReplaces the `method` on the `object` with the `replacerFn` wrapped in a spy.See the [sinon.js spy docs](http://sinonjs.org/docs/#spies) for methods on the spy.\n\n***\n\n# Usage\n\n## Create a stub and manually replace a function\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// assume App.start calls util.addListeners\\nutil.addListeners = cy.stub()\\nApp.start()\\nexpect(util.addListeners).to.be.called\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## Replace a method with a stub\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// assume App.start calls util.addListeners\\ncy.stub(util, \\\"addListeners\\\")\\nApp.start()\\nexpect(util.addListeners).to.be.called\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## Replace a method with a function\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// assume App.start calls util.addListeners\\nlet listenersAdded = false\\ncy.stub(util, \\\"addListeners\\\", function () {\\n  listenersAdded = true\\n})\\nApp.start()\\nexpect(listenersAdded).to.be.true\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## Specify the return value of a stubbed method\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// assume App.start calls util.addListeners, which returns a function\\n// that removes the listeners\\nconst removeStub = cy.stub()\\ncy.stub(util, \\\"addListeners\\\").returns(removeStub)\\nApp.start()\\nApp.stop()\\nexpect(removeStub).to.be.called\\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.stub\"\n}\n[/block]\n\n***\n\n## Alias a stub\n\nAdding an alias using [`cy.as`](https://on.cypress.io/api/as) to stubs makes them easier to identify in error messages and Cypress's command log.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"const obj = {\\n  foo () {}\\n}\\nconst stub = cy.stub(obj, \\\"foo\\\").as(\\\"anyArgs\\\")\\nconst withFoo = stub.withArgs(\\\"foo\\\").as(\\\"withFoo\\\")\\nobj.foo()\\nexpect(stub).to.be.called\\nexpect(withFoo).to.be.called // purposefully failing assertion\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nYou will see the following in the command log:\n\n![stubs with aliases](https://cloud.githubusercontent.com/assets/1157043/22437243/4cc778a4-e6f5-11e6-8f07-e601d3438c4f.png)\n\n***\n\n# Command Log\n\n## Create a stub, alias it, and call it\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"const obj = {\\n  foo () {}\\n}\\nconst stub = cy.stub(obj, \\\"foo\\\").as(\\\"foo\\\")\\nobj.foo(\\\"foo\\\", \\\"bar\\\")\\nexpect(stub).to.be.called\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nThe command above will display in the command log as:\n\n<img width=\"454\" alt=\"screen shot of command log\" src=\"https://cloud.githubusercontent.com/assets/1157043/22437473/335f7104-e6f6-11e6-8ee8-74dc21e7d4fa.png\">\n\nWhen clicking on the `(stub-1)` event within the command log, the console outputs the following:\n\n<img width=\"585\" alt=\"screen shot of console output\" src=\"https://cloud.githubusercontent.com/assets/1157043/22437546/6b01e574-e6f6-11e6-878f-e10c2316d213.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- [Recipe: Unit Test - Stubbing Dependencies](https://github.com/cypress-io/cypress-example-recipes#unit-test---stubbing-dependencies)\n- [spy](https://on.cypress.io/api/spy)\n- [clock](https://on.cypress.io/api/clock)","excerpt":"Create a stub and/or replace a function with a stub","slug":"stub","type":"basic","title":"stub"}

stub

Create a stub and/or replace a function with a stub

A stub is used to replace a function, record its usage and control its behavior. You can track calls to the functions and what arguments the function was called with. You can also control what the function returns and even cause it to throw an exception. `cy.stub` returns a [sinon.js stub](http://sinonjs.org/docs/#stubs). All methods found on sinon.js spies and stubs are supported. `cy.stub` creates stubs in a [sandbox](http://sinonjs.org/docs/#sandbox), so all stubs created are automatically reset/restored between tests without you having to explicitly reset/restore them. Cypress has built-in [sinon-as-promised](https://github.com/bendrucker/sinon-as-promised) support, so the stubs returned by `cy.stub` supports the `.resolves` and `.rejects` API provided by `sinon-as-promised`. Cypress also has built-in [sinon-chai](https://github.com/domenic/sinon-chai) support, so any [assertions](https://github.com/domenic/sinon-chai#assertions) supported by `sinon-chai` can be used without any configuration. Unlike most Cypress commands, `cy.stub` is *synchronous* and returns a value (the stub) instead of a Promise-like chain-able object. | | | |--- | --- | | **Returns** | the stub | *** # [cy.stub()](#section-usage) Creates and returns a stub. See the [sinon.js stub docs](http://sinonjs.org/docs/#stubs) for methods on the stub. *** # [cy.stub( *object*, *"method"* )](#section-replace-a-method-with-a-stub) Replaces the `method` on the `object` with a stub and returns the stub. See the [sinon.js stub docs](http://sinonjs.org/docs/#stubs) for methods on the stub. *** # [cy.stub( *object*, *"method"*, replacerFn )](#section-replace-a-method-with-a-function) Replaces the `method` on the `object` with the `replacerFn` wrapped in a spy.See the [sinon.js spy docs](http://sinonjs.org/docs/#spies) for methods on the spy. *** # Usage ## Create a stub and manually replace a function [block:code] { "codes": [ { "code": "// assume App.start calls util.addListeners\nutil.addListeners = cy.stub()\nApp.start()\nexpect(util.addListeners).to.be.called\n", "language": "javascript" } ] } [/block] *** ## Replace a method with a stub [block:code] { "codes": [ { "code": "// assume App.start calls util.addListeners\ncy.stub(util, \"addListeners\")\nApp.start()\nexpect(util.addListeners).to.be.called\n", "language": "javascript" } ] } [/block] *** ## Replace a method with a function [block:code] { "codes": [ { "code": "// assume App.start calls util.addListeners\nlet listenersAdded = false\ncy.stub(util, \"addListeners\", function () {\n listenersAdded = true\n})\nApp.start()\nexpect(listenersAdded).to.be.true\n", "language": "javascript" } ] } [/block] *** ## Specify the return value of a stubbed method [block:code] { "codes": [ { "code": "// assume App.start calls util.addListeners, which returns a function\n// that removes the listeners\nconst removeStub = cy.stub()\ncy.stub(util, \"addListeners\").returns(removeStub)\nApp.start()\nApp.stop()\nexpect(removeStub).to.be.called\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.stub" } [/block] *** ## Alias a stub Adding an alias using [`cy.as`](https://on.cypress.io/api/as) to stubs makes them easier to identify in error messages and Cypress's command log. [block:code] { "codes": [ { "code": "const obj = {\n foo () {}\n}\nconst stub = cy.stub(obj, \"foo\").as(\"anyArgs\")\nconst withFoo = stub.withArgs(\"foo\").as(\"withFoo\")\nobj.foo()\nexpect(stub).to.be.called\nexpect(withFoo).to.be.called // purposefully failing assertion\n", "language": "javascript" } ] } [/block] You will see the following in the command log: ![stubs with aliases](https://cloud.githubusercontent.com/assets/1157043/22437243/4cc778a4-e6f5-11e6-8f07-e601d3438c4f.png) *** # Command Log ## Create a stub, alias it, and call it [block:code] { "codes": [ { "code": "const obj = {\n foo () {}\n}\nconst stub = cy.stub(obj, \"foo\").as(\"foo\")\nobj.foo(\"foo\", \"bar\")\nexpect(stub).to.be.called\n", "language": "javascript" } ] } [/block] The command above will display in the command log as: <img width="454" alt="screen shot of command log" src="https://cloud.githubusercontent.com/assets/1157043/22437473/335f7104-e6f6-11e6-8ee8-74dc21e7d4fa.png"> When clicking on the `(stub-1)` event within the command log, the console outputs the following: <img width="585" alt="screen shot of console output" src="https://cloud.githubusercontent.com/assets/1157043/22437546/6b01e574-e6f6-11e6-878f-e10c2316d213.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) - [Recipe: Unit Test - Stubbing Dependencies](https://github.com/cypress-io/cypress-example-recipes#unit-test---stubbing-dependencies) - [spy](https://on.cypress.io/api/spy) - [clock](https://on.cypress.io/api/clock)