From 390a0d0393a229ee8be9d5ea4200a9f6844beb29 Mon Sep 17 00:00:00 2001 From: BlueWinds Date: Tue, 7 Feb 2023 13:44:29 -0800 Subject: [PATCH 1/7] Documentation for Cypress.ensure --- docs/api/cypress-api/ensure.mdx | 81 +++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/api/cypress-api/ensure.mdx diff --git a/docs/api/cypress-api/ensure.mdx b/docs/api/cypress-api/ensure.mdx new file mode 100644 index 0000000000..304d499f33 --- /dev/null +++ b/docs/api/cypress-api/ensure.mdx @@ -0,0 +1,81 @@ +--- +title: Cypress.ensure +--- + +`Cypress.ensure.method()` is a collection of helper methods for verifying +conditions while executing Cypress commands. They are mostly useful when writing +[custom queries](/api/cypress-api/custom-queries) or +[commands](/api/cypress-api/custom-commands). + +Most functions on `Cypress.ensure` accept `subject` argument, and assert +something about it, throwing an error if it doesn't match. They have no return +value; their only purpose is to ensure the state of the application and throw an +error if it doesn't match. + +## Syntax + +```javascript +// Command chain +Cypress.ensure.isChildCommand(command, args, cy)​ + +// Type of argument +Cypress.ensure.isType(subject, type, name, cy)​ +Cypress.ensure.isElement(subject, name, cy)​ +Cypress.ensure.isWindow(subject, name, cy) +Cypress.ensure.isDocument(subject, name, cy)​ + +// State of DOM element +Cypress.ensure.isAttached(subject, name, cy)​ +Cypress.ensure.isNotDisabled(subject, name)​ +Cypress.ensure.isNotHiddenByAncestors(subject, name)​ +Cypress.ensure.isNotReadonly(subject, name)​ +Cypress.ensure.isScrollable($el, name)​ +Cypress.ensure.isStrictlyVisible(subject, name)​ +Cypress.ensure.isVisible(subject, name)​ +``` + +:::caution + +Many of these functions accept an optional `onFail` argument. This is a legacy +feature used to customize the thrown error, and may be removed in a future +release; we recommend against relying on it. If you need more control over the +error thrown, write your own `ensure` function instead. + +::: + +### Usage + +** Correct Usage** + +```javascript +Cypress.Commands.addQuery('getChildById', function (id) { + return (subject) => { + // Verify that the subject is an element, document, or window object + Cypress.ensure.isType(subject, ['element', 'document', 'window'], 'getChildById', cy) + + return $$(`#${id}`, subject) + } +}) + +Cypress.Commands.addQuery('verifyElementActionable', function (id) { + // Throws an early error if this query is chained directly off `cy`, eg. + // `cy.verifyElementActionable('foo')` would throw an error + Cypress.ensure.isChildCommand(command, args, cy)​ + + return (subject) => { + // Verify that the subject fulfills a variety of conditions + Cypress.ensure.isElement(subject, 'verifyElementActionable', cy) + Cypress.ensure.isVisible(subject, 'verifyElementActionable', cy) + Cypress.ensure.isNotDisabled(subject, 'verifyElementActionable', cy) + Cypress.ensure.isNotReadonly(subject, 'verifyElementActionable', cy) + + return subject + } +}) +``` + +## See also + +- Writing [custom queries](/api/cypress-api/custom-queries) contains more + information about writing custom queries, which is the main use-case for the + `ensure` functions. From 6b67ce724b38ab66b65fadde3d4639ab9430d226 Mon Sep 17 00:00:00 2001 From: Blue F Date: Mon, 13 Feb 2023 08:57:16 -0800 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: Zach Bloomquist --- docs/api/cypress-api/ensure.mdx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/api/cypress-api/ensure.mdx b/docs/api/cypress-api/ensure.mdx index 304d499f33..652abcd3d8 100644 --- a/docs/api/cypress-api/ensure.mdx +++ b/docs/api/cypress-api/ensure.mdx @@ -2,15 +2,11 @@ title: Cypress.ensure --- -`Cypress.ensure.method()` is a collection of helper methods for verifying -conditions while executing Cypress commands. They are mostly useful when writing +`Cypress.ensure` is a collection of helper methods for making assertions. They are mostly useful when writing [custom queries](/api/cypress-api/custom-queries) or [commands](/api/cypress-api/custom-commands). -Most functions on `Cypress.ensure` accept `subject` argument, and assert -something about it, throwing an error if it doesn't match. They have no return -value; their only purpose is to ensure the state of the application and throw an -error if it doesn't match. +Most functions on `Cypress.ensure` accept a `subject` argument, check an assertion, and throw an error if the assertion fails. These functions have no return value. ## Syntax @@ -76,6 +72,6 @@ Cypress.Commands.addQuery('verifyElementActionable', function (id) { ## See also -- Writing [custom queries](/api/cypress-api/custom-queries) contains more +- ["Custom Queries"](/api/cypress-api/custom-queries) contains more information about writing custom queries, which is the main use-case for the `ensure` functions. From 259aa0650051c40b3e6825d6aa8c884ce96f122b Mon Sep 17 00:00:00 2001 From: Blue F Date: Mon, 13 Feb 2023 08:57:37 -0800 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Emily Rohrbough --- docs/api/cypress-api/ensure.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/cypress-api/ensure.mdx b/docs/api/cypress-api/ensure.mdx index 652abcd3d8..ca6617594f 100644 --- a/docs/api/cypress-api/ensure.mdx +++ b/docs/api/cypress-api/ensure.mdx @@ -4,7 +4,7 @@ title: Cypress.ensure `Cypress.ensure` is a collection of helper methods for making assertions. They are mostly useful when writing [custom queries](/api/cypress-api/custom-queries) or -[commands](/api/cypress-api/custom-commands). +[custom commands](/api/cypress-api/custom-commands). Most functions on `Cypress.ensure` accept a `subject` argument, check an assertion, and throw an error if the assertion fails. These functions have no return value. From 382a578b88b123725d920fbac5c918397fd5d592 Mon Sep 17 00:00:00 2001 From: BlueWinds Date: Mon, 13 Feb 2023 09:23:35 -0800 Subject: [PATCH 4/7] Review updates --- docs/api/cypress-api/ensure.mdx | 36 +++++++++++++++++---------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/api/cypress-api/ensure.mdx b/docs/api/cypress-api/ensure.mdx index ca6617594f..411be68f5d 100644 --- a/docs/api/cypress-api/ensure.mdx +++ b/docs/api/cypress-api/ensure.mdx @@ -15,19 +15,19 @@ Most functions on `Cypress.ensure` accept a `subject` argument, check an asserti Cypress.ensure.isChildCommand(command, args, cy)​ // Type of argument -Cypress.ensure.isType(subject, type, name, cy)​ -Cypress.ensure.isElement(subject, name, cy)​ -Cypress.ensure.isWindow(subject, name, cy) -Cypress.ensure.isDocument(subject, name, cy)​ +Cypress.ensure.isType(subject, type, commandName, cy)​ +Cypress.ensure.isElement(subject, commandName, cy)​ +Cypress.ensure.isWindow(subject, commandName, cy) +Cypress.ensure.isDocument(subject, commandName, cy)​ // State of DOM element -Cypress.ensure.isAttached(subject, name, cy)​ -Cypress.ensure.isNotDisabled(subject, name)​ -Cypress.ensure.isNotHiddenByAncestors(subject, name)​ -Cypress.ensure.isNotReadonly(subject, name)​ -Cypress.ensure.isScrollable($el, name)​ -Cypress.ensure.isStrictlyVisible(subject, name)​ -Cypress.ensure.isVisible(subject, name)​ +Cypress.ensure.isAttached(subject, commandName, cy)​ +Cypress.ensure.isNotDisabled(subject, commandName)​ +Cypress.ensure.isNotHiddenByAncestors(subject, commandName)​ +Cypress.ensure.isNotReadonly(subject, commandName)​ +Cypress.ensure.isScrollable(subject, commandName)​ +Cypress.ensure.isStrictlyVisible(subject, commandName)​ +Cypress.ensure.isVisible(subject, commandName)​ ``` :::caution @@ -53,17 +53,19 @@ Cypress.Commands.addQuery('getChildById', function (id) { } }) -Cypress.Commands.addQuery('verifyElementActionable', function (id) { +const queryName = 'verifyElementActionable' + +Cypress.Commands.addQuery(queryName, function (...args) { // Throws an early error if this query is chained directly off `cy`, eg. // `cy.verifyElementActionable('foo')` would throw an error - Cypress.ensure.isChildCommand(command, args, cy)​ + Cypress.ensure.isChildCommand(this, args, cy)​ return (subject) => { // Verify that the subject fulfills a variety of conditions - Cypress.ensure.isElement(subject, 'verifyElementActionable', cy) - Cypress.ensure.isVisible(subject, 'verifyElementActionable', cy) - Cypress.ensure.isNotDisabled(subject, 'verifyElementActionable', cy) - Cypress.ensure.isNotReadonly(subject, 'verifyElementActionable', cy) + Cypress.ensure.isElement(subject, queryName, cy) + Cypress.ensure.isVisible(subject, queryName, cy) + Cypress.ensure.isNotDisabled(subject, queryName, cy) + Cypress.ensure.isNotReadonly(subject, queryName, cy) return subject } From 6c3f3d3466400141d3db71bcfab3231a94507296 Mon Sep 17 00:00:00 2001 From: BlueWinds Date: Mon, 13 Feb 2023 09:24:06 -0800 Subject: [PATCH 5/7] Prettier run --- docs/api/cypress-api/ensure.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/api/cypress-api/ensure.mdx b/docs/api/cypress-api/ensure.mdx index 411be68f5d..0889299934 100644 --- a/docs/api/cypress-api/ensure.mdx +++ b/docs/api/cypress-api/ensure.mdx @@ -2,11 +2,13 @@ title: Cypress.ensure --- -`Cypress.ensure` is a collection of helper methods for making assertions. They are mostly useful when writing -[custom queries](/api/cypress-api/custom-queries) or -[custom commands](/api/cypress-api/custom-commands). +`Cypress.ensure` is a collection of helper methods for making assertions. They +are mostly useful when writing [custom queries](/api/cypress-api/custom-queries) +or [custom commands](/api/cypress-api/custom-commands). -Most functions on `Cypress.ensure` accept a `subject` argument, check an assertion, and throw an error if the assertion fails. These functions have no return value. +Most functions on `Cypress.ensure` accept a `subject` argument, check an +assertion, and throw an error if the assertion fails. These functions have no +return value. ## Syntax @@ -74,6 +76,6 @@ Cypress.Commands.addQuery(queryName, function (...args) { ## See also -- ["Custom Queries"](/api/cypress-api/custom-queries) contains more - information about writing custom queries, which is the main use-case for the - `ensure` functions. +- ["Custom Queries"](/api/cypress-api/custom-queries) contains more information + about writing custom queries, which is the main use-case for the `ensure` + functions. From 519945fedb8789698bf0bbc5ee387fca0bc5a066 Mon Sep 17 00:00:00 2001 From: BlueWinds Date: Wed, 15 Feb 2023 11:54:45 -0800 Subject: [PATCH 6/7] Remove docs around ensure.isChildCommand since we intend to remove it. --- docs/api/cypress-api/ensure.mdx | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/api/cypress-api/ensure.mdx b/docs/api/cypress-api/ensure.mdx index 0889299934..89a1d36974 100644 --- a/docs/api/cypress-api/ensure.mdx +++ b/docs/api/cypress-api/ensure.mdx @@ -13,9 +13,6 @@ return value. ## Syntax ```javascript -// Command chain -Cypress.ensure.isChildCommand(command, args, cy)​ - // Type of argument Cypress.ensure.isType(subject, type, commandName, cy)​ Cypress.ensure.isElement(subject, commandName, cy)​ @@ -58,10 +55,6 @@ Cypress.Commands.addQuery('getChildById', function (id) { const queryName = 'verifyElementActionable' Cypress.Commands.addQuery(queryName, function (...args) { - // Throws an early error if this query is chained directly off `cy`, eg. - // `cy.verifyElementActionable('foo')` would throw an error - Cypress.ensure.isChildCommand(this, args, cy)​ - return (subject) => { // Verify that the subject fulfills a variety of conditions Cypress.ensure.isElement(subject, queryName, cy) From e8fb04415fd2c6de442b2c2ecd91b21ed5860d2e Mon Sep 17 00:00:00 2001 From: BlueWinds Date: Wed, 15 Feb 2023 11:55:54 -0800 Subject: [PATCH 7/7] Prettier run --- docs/api/cypress-api/ensure.mdx | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/api/cypress-api/ensure.mdx b/docs/api/cypress-api/ensure.mdx index 89a1d36974..59c105059d 100644 --- a/docs/api/cypress-api/ensure.mdx +++ b/docs/api/cypress-api/ensure.mdx @@ -6,9 +6,10 @@ title: Cypress.ensure are mostly useful when writing [custom queries](/api/cypress-api/custom-queries) or [custom commands](/api/cypress-api/custom-commands). -Most functions on `Cypress.ensure` accept a `subject` argument, check an -assertion, and throw an error if the assertion fails. These functions have no -return value. +Most functions on `Cypress.ensure` accept a +[`subject`](/guides/core-concepts/introduction-to-cypress#Subject-Management) +argument, check an assertion, and throw an error if the assertion fails. These +functions have no return value. ## Syntax @@ -46,7 +47,12 @@ error thrown, write your own `ensure` function instead. Cypress.Commands.addQuery('getChildById', function (id) { return (subject) => { // Verify that the subject is an element, document, or window object - Cypress.ensure.isType(subject, ['element', 'document', 'window'], 'getChildById', cy) + Cypress.ensure.isType( + subject, + ['element', 'document', 'window'], + 'getChildById', + cy + ) return $$(`#${id}`, subject) }