Skip to content

Commit

Permalink
Revert "Revert "clarify effect of should command on implicit DOM asse…
Browse files Browse the repository at this point in the history
…rtions (#1289)""

This reverts commit 296da56.
  • Loading branch information
kuceb committed Jan 31, 2019
1 parent d91d758 commit 6491fa4
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 2 deletions.
4 changes: 4 additions & 0 deletions source/api/commands/should.md
Original file line number Diff line number Diff line change
Expand Up @@ -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?
Expand Down
24 changes: 22 additions & 2 deletions source/guides/core-concepts/introduction-to-cypress.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit 6491fa4

Please sign in to comment.