Refactor custom command rules, remove undocumented `cy.chain`

Currently there is an undocumented cy.chain command that is necessary to get chaining to work correctly.

The reasoning for this is fairly complex and has to do with internal rules in Cypress for determining parent, child, and dual commands and is a side effect of a peculiar implementation detail.

We need to simplify this entire API, the rules surrounding it, and make things “just work” the way it appears to work.

To do:

• simplify the rules around nulling out subjects
• move the logic surrounding throwing on an improperly called child command to chainer length logic and not cy queue length logic or by existing subject value
• dont make a null value forcibly blow up child commands
• always force child commands to have the subject yielded to them in their callback (even if its null)
• update dual command logic to only have the subject yielded if they are not the first called method on a chainer (else have this subject automatically nulled out)
• update the docs to provide much clearer examples and reasoning around this all
• warn about overusing custom commands aka Page Object Pattern
• warn when using cy.chain

Related to #463, #436, #435, #198

These examples should “just work”

Cypress.Commands.addParent("a", function(){
  cy.wrap("foo")
})

Cypress.Commands.addChild("b", function(str){
  return str + "bar"
})

Cypress.Commands.addDual("c", function(str){
  expect(str).to.eq("foobar")

  return str
})

Cypress.Commands.addDual("d", function(str){
  return str ? "string is truthy" : "string is falsy"
})

it("just works", function(){
  cy
    .a().should("eq", "foo")
    .b().should("eq", "foobar")
    .c().should("eq", "foobar")
    .d().should("eq", "string is truthy")
  
  cy.d().should("eq", "string is falsy")
})

[Athaphian]

I’m not sure I am doing this right… I use Cypress 3.1.0 but I cannot get it to work with either wrap or chain (which is logical since chain is deprecated and removed). Im trying to select a piece of subdom (from the shadow dom in this case):

Cypress.Commands.add('shadowdom', {
  prevSubject: true
}, (subject, query) => {
  const result = shadowDomSelector(subject.get(0), query);
  return result;
});

But I always get the following error:

(In this case chaining it to .contains) CypressError: cy.contains() failed because it requires the subject be a global ‘window’ object.

I’ve been reading the documentation for about half a day, but cannot seem to find a proper solution.

[brian-mann]

Fixed in 0.20.0