deprecate existing custom command interface

[brian-mann]

We are going to move the custom command interface to be on Cypress.Commands instead of the Cypress object.

Cypress.addParentCommand -> Cypress.Commands.add
Cypress.addChildCommand -> Cypress.Commands.add
Cypress.addDualCommand -> Cypress.Commands.add

This will be a breaking change and we'll print a good error message.

Changes to the interface

Instead of having to decide "up front" and learn about the difference between parent, child, and dual commands, you can now simply describe their "behavior" surrounding subjects to get what you want.

Custom commands will now accept an optional 2nd options argument which will describe how to handle existing subjects.

{prevSubject: false} // the default (parent command) which ignores existing subjects
{prevSubject: true} // enforces an existing subject (child command)
{prevSubject: "dom"} // enforces an existing DOM subject (child command operating on DOM)
{prevSubject: "optional"} // may or may not have an existing subject (dual command)

// example parent command
Cypress.Commands.add("login", function(username, password){
  // this works the same
})

// example child command
Cypress.Commands.add("rightclick", {prevSubject: "dom"}, function(subject, arg1, arg2){
  // enforces that the previous subject is DOM and the subject is yielded here
  // blows up and provides a great error when improperly chained
})

// example dual command
Cypress.Commands.add("foo", {prevSubject: "optional"}, function(subject, arg1, arg2){
  // subject may or may not be undefined giving you the option to change the behavior
  // the most common dual command is cy.contains() which operates differently whether
  // there is an existing subject or not
})

[Andrew1431]

Hey! I spent a while tracing down a bug this morning, and the error was very unclear to me. I was simply getting an error: Can not read property 'apply' of undefined when the custom method would be called.

Turns out my issue was that deleteRoom was not being exported, and as a result I was passing undefined to the addDualCommand. Could you consider adding a validator in that method?

import { deleteRoom } from './deleteRoom';

Cypress.addDualCommand('deleteRoom', deleteRoom);

Just a recommendation! :)

Thanks!

[jennifer-shehane]

The code for this is done, but this has yet to be released. We'll update this issue and reference the changelog when it's released.

[brian-mann]

Fixed in 0.20.0