{"_id":"56995ac854d7db17000ee9e5","parentDoc":null,"__v":0,"user":"568fffce769f210d0013258f","category":{"_id":"5697efe48d2a770d00d2fd16","version":"568fde82b700ce0d002f4b46","__v":50,"pages":["5697f9021c4dc823005426a7","5697f9a7d231880d00676f88","5697f9a72cf4060d004eaa98","5697f9a71c4dc823005426a9","5697f9a82cf4060d004eaa99","5697f9a82cf4060d004eaa9a","5697f9a81c4dc823005426aa","5697f9a869393517000c8451","5697f9a73503e40d0061f4e1","5697f9a869393517000c8452","5697f9a92cf4060d004eaa9b","5697f9a88560a60d00e2c398","5697f9a81c4dc823005426ab","5697fe158560a60d00e2c3a6","5697fe15d231880d00676f8e","56995ac8cb127f0d003cc165","56995ac854d7db17000ee9e5","56995ac8113a901900ef8f78","56995ac8113a901900ef8f77","56a0ff2a8b2e6f0d0018e94b","56ab8b29c159aa0d0070de3d","56ab8b290b9e0b0d00616230","56ab8b294e8ba20d006a2377","56ab8b2935138c0d005c944e","56ab8b2af25f160d00e17ef8","56ab8b624e4b730d009eb09e","56ab8b62f25f160d00e17ef9","56ab8b62d4432d1900eed1b0","56ab8b62678b58170031ebb2","56ab8b62678b58170031ebb1","56ab8bf435138c0d005c9450","56ab8bf44e4b730d009eb0a1","56ab8bf435138c0d005c9451","56ab8bf5f9757e0d007c65e7","56ab8bf58beeff0d003b809a","56ab8c3ef25f160d00e17efc","56ab8c3f4e8ba20d006a237a","56ab8c3f8beeff0d003b809b","56ab8c3f4e4b730d009eb0a2","56ab8c3f0b9e0b0d00616234","56ab8c704e4b730d009eb0a3","56ab8c709327b30d00f7c1f1","56ab8c714e8ba20d006a237c","56ab8c71f9757e0d007c65e9","56ab8c71f9757e0d007c65ea","56ab8ce8678b58170031ebbd","56ab8ce78beeff0d003b809d","56ab8ce70b9e0b0d00616237","56ab8ce84e4b730d009eb0a4","56ab8ce84e8ba20d006a237d"],"project":"568fde81b700ce0d002f4b43","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-14T18:58:44.771Z","from_sync":false,"order":3,"slug":"cypress-api","title":"Cypress API"},"version":{"_id":"568fde82b700ce0d002f4b46","__v":23,"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"},"project":"568fde81b700ce0d002f4b43","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-15T20:47:04.765Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"`Cypress.Cookies` is a synchronous interface that allows you to do more than just get, set, or clear cookies.\n\nTypically you'd use `Cypress.Cookies` in hooks like `before`, `beforeEach`, `after`, and `afterEach`.\n\nCypress automatically clears all cookies **before** each test to prevent state from building up. You can take advantage of `Cypress.Cookies.preserveOnce` or even **whitelist** cookies by their name to preserve values across multiple tests. This enables you to preserve sessions through several tests.\n\n# [Cypress.Cookies.debug( *boolean*, *options* )](#section-debug-usage)\n\nEnable or disable cookie debugging. When enabled, Cypress will log out when cookies are set or cleared.\n\n***\n\n# [Cypress.Cookies.preserveOnce( *name1*, *name2*, *name3*, ... )](#section-preserve-usage)\n\nWill preserve cookies by name. Pass an unlimited number of arguments. These preserved cookies will not be cleared before the next test starts.\n\n***\n\n# [Cypress.Cookies.defaults( *options* )](#section-defaults-usage)\n\nSet defaults for all cookies, such as whitelisting a set of cookies to bypass being cleared before each test.\n\n***\n\n# Debug Usage\n\n## Log out when cookie values set or clear\n\nBy turning on debugging, Cypress will automatically log out to the console when it **sets** or **clears** cookie values. This is useful to help you understand how Cypress clears cookies before each test, and is useful to visualize how to handle preserving cookies in between tests.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"Cypress.Cookies.debug(true) // now Cypress will log out when it alters cookies\\n\\ncy.clearCookie('foo')\\ncy.setCookie('foo', 'bar')\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n![screen shot 2016-05-22 at 8 54 00 pm](https://cloud.githubusercontent.com/assets/1268976/15457855/e2b6e99c-205f-11e6-8b25-ac6e0dcae9ce.png)\n\n## Turn off verbose debugging output\n\nBy default Cypress will log out the cookie object which allows you to inspect all of its properties. However you may not need that level of detail and you can turn this off.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"Cypress.Cookies.debug(true, {verbose: false})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nNow when Cypress logs cookies they will only include the `name` and `value`.\n\n![screen shot 2016-05-22 at 8 54 13 pm](https://cloud.githubusercontent.com/assets/1268976/15457832/680bc71c-205f-11e6-9b8b-1c84380790e0.png)\n\nDebugging will be turned on until you explictly turn it back off.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"Cypress.Cookies.debug(false) // now debugging is turned off\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n# Preserve Usage\n\n## Preserve cookies through multiple tests\n\nCypress gives you a simple interface to automatically preserve cookies for multiple tests. Cypress automatically clears all cookies before each new test starts by default.\n\nBy clearing cookies before each test you are gauranteed to always start from a clean slate. Starting from a clean state prevents coupling your tests to one another and prevents situations where mutating something in your application in one test affects another one downstream.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The most common use case for preserving cookies is to prevent having to log in to your application before each individual test. This is a problem if the majority of each test is spent logging in a user.\"\n}\n[/block]\n\nYou can use `Cypress.Cookies.preserveOnce` to preserve cookies through multiple tests.\n\nThere are *likely* better ways to do this, but this isn't well documented at the moment. Every application is different and there is no one-size-fits-all solution. For the moment, if you're using session-based cookies, this method will work.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"describe(\\\"Dashboard\\\", function(){\\n  before(function(){\\n    // log in only once before any of the tests run.\\n    // your app will likely set some sort of session cookie.\\n    // you'll need to know the name of the cookie(s), which you can find\\n    // in your Resources -> Cookies panel in the Chrome Dev Tools.\\n    cy.login()\\n  })\\n\\n  beforeEach(function(){\\n    // before each test, we can automatically preserve the\\n    // 'session_id' and 'remember_token' cookies. this means they\\n    // will not be cleared before the NEXT test starts.\\n    //\\n    // the name of your cookies will likely be different\\n    // this is just a simple example\\n    Cypress.Cookies.preserveOnce(\\\"session_id\\\", \\\"remember_token\\\")\\n  })\\n\\n  it(\\\"displays stats\\\", function(){\\n    // ...\\n  })\\n\\n  it(\\\"can do something\\\", function(){\\n    // ...\\n  })\\n\\n  it(\\\"opens a modal\\\", function(){\\n    // ...\\n  })\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n# Defaults Usage\n\n## Set global default cookies\n\nYou can modify the global defaults and whitelist a set of Cookies which will always be preserved across tests.\n\nAny change you make here will take effect immediately for the remainder of every single test.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"A great place to put this configuration is in your `cypress/support/defaults.js` file, since it is loaded before any test files are evaluated.\"\n}\n[/block]\n\n**Whitelist accepts:**\n\n- string\n- array\n- regexp\n- function\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// string usage\\n\\n// now any cookie with the name 'session_id' will\\n// not be cleared before each test runs\\nCypress.Cookies.defaults({\\n  whitelist: \\\"session_id\\\"\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// array usage\\n\\n// now any cookie with the name 'session_id' or 'remember_token'\\n// will not be cleared before each test runs\\nCypress.Cookies.defaults({\\n  whitelist: [\\\"session_id\\\", \\\"remember_token\\\"]\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// RegExp usage\\n\\n// now any cookie that matches this RegExp\\n// will not be cleared before each test runs\\nCypress.Cookies.defaults({\\n  whitelist: /session|remember/\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// function usage\\n\\nCypress.Cookies.defaults({\\n  whitelist: function(cookie){\\n    // implement your own logic here\\n    // if the function returns truthy\\n    // then the cookie will not be cleared\\n    // before each test runs\\n  }\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n# Related\n\n- [clearCookie](https://on.cypress.io/api/clearcookie)\n- [clearCookies](https://on.cypress.io/api/clearcookies)\n- [getCookie](https://on.cypress.io/api/getcookie)\n- [getCookies](https://on.cypress.io/api/getcookies)\n- [setCookie](https://on.cypress.io/api/setcookie)","excerpt":"Manage your application's cookies","slug":"cookies","type":"basic","title":"Cookies"}

Cookies

Manage your application's cookies

`Cypress.Cookies` is a synchronous interface that allows you to do more than just get, set, or clear cookies. Typically you'd use `Cypress.Cookies` in hooks like `before`, `beforeEach`, `after`, and `afterEach`. Cypress automatically clears all cookies **before** each test to prevent state from building up. You can take advantage of `Cypress.Cookies.preserveOnce` or even **whitelist** cookies by their name to preserve values across multiple tests. This enables you to preserve sessions through several tests. # [Cypress.Cookies.debug( *boolean*, *options* )](#section-debug-usage) Enable or disable cookie debugging. When enabled, Cypress will log out when cookies are set or cleared. *** # [Cypress.Cookies.preserveOnce( *name1*, *name2*, *name3*, ... )](#section-preserve-usage) Will preserve cookies by name. Pass an unlimited number of arguments. These preserved cookies will not be cleared before the next test starts. *** # [Cypress.Cookies.defaults( *options* )](#section-defaults-usage) Set defaults for all cookies, such as whitelisting a set of cookies to bypass being cleared before each test. *** # Debug Usage ## Log out when cookie values set or clear By turning on debugging, Cypress will automatically log out to the console when it **sets** or **clears** cookie values. This is useful to help you understand how Cypress clears cookies before each test, and is useful to visualize how to handle preserving cookies in between tests. [block:code] { "codes": [ { "code": "Cypress.Cookies.debug(true) // now Cypress will log out when it alters cookies\n\ncy.clearCookie('foo')\ncy.setCookie('foo', 'bar')\n", "language": "javascript" } ] } [/block] ![screen shot 2016-05-22 at 8 54 00 pm](https://cloud.githubusercontent.com/assets/1268976/15457855/e2b6e99c-205f-11e6-8b25-ac6e0dcae9ce.png) ## Turn off verbose debugging output By default Cypress will log out the cookie object which allows you to inspect all of its properties. However you may not need that level of detail and you can turn this off. [block:code] { "codes": [ { "code": "Cypress.Cookies.debug(true, {verbose: false})\n", "language": "javascript" } ] } [/block] Now when Cypress logs cookies they will only include the `name` and `value`. ![screen shot 2016-05-22 at 8 54 13 pm](https://cloud.githubusercontent.com/assets/1268976/15457832/680bc71c-205f-11e6-9b8b-1c84380790e0.png) Debugging will be turned on until you explictly turn it back off. [block:code] { "codes": [ { "code": "Cypress.Cookies.debug(false) // now debugging is turned off\n", "language": "javascript" } ] } [/block] *** # Preserve Usage ## Preserve cookies through multiple tests Cypress gives you a simple interface to automatically preserve cookies for multiple tests. Cypress automatically clears all cookies before each new test starts by default. By clearing cookies before each test you are gauranteed to always start from a clean slate. Starting from a clean state prevents coupling your tests to one another and prevents situations where mutating something in your application in one test affects another one downstream. [block:callout] { "type": "info", "body": "The most common use case for preserving cookies is to prevent having to log in to your application before each individual test. This is a problem if the majority of each test is spent logging in a user." } [/block] You can use `Cypress.Cookies.preserveOnce` to preserve cookies through multiple tests. There are *likely* better ways to do this, but this isn't well documented at the moment. Every application is different and there is no one-size-fits-all solution. For the moment, if you're using session-based cookies, this method will work. [block:code] { "codes": [ { "code": "describe(\"Dashboard\", function(){\n before(function(){\n // log in only once before any of the tests run.\n // your app will likely set some sort of session cookie.\n // you'll need to know the name of the cookie(s), which you can find\n // in your Resources -> Cookies panel in the Chrome Dev Tools.\n cy.login()\n })\n\n beforeEach(function(){\n // before each test, we can automatically preserve the\n // 'session_id' and 'remember_token' cookies. this means they\n // will not be cleared before the NEXT test starts.\n //\n // the name of your cookies will likely be different\n // this is just a simple example\n Cypress.Cookies.preserveOnce(\"session_id\", \"remember_token\")\n })\n\n it(\"displays stats\", function(){\n // ...\n })\n\n it(\"can do something\", function(){\n // ...\n })\n\n it(\"opens a modal\", function(){\n // ...\n })\n})\n", "language": "javascript" } ] } [/block] *** # Defaults Usage ## Set global default cookies You can modify the global defaults and whitelist a set of Cookies which will always be preserved across tests. Any change you make here will take effect immediately for the remainder of every single test. [block:callout] { "type": "info", "body": "A great place to put this configuration is in your `cypress/support/defaults.js` file, since it is loaded before any test files are evaluated." } [/block] **Whitelist accepts:** - string - array - regexp - function [block:code] { "codes": [ { "code": "// string usage\n\n// now any cookie with the name 'session_id' will\n// not be cleared before each test runs\nCypress.Cookies.defaults({\n whitelist: \"session_id\"\n})\n", "language": "javascript" } ] } [/block] [block:code] { "codes": [ { "code": "// array usage\n\n// now any cookie with the name 'session_id' or 'remember_token'\n// will not be cleared before each test runs\nCypress.Cookies.defaults({\n whitelist: [\"session_id\", \"remember_token\"]\n})\n", "language": "javascript" } ] } [/block] [block:code] { "codes": [ { "code": "// RegExp usage\n\n// now any cookie that matches this RegExp\n// will not be cleared before each test runs\nCypress.Cookies.defaults({\n whitelist: /session|remember/\n})\n", "language": "javascript" } ] } [/block] [block:code] { "codes": [ { "code": "// function usage\n\nCypress.Cookies.defaults({\n whitelist: function(cookie){\n // implement your own logic here\n // if the function returns truthy\n // then the cookie will not be cleared\n // before each test runs\n }\n})\n", "language": "javascript" } ] } [/block] *** # Related - [clearCookie](https://on.cypress.io/api/clearcookie) - [clearCookies](https://on.cypress.io/api/clearcookies) - [getCookie](https://on.cypress.io/api/getcookie) - [getCookies](https://on.cypress.io/api/getcookies) - [setCookie](https://on.cypress.io/api/setcookie)