Cypress.Commands.add(name, callbackFn) Cypress.Commands.add(name, options, callbackFn) Cypress.Commands.overwrite(name, callbackFn)
The name of the command you’re either adding or overwriting.
Pass a function that receives the arguments passed to the command.
Pass in an options object to define the implicit behavior of the custom command.
optionsis only supported for use in
Cypress.Commands.add()and not supported for use in
||how to handle the previously yielded subject.|
prevSubject accepts the following values:
false: ignore any previous subjects: (parent command)
true: receives the previous subject: (child command)
optional: may start a chain, or use an existing chain: (dual command)
In additional to controlling the command’s implicit behavior you can also add declarative subject validations such as:
element: requires the previous subject be a DOM element
document: requires the previous subject be the document
window: requires the previous subject be the window
Internally our built in commands make use of every single one of these combinations above.
Custom commands work well when you’re needing to describe behavior that’s desirable across all of your tests. Examples would be a
cy.login() or extending your application’s behavior like
cy.get(‘.dropdown‘).dropdown(‘Apples‘). These are specific to your application and can be used everywhere.
If you’re working on a
search_spec.js file and want to compose several repeatable actions together, you should first ask yourself:
Every custom command you write is generally an abstraction over a series of internal commands. That means you and your team members exert much more mental effort to understand what your custom command does.
There’s no reason to add this level of complexity when you’re only wrapping a couple commands.
This first custom command is wrapping
cy.get(selector).click(). Going down this route would lead to creating dozens or even hundreds of custom commands to cover every possible combination of element interactions. It’s completely unnecessary.
.shouldBeVisible() custom command isn’t worth the trouble or abstraction when you can already use:
Testing in Cypress is all about readability and simplicity. You don’t have to do that much actual programming to get a lot done. You also don’t need to worry about keeping your code as DRY as possible. Test code serves a different purpose than app code. Understandability and debuggability should be prioritized above all else.
Try not to overcomplicate things and create too many abstractions. When in doubt, use a regular function for individual spec files.
Make your custom commands composable and as unopinionated as possible. Cramming too much into them makes them inflexible and requires more and more options passing to control their behavior.
Try to add either zero or as few assertions as possible in your custom command. Those tend to shape your command into a much more rigid structure. Sometimes this is unavoidable, but a best practice is to let the calling code choose when and how to use assertions.
You can describe the method signature for your custom command, allowing IntelliSense to show helpful documentation. See the
cypress-example-todomvc repository for a working example.