cypress-documentation
cypress-documentation copied to clipboard
cypress-io
"DOM based commands" not clearly defined / confusing
Subject
guides
Description
In a few parts of the documentation, the term "DOM based commands" is used (like here and here), but I couldn't find anywhere what this term means in the context of Cypress. I think it would be a great idea to have a separate page to which the usage of this term is linked to, which exactly describes what is considered to be a "DOM based command" and what isn't.
To provide you with the perspective of someone that reads the documentation for the first time, I will elaborate on which parts I find confusing and why:
For example, in "Default Assertions" it says:
Others, such as DOM based commands will automatically retry and wait for their corresponding elements to exist before failing. From the context I can see that
cy.request()is not a "DOM based command" (which makes sense) but it still doesn't tell me which ones are. Therefore I don't know which commands will retry and which ones won't, which is quite important to know in my opinion.
Also in "Default Assertions" it says:
All DOM based commands automatically wait for their elements to exist in the DOM. You never need to write .should('exist') after a DOM based command.
From reading this, specifically "after a DOM based command" makes me believe methods like cy.get(...) would be a DOM based command, so this would imply something like cy.get(...).should('exist') would be redundant, as cy.get(...) already checks for existence. But if I look through the cypress codebase, I can find plenty of tests and examples where something like cy.get(...).should('exist') is used, so this makes me wonder whether those are leftovers from a previous version where this was necessary or if my assumption that cy.get(...) counts as a DOM based command is wrong.
Looking further into the documentation trying to clear the confusion up, in "Interacting with Elements" I found the following:
Some commands in Cypress are for interacting with the DOM such as: .click(), .dblclick()...
Since it says "interacting with the DOM" this could imply methods like .click() would count as "DOM based commands", but then this would conflict with the explanation in "Default Assertions" where it states "after a DOM based command", as something like .click().should('exist') would not make sense.
Also on this page it doesn't mention cy.get(...) which confuses me even more since I don't know if it's not mentioned as it says "such as:", which means it may have been omitted, but given cy.get(...) is such an important command, it would need to be included, so is it maybe not a DOM based command?
The last thing I found that could have something to do with "DOM based commands" was the Cypress.dom methods documentation which further added to the confusion, making me wonder if those are the mentioned DOM based commands?
In general I wished the parts in the documentation where things like "for instance:" or "such as:" are mentioned were more exhaustive / complete. For example in "Default Assertions":
Certain commands may have a specific requirement that causes them to immediately fail without retrying: such as cy.request().
By reading this as someone new to Cypress, the only information I gain is that cy.request immediately fails without retrying and that there may be more which I have no idea about how to find out which those are. This is quite scary, as I have to worry now with every command I use that it may fail without retrying and what's worse that this may not even get noticed by me if it coincidentally works the first time and fails at some point in the future as a seemingly "flaky" test.
In cases like this it should either explain how to know / find out which ones are affected or even better include all affected ones or link to a page in the documentation / code where a full list can be seen.
Another example is "Interacting with Elements", where I'm wondering as it mentions "such as:" which others are available.
I'm fully aware that it is more difficult to maintain documentation that is exhaustive and while this may be enough for developers experienced with Cypress, it makes it very difficult for developers unexperienced with Cypress to understand how to use Cypress correctly and effectively.
