feat: add cy.raise (#44)

## raise

This plugin includes a utility custom command `cy.raise` that lets you conveniently throw an error.

```js
cy.get('li').if('not.have.length', 3).raise('Wrong number of todos')
```

**Tip:** the above syntax works, but you better pass an Error instance rather than a string to get the exact stack trace location

```js
cy.get('li').if('not.have.length', 3).raise(new Error('Wrong number of todos'))
```

README.md

@@ -201,6 +201,20 @@ cy.wrap(42).if('not.null') // takes IF path
 
 See spec [null.cy.js](./cypress/e2e/null.cy.js)
 
+## raise
+
+This plugin includes a utility custom command `cy.raise` that lets you conveniently throw an error.
+
+```js
+cy.get('li').if('not.have.length', 3).raise('Wrong number of todos')
+```
+
+**Tip:** the above syntax works, but you better pass an Error instance rather than a string to get the exact stack trace location
+
+```js
+cy.get('li').if('not.have.length', 3).raise(new Error('Wrong number of todos'))
+```
+
 ## More examples
 
 Check out the spec files in [cypress/e2e](./cypress/e2e/) folder. If you still have a question, [open a GitHub issue](https://github.com/bahmutov/cypress-if/issues).

cypress/e2e/raise-error.cy.js

@@ -0,0 +1,72 @@
+/// <reference types="cypress" />
+// @ts-check
+
+import '../../src'
+
+it('raises an error if wrong number of elements', () => {
+  // prevent ".raise" from failing the test
+  Cypress.Commands.overwrite('raise', cy.stub().as('raise'))
+
+  cy.visit('cypress/index.html')
+  // we have 3 items
+  cy.get('#fruits li').should('have.length', 3)
+  // force an error
+  cy.get('#fruits li')
+    .if('have.length', 1)
+    .then(cy.spy().as('if'))
+    .log('right number of elements')
+    .else()
+    .log('too many elements')
+    .then(cy.spy().as('else'))
+    .raise('Too many elements')
+  cy.get('@else').should('have.been.calledOnce')
+  cy.get('@if').should('not.have.been.called')
+})
+
+it('raises an error if not the right number of elements', () => {
+  // prevent ".raise" from failing the test
+  Cypress.Commands.overwrite('raise', cy.stub().as('raise'))
+
+  cy.visit('cypress/index.html')
+  // we have 3 items
+  cy.get('#fruits li').should('have.length', 3)
+  // force an error
+  cy.get('#fruits li')
+    .if('not.have.length', 1)
+    .log('wrong number of items')
+    .then(cy.spy().as('else'))
+    .raise('Too many elements')
+  cy.get('@else').should('have.been.calledOnce')
+})
+
+it('raises an error instance', () => {
+  // prevent ".raise" from failing the test
+  Cypress.Commands.overwrite('raise', cy.stub().as('raise'))
+
+  cy.visit('cypress/index.html')
+  // we have 3 items
+  cy.get('#fruits li').should('have.length', 3)
+  // force an error
+  cy.get('#fruits li')
+    .if('not.have.length', 1)
+    .log('wrong number of items')
+    .then(cy.spy().as('else'))
+    // when using an Error instance (and not a string)
+    // the error stack will point at this spec location
+    .raise(new Error('Too many elements'))
+  cy.get('@else').should('have.been.calledOnce')
+})
+
+it.skip('raises an error if element does not exist', () => {
+  // prevent ".raise" from failing the test
+  Cypress.Commands.overwrite('raise', cy.stub().as('raise'))
+
+  cy.visit('cypress/index.html')
+  // force an error
+  cy.get('#does-not-exist')
+    .if('not.exist')
+    .log('no such element')
+    .then(cy.spy().as('else'))
+    .raise('Cannot find it')
+  cy.get('@else').should('have.been.calledOnce')
+})

src/index.d.ts

@@ -64,5 +64,14 @@ declare namespace Cypress {
      *    .finally().should('be.checked')
      */
     finally(): Chainable<any>
+
+    /**
+     * A simple way to throw an error
+     * @example
+     *  cy.get('li')
+     *    .if('not.have.length', 3)
+     *    .raise('wrong number of todo items')
+     */
+    raise(x: string | Error): Chainable<void>
   }
 }

src/index.js

@@ -321,3 +321,15 @@ Cypress.Commands.overwrite('task', function (task, args, options) {
 
   return task(args, options)
 })
+
+Cypress.Commands.add('raise', (x) => {
+  if (Cypress._.isError(x)) {
+    throw x
+  }
+  const e = new Error(
+    String(x) +
+      '\n' +
+      'cypress-if tip: pass an error instance to have correct stack',
+  )
+  throw e
+})