From 296da56b3cb1355abfd317c7b9f5a59ac23b9986 Mon Sep 17 00:00:00 2001 From: Ben Kucera <14625260+Bkucera@users.noreply.github.com> Date: Wed, 30 Jan 2019 14:34:19 -0500 Subject: [PATCH 1/3] Revert "clarify effect of should command on implicit DOM assertions (#1289)" This reverts commit 7d2f44d794d5500f58e57168f8dd79770cce254a. --- source/api/commands/should.md | 4 ---- .../core-concepts/introduction-to-cypress.md | 24 ++----------------- 2 files changed, 2 insertions(+), 26 deletions(-) diff --git a/source/api/commands/should.md b/source/api/commands/should.md index a2bba34b79..2c2af82dc5 100644 --- a/source/api/commands/should.md +++ b/source/api/commands/should.md @@ -340,10 +340,6 @@ cy.get('button').click() # Notes -## Effect on default DOM assertions - -When you chain `.should()` on a DOM-based command, the default `.should('exist')` assertion is skipped. This may result in an unexpected behavior such as negative assertions passing even when the element doesn't exist in the DOM. See {% url 'Default Assertions' introduction-to-cypress#Default-Assertions %} for more. - ## Subjects ### How do I know which assertions change the subject and which keep it the same? diff --git a/source/guides/core-concepts/introduction-to-cypress.md b/source/guides/core-concepts/introduction-to-cypress.md index af27adfb77..8c878e7a7d 100644 --- a/source/guides/core-concepts/introduction-to-cypress.md +++ b/source/guides/core-concepts/introduction-to-cypress.md @@ -674,30 +674,10 @@ Even more - action commands will automatically wait for their element to reach a {% note success Core Concept %} All DOM based commands automatically wait for their elements to exist in the DOM. -You don't need to write {% url "`.should('exist')`" should %} after a DOM based command, unless you chain extra `.should()` assertions. +You **never** need to write {% url "`.should('exist')`" should %} after a DOM based command. {% endnote %} -{% note danger "Negative DOM assertions" %} -If you chain any `.should()` command, the default `.should('exist')` is not asserted. This does not matter for most *positive* assertions, such as `.should('have.class')`, because those imply existence in the first place, but if you chain *negative* assertions ,such as `.should('not.have.class')`, they will pass even if the DOM element doesn't exist: - -``` -cy.get('.does-not-exist').should('not.be.visible') // passes -cy.get('.does-not-exist').should('not.have.descendants') // passes -``` - -This also applies to custom assertions such as when passing a callback: - -``` -// passes, provided the callback itself passes -cy.get('.does-not-exist').should(($element) => { - expect($element.find('input')).to.not.exist -}) -``` - -There's an {% url 'open discussion' https://github.com/cypress-io/cypress/issues/205 %} about this behavior. -{% endnote %} - -These rules are pretty intuitive, and most commands give you the flexibility to override or bypass the default ways they can fail, typically by passing a `{force: true}` option. +These rules are pretty intuitive, and most commands give you flexibility to override or bypass the default ways they can fail, typically by passing a `{force: true}` option. ### Example #1: Existence and Actionability From d91d758b124243297ba7a15c179544e4c661b081 Mon Sep 17 00:00:00 2001 From: Ben Kucera <14625260+Bkucera@users.noreply.github.com> Date: Wed, 30 Jan 2019 14:52:31 -0500 Subject: [PATCH 2/3] add docs for focus assertion --- source/api/commands/should.md | 9 +++++++++ source/guides/references/assertions.md | 1 + 2 files changed, 10 insertions(+) diff --git a/source/api/commands/should.md b/source/api/commands/should.md index 2c2af82dc5..424f1d987b 100644 --- a/source/api/commands/should.md +++ b/source/api/commands/should.md @@ -125,6 +125,15 @@ cy.get('button').should('have.id', 'new-user').then(($button) => { cy.get('#header a').should('have.attr', 'href', '/users') ``` +## Focus + +### Assert an input is focused after button click + +```javascript +cy.get('#btn-focuses-input').click() +cy.get('#input-receives-focus').should('have.focus') // equivalent to should('be.focused') +``` + ## Function Passing a function to `.should()` enables you to make multiple assertions on the yielded subject. This also gives you the opportunity to *massage* what you'd like to assert on. diff --git a/source/guides/references/assertions.md b/source/guides/references/assertions.md index 5894f5d316..3e9710c4fc 100644 --- a/source/guides/references/assertions.md +++ b/source/guides/references/assertions.md @@ -139,6 +139,7 @@ You will commonly use these chainers after using DOM commands like: {% url `cy.g | hidden | `expect($el).to.be.hidden` | | selected | `expect($option).not.to.be.selected` | | checked | `expect($input).not.to.be.checked` | +| focus[ed] | `expect($input).not.to.be.focused`
`expect($input).to.have.focus` | | enabled | `expect($input).to.be.enabled` | | disabled | `expect($input).to.be.disabled` | | empty | `expect($el).not.to.be.empty` | From 6491fa4583d811235dfc8eec6e409beb16861f43 Mon Sep 17 00:00:00 2001 From: Ben Kucera <14625260+Bkucera@users.noreply.github.com> Date: Thu, 31 Jan 2019 14:39:33 -0500 Subject: [PATCH 3/3] Revert "Revert "clarify effect of should command on implicit DOM assertions (#1289)"" This reverts commit 296da56b3cb1355abfd317c7b9f5a59ac23b9986. --- source/api/commands/should.md | 4 ++++ .../core-concepts/introduction-to-cypress.md | 24 +++++++++++++++++-- 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/source/api/commands/should.md b/source/api/commands/should.md index 424f1d987b..d639937a74 100644 --- a/source/api/commands/should.md +++ b/source/api/commands/should.md @@ -349,6 +349,10 @@ cy.get('button').click() # Notes +## Effect on default DOM assertions + +When you chain `.should()` on a DOM-based command, the default `.should('exist')` assertion is skipped. This may result in an unexpected behavior such as negative assertions passing even when the element doesn't exist in the DOM. See {% url 'Default Assertions' introduction-to-cypress#Default-Assertions %} for more. + ## Subjects ### How do I know which assertions change the subject and which keep it the same? diff --git a/source/guides/core-concepts/introduction-to-cypress.md b/source/guides/core-concepts/introduction-to-cypress.md index 8c878e7a7d..af27adfb77 100644 --- a/source/guides/core-concepts/introduction-to-cypress.md +++ b/source/guides/core-concepts/introduction-to-cypress.md @@ -674,10 +674,30 @@ Even more - action commands will automatically wait for their element to reach a {% note success Core Concept %} All DOM based commands automatically wait for their elements to exist in the DOM. -You **never** need to write {% url "`.should('exist')`" should %} after a DOM based command. +You don't need to write {% url "`.should('exist')`" should %} after a DOM based command, unless you chain extra `.should()` assertions. {% endnote %} -These rules are pretty intuitive, and most commands give you flexibility to override or bypass the default ways they can fail, typically by passing a `{force: true}` option. +{% note danger "Negative DOM assertions" %} +If you chain any `.should()` command, the default `.should('exist')` is not asserted. This does not matter for most *positive* assertions, such as `.should('have.class')`, because those imply existence in the first place, but if you chain *negative* assertions ,such as `.should('not.have.class')`, they will pass even if the DOM element doesn't exist: + +``` +cy.get('.does-not-exist').should('not.be.visible') // passes +cy.get('.does-not-exist').should('not.have.descendants') // passes +``` + +This also applies to custom assertions such as when passing a callback: + +``` +// passes, provided the callback itself passes +cy.get('.does-not-exist').should(($element) => { + expect($element.find('input')).to.not.exist +}) +``` + +There's an {% url 'open discussion' https://github.com/cypress-io/cypress/issues/205 %} about this behavior. +{% endnote %} + +These rules are pretty intuitive, and most commands give you the flexibility to override or bypass the default ways they can fail, typically by passing a `{force: true}` option. ### Example #1: Existence and Actionability