{"_id":"5696cda524490c3700170a05","category":{"_id":"56954a95fe18811700c9bfdf","pages":["56954a97fe18811700c9c01d","56954a97fe18811700c9c01e","56954a97fe18811700c9c01f","56954a97fe18811700c9c020","56954a97fe18811700c9c021","56954a97fe18811700c9c022","56954a97fe18811700c9c023","56954a97fe18811700c9c024","56954a97fe18811700c9c025","56954a97fe18811700c9c026","56954a97fe18811700c9c027","56954a97fe18811700c9c028","56954a97fe18811700c9c029","5696cda524490c3700170a05","5697efe61c4dc8230054268e","5697efe72cf4060d004eaa75","56993ff47465970d00650b8f","56a7a155dfdabc0d000ae910","56a7a155b5d0920d0051cd81","56a7a1a6cf6d771700baeee3","56a7a1a63d33bc2100793d5d","56a7a23097e8b00d0096d209","56a7a230ea3e3417000df4b1","56a7a25acf6d771700baeee6","56a7a25a03f28c0d00a545bf","56a7a2b83d33bc2100793d60","56a7a2b8b5d0920d0051cd82","56b27fe42db51f0d0044e566"],"project":"568fde81b700ce0d002f4b43","__v":16,"version":"56954a94fe18811700c9bfda","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-09T16:40:53.584Z","from_sync":false,"order":4,"slug":"guides","title":"Guides"},"parentDoc":null,"user":"568fffce769f210d0013258f","project":"568fde81b700ce0d002f4b43","version":{"_id":"56954a94fe18811700c9bfda","project":"568fde81b700ce0d002f4b43","__v":6,"createdAt":"2016-01-12T18:48:52.007Z","releaseDate":"2016-01-12T18:48:52.007Z","categories":["56954a95fe18811700c9bfdb","56954a95fe18811700c9bfdc","56954a95fe18811700c9bfdd","56954a95fe18811700c9bfde","56954a95fe18811700c9bfdf","56954a95fe18811700c9bfe0","56954a95fe18811700c9bfe1","56954a95fe18811700c9bfe2","56954a95fe18811700c9bfe3","56954a95fe18811700c9bfe4","5695649fdcaf0d1700cb8721","5696c1168560a60d00e2c1d6","56a7a32e79395317007c1ad6","5898fc3eec49fb0f004c2663","589cc675ea37da23004e05e1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"foo","version_clean":"0.0.0","version":"0.0"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-13T22:20:21.060Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"# Contents\n\n- :fa-angle-right: [Commands are Async](#section-commands-are-async)\n- :fa-angle-right: [Subjects](#section-subjects)\n- :fa-angle-right: [Chaining](#section-chaining)\n  - [Parent Commands](#section-parent-commands)\n  - [Child Commands](#section-child-commands)\n  - [Dual Commands](#section-dual-commands)\n\n***\n\n# Commands are Async\n\nWhen writing integration tests, you will need to traverse the DOM and perform user actions. In traditional server-side rendered views, it's unlikely you be deal with many application state changes. However, if you're writing an application using a modern JavaScript framework, you'll likely need to navigate through highly complex, dynamic states.\n\n> Cypress is designed to handle *both* traditional server-side rendered views & modern JavaScript framework applications.\n\nThe architecture of Cypress focuses around asynchronicity. The DOM is a highly complex, mutable object; to handle the indeterminate state of the DOM, we've designed our commands to be asynchronous.\n\n**Because all commands are async, this offers many advantages.**\n\n1. All commands can retry until a certain specified condition is met.\n2. Commands can be replayed, inserted between others, or even conditionally run.\n3. Cypress can look ahead (or look behind) at commands which have yet to run, and alter its behavior.\n\nCypress is designed to also handle the disadvantages of async. One example is [aliasing](https://on.cypress.io/guides/using-aliases). This works around the need to assign values to variables.\n\nThe [Command API](https://on.cypress.io/api) attempts to balance readability, terseness, flexibility, and capability all while being designed similar to familiar APIs. The [Command API](https://on.cypress.io/api) is also fluent - that is, you chain all commands together - similar to how jQuery's API is designed.\n\n***\n\n# Subjects\n\nCommands work just like JavaScript Promises. That is, the resolved value of one command becomes the `subject` of the next command - just like a waterfall.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy\\n  // when 'get' resolves, the subject\\n  // becomes the DOM element <div#main>\\n  .get(\\\"#main\\\")\\n\\n  // after 'get' resolves, the find command\\n  // runs and is passed <div#main> as its subject.\\n  // <div#main> becomes the subject that we 'find' on.\\n  .find(\\\"button\\\")\\n\\n  // after 'find' resolves, <button> becomes the new subject.\\n  // <button> is what the click operates on.\\n  // this is functionally equivalent to\\n  // writing $(\\\"#main\\\").find(\\\"button\\\").click() in jQuery.\\n  .click()\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nThe difference between the Cypress API and jQuery's API is that *all* commands are async. **No command returns an actual assignable value.** That is because every command is queued, ran, and retried until it resolves. Some commands may not resolve until several seconds after they are run.\n\nFor instance you **cannot** do this:\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// THIS WILL NOT WORK!\\nbutton = cy.get(\\\"#main\\\").find(\\\"button\\\")\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nJust like Promises, the value that async commands return can only be yielded in a callback function.\n\nIf you want to retrieve the resolved value (the subject) of a command, use a [`then`](https://on.cypress.io/api/then) command, the same way you would with Promises.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy.get(\\\"#main\\\").find(\\\"button\\\").then(function($button){\\n  // when the 'find' command resolves, we can yield its\\n  // resolved value (the new subject) in a callback function.\\n  // now we can work with this value directly.\\n  $button.trigger(\\\"click\\\")\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nWhen chaining together multiple commands you rarely should need to yield the subject via a [`cy.then`](https://on.cypress.io/api/then) command. Cypress favors readability and terseness, and even [assertions](https://on.cypress.io/guides/making-assertions) can be implicitly run without having to use a [`cy.then`](https://on.cypress.io/api/then) command.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// we're testing that an 'active' class is\\n// applied to our button after being clicked\\ncy.get(\\\"#main\\\").find(\\\"button\\\").click().should(\\\"have.class\\\", \\\"active\\\")\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n# Chaining\n\nBecause Cypress implements a fluent API, all commands are linked together.  Cypress has a small, but powerful, set of rules to know how to process the chain of commands.\n\n**There are 3 types of commands:**\n\n- [Parent Commands](#section-parent-commands)\n- [Child Commands](#section-child-commands)\n- [Dual Commands](#section-dual-commands)\n\n***\n\n## Parent Commands\n\nParent commands always *begin* a new chain of commands. Even if you've written a previous chain, parent commands will always start a new chain, and ignore previous chains. Parent commands should be written off the `cy` object:\n\n**Examples of parent commands:**\n\n - [`visit`](https://on.cypress.io/api/visit)\n - [`server`](https://on.cypress.io/api/server)\n - [`get`](https://on.cypress.io/api/get)\n - [`root`](https://on.cypress.io/api/root)\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy\\n  // visit is a parent command which is initially called off the cy object\\n  .visit(\\\"http://localhost:8000\\\")\\n\\n  // get ignores previously run commands and will\\n  //  query (by default) from the root document\\n  .get(\\\"#main\\\").find(\\\"button\\\").click().should(\\\"have.class\\\", \\\"active\\\")\\n\\n  // because get is a parent command, when we use it a 2nd time in a chain\\n  // the previous chain is ignored and we query from the root document\\n  .get(\\\"input\\\").type(\\\"foobarbaz\\\")\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## Child Commands\n\nChild commands are always chained off of a **parent** command, or another **child** command.\n\n**Examples of child commands:**\n\n- [`find`](https://on.cypress.io/api/find)\n- [`click`](https://on.cypress.io/api/click)\n- [`type`](https://on.cypress.io/api/type)\n- [`children`](https://on.cypress.io/api/children)\n- [`should`](https://on.cypress.io/api/should)\n\nEach of the above commands require an existing subject. It wouldn't make sense to [`click`](https://on.cypress.io/api/click) onto nothing, nor would it make sense to [`type`](https://on.cypress.io/api/type) or query for [`children`](https://on.cypress.io/api/children) of nothing.\n\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If child commands have specific rules which are not met, they will throw a very explicit error telling you why they can't be invoked at that time.\"\n}\n[/block]\n\nLooking at our previous example:\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy\\n  .visit(\\\"http://localhost:8000\\\")\\n\\n  .get(\\\"#main\\\")\\n    // we find the button within the existing DOM subject <div#main>\\n    // our subject now becomes the <button> element\\n    .find(\\\"button\\\")\\n\\n    // then we click the current subject, <button>\\n    .click()\\n\\n    // the click command does not change the subject\\n    // it returns the existing <button> subject\\n    // we can now assert that the <button> has the class 'active'\\n    .should(\\\"have.class\\\", \\\"active\\\")\\n\\n  .get(\\\"input\\\")\\n\\n    // we type into an existing DOM <input /> subject\\n    .type(\\\"foobarbaz\\\")\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## Dual Commands\n\nWhile parent commands always start a new chain of commands and child commands require being chained off a parent command, dual commands can behave as parent or child command. That is, they can **start** a new chain, or be chained off of an **existing** chain.\n\n**Examples of dual commands:**\n\n- [`contains`](https://on.cypress.io/api/contains)\n- [`wait`](https://on.cypress.io/api/wait)\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy\\n  // contains acts as a parent command, starting a chain of commands\\n  // contains will query from the root document (the default subject)\\n  .contains(\\\"Jane Lane\\\").click()\\n\\n  // contains can also act as a child command, using it's parent command's subject, <form>\\n  // contains only searches for content inside of the <form> element\\n  .get(\\\"form\\\").contains(\\\"Submit!\\\").click()\\n\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]","excerpt":"Traverse the dom and perform actions with commands","slug":"issuing-commands","type":"basic","title":"Issuing Commands"}

Issuing Commands

Traverse the dom and perform actions with commands

# Contents - :fa-angle-right: [Commands are Async](#section-commands-are-async) - :fa-angle-right: [Subjects](#section-subjects) - :fa-angle-right: [Chaining](#section-chaining) - [Parent Commands](#section-parent-commands) - [Child Commands](#section-child-commands) - [Dual Commands](#section-dual-commands) *** # Commands are Async When writing integration tests, you will need to traverse the DOM and perform user actions. In traditional server-side rendered views, it's unlikely you be deal with many application state changes. However, if you're writing an application using a modern JavaScript framework, you'll likely need to navigate through highly complex, dynamic states. > Cypress is designed to handle *both* traditional server-side rendered views & modern JavaScript framework applications. The architecture of Cypress focuses around asynchronicity. The DOM is a highly complex, mutable object; to handle the indeterminate state of the DOM, we've designed our commands to be asynchronous. **Because all commands are async, this offers many advantages.** 1. All commands can retry until a certain specified condition is met. 2. Commands can be replayed, inserted between others, or even conditionally run. 3. Cypress can look ahead (or look behind) at commands which have yet to run, and alter its behavior. Cypress is designed to also handle the disadvantages of async. One example is [aliasing](https://on.cypress.io/guides/using-aliases). This works around the need to assign values to variables. The [Command API](https://on.cypress.io/api) attempts to balance readability, terseness, flexibility, and capability all while being designed similar to familiar APIs. The [Command API](https://on.cypress.io/api) is also fluent - that is, you chain all commands together - similar to how jQuery's API is designed. *** # Subjects Commands work just like JavaScript Promises. That is, the resolved value of one command becomes the `subject` of the next command - just like a waterfall. [block:code] { "codes": [ { "code": "cy\n // when 'get' resolves, the subject\n // becomes the DOM element <div#main>\n .get(\"#main\")\n\n // after 'get' resolves, the find command\n // runs and is passed <div#main> as its subject.\n // <div#main> becomes the subject that we 'find' on.\n .find(\"button\")\n\n // after 'find' resolves, <button> becomes the new subject.\n // <button> is what the click operates on.\n // this is functionally equivalent to\n // writing $(\"#main\").find(\"button\").click() in jQuery.\n .click()\n", "language": "javascript" } ] } [/block] The difference between the Cypress API and jQuery's API is that *all* commands are async. **No command returns an actual assignable value.** That is because every command is queued, ran, and retried until it resolves. Some commands may not resolve until several seconds after they are run. For instance you **cannot** do this: [block:code] { "codes": [ { "code": "// THIS WILL NOT WORK!\nbutton = cy.get(\"#main\").find(\"button\")\n", "language": "javascript" } ] } [/block] Just like Promises, the value that async commands return can only be yielded in a callback function. If you want to retrieve the resolved value (the subject) of a command, use a [`then`](https://on.cypress.io/api/then) command, the same way you would with Promises. [block:code] { "codes": [ { "code": "cy.get(\"#main\").find(\"button\").then(function($button){\n // when the 'find' command resolves, we can yield its\n // resolved value (the new subject) in a callback function.\n // now we can work with this value directly.\n $button.trigger(\"click\")\n})\n", "language": "javascript" } ] } [/block] When chaining together multiple commands you rarely should need to yield the subject via a [`cy.then`](https://on.cypress.io/api/then) command. Cypress favors readability and terseness, and even [assertions](https://on.cypress.io/guides/making-assertions) can be implicitly run without having to use a [`cy.then`](https://on.cypress.io/api/then) command. [block:code] { "codes": [ { "code": "// we're testing that an 'active' class is\n// applied to our button after being clicked\ncy.get(\"#main\").find(\"button\").click().should(\"have.class\", \"active\")\n", "language": "javascript" } ] } [/block] *** # Chaining Because Cypress implements a fluent API, all commands are linked together. Cypress has a small, but powerful, set of rules to know how to process the chain of commands. **There are 3 types of commands:** - [Parent Commands](#section-parent-commands) - [Child Commands](#section-child-commands) - [Dual Commands](#section-dual-commands) *** ## Parent Commands Parent commands always *begin* a new chain of commands. Even if you've written a previous chain, parent commands will always start a new chain, and ignore previous chains. Parent commands should be written off the `cy` object: **Examples of parent commands:** - [`visit`](https://on.cypress.io/api/visit) - [`server`](https://on.cypress.io/api/server) - [`get`](https://on.cypress.io/api/get) - [`root`](https://on.cypress.io/api/root) [block:code] { "codes": [ { "code": "cy\n // visit is a parent command which is initially called off the cy object\n .visit(\"http://localhost:8000\")\n\n // get ignores previously run commands and will\n // query (by default) from the root document\n .get(\"#main\").find(\"button\").click().should(\"have.class\", \"active\")\n\n // because get is a parent command, when we use it a 2nd time in a chain\n // the previous chain is ignored and we query from the root document\n .get(\"input\").type(\"foobarbaz\")\n", "language": "javascript" } ] } [/block] *** ## Child Commands Child commands are always chained off of a **parent** command, or another **child** command. **Examples of child commands:** - [`find`](https://on.cypress.io/api/find) - [`click`](https://on.cypress.io/api/click) - [`type`](https://on.cypress.io/api/type) - [`children`](https://on.cypress.io/api/children) - [`should`](https://on.cypress.io/api/should) Each of the above commands require an existing subject. It wouldn't make sense to [`click`](https://on.cypress.io/api/click) onto nothing, nor would it make sense to [`type`](https://on.cypress.io/api/type) or query for [`children`](https://on.cypress.io/api/children) of nothing. [block:callout] { "type": "info", "body": "If child commands have specific rules which are not met, they will throw a very explicit error telling you why they can't be invoked at that time." } [/block] Looking at our previous example: [block:code] { "codes": [ { "code": "cy\n .visit(\"http://localhost:8000\")\n\n .get(\"#main\")\n // we find the button within the existing DOM subject <div#main>\n // our subject now becomes the <button> element\n .find(\"button\")\n\n // then we click the current subject, <button>\n .click()\n\n // the click command does not change the subject\n // it returns the existing <button> subject\n // we can now assert that the <button> has the class 'active'\n .should(\"have.class\", \"active\")\n\n .get(\"input\")\n\n // we type into an existing DOM <input /> subject\n .type(\"foobarbaz\")\n", "language": "javascript" } ] } [/block] *** ## Dual Commands While parent commands always start a new chain of commands and child commands require being chained off a parent command, dual commands can behave as parent or child command. That is, they can **start** a new chain, or be chained off of an **existing** chain. **Examples of dual commands:** - [`contains`](https://on.cypress.io/api/contains) - [`wait`](https://on.cypress.io/api/wait) [block:code] { "codes": [ { "code": "cy\n // contains acts as a parent command, starting a chain of commands\n // contains will query from the root document (the default subject)\n .contains(\"Jane Lane\").click()\n\n // contains can also act as a child command, using it's parent command's subject, <form>\n // contains only searches for content inside of the <form> element\n .get(\"form\").contains(\"Submit!\").click()\n\n", "language": "javascript" } ] } [/block]