Refactor custom command rules, remove undocumented cy.chain

[brian-mann]

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")
})

[jennifer-shehane]

Warning displays on use of cy.chain() in v.0.20.0:

Error: CypressError: cy.chain() was an undocumented command that has now been removed.
You can safely remove this from your code and it should work without it.

[dziamid]

Hopefully this can be resolved soon and we can switch to the new command API. In the meantime, can someone spot the problem with the code below?

So this works:

cy.get('body')
  .find('.Select-control input')
  .first()
  .type('Some text')

This sadly does not work:

Cypress.addChildCommand('findReactSelect', (subject) => {
  cy
    .chain()
    .wrap(subject)
    .find('.Select-control input')
    .first()
});

cy.get('body')
  .findReactSelect()
  .type('Some text') //CypressError: Subject is null. You cannot call cy.type() without a subject.

[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.

[dziamid]

It is so weird that i cannot fork and adopt features early. I wonder what is holding you back to have the tool open sourced already.

[brian-mann]

Fixed in 0.20.0

[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.