Throw when a value other than `cy` is returned from a test or command function

[brian-mann]

During an e2e or integration test, we should throw a specific error message when:

1. a value is returned to a callback function
2. in either a mocha it test or in a custom command
3. and a cy command was invoked.

We're going to opt for a stricter API up front contract instead of being magical behind the scenes and forcing return values unbeknownst to the developer.

The following situations should throw:

Cypress.Commands.addParent("foo", function(){
  cy.get("body").should("have.class", "foo")

  return "foobarbaz"
})

it("should throw", function(){
  cy.get("body").should("have.class", "foo")
   
  // currently Cypress detects this and forcibly
  // returns 'cy'. Instead we should throw.
  return "foobarbaz"
})

it("should also throw", function(){
  cy.foo()
})

it("does not throw", function(){
  // this is okay since no cy commands were invoked!
  expect(true).to.be.true
})

[brian-mann]

If promises are returned that is handled by: #464

If promises are returned in a custom command that is handled by: #435

All other value types will cause an exception to be thrown either when returning a value to a test, or a custom command.

[brian-mann]

Error when value is returned in a test

Error when value is returned in a custom command

[brian-mann]

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

[brian-mann]

Fixed in 0.20.0