add recipe showing how to handle errors (#619)

Author: bahmutov

README.md

@@ -8,6 +8,7 @@ Recipe | Description
 --- | ---
 [Node Modules](./examples/fundamentals__node-modules) | Import your own node modules
 [Environment variables](./examples/server-communication__env-variables) | Passing environment variables to tests
+[Handling errors](./examples/fundamentals__errors) | Handling thrown errors and unhandled promise rejections
 [Dynamic tests](./examples/fundamentals__dynamic-tests) | Create tests dynamically from data
 [Fixtures](./examples/fundamentals__fixtures) | Loading single or multiple fixtures
 [Adding Custom Commands](./examples/fundamentals__add-custom-command) | Write your own custom commands using JavaScript with correct types for IntelliSense to work

circle.yml

@@ -221,6 +221,8 @@ jobs:
     <<: *defaults
   fundamentals__add-custom-command-ts:
     <<: *defaults
+  fundamentals__errors:
+    <<: *defaults
   logging-in__csrf-tokens:
     <<: *defaults
   logging-in__html-web-forms:
@@ -428,6 +430,9 @@ all_jobs: &all_jobs
   - fundamentals__add-custom-command-ts:
       requires:
         - build
+  - fundamentals__errors:
+      requires:
+        - build
   - logging-in__csrf-tokens:
       requires:
         - build
@@ -610,6 +615,7 @@ all_jobs: &all_jobs
         - fundamentals__module-api-wrap
         - fundamentals__add-custom-command
         - fundamentals__add-custom-command-ts
+        - fundamentals__errors
         - fundamentals__typescript
         - logging-in__csrf-tokens
         - logging-in__html-web-forms

examples/fundamentals__errors/README.md

@@ -0,0 +1,27 @@
+# Handling application errors
+
+For more details, see [Cypress catalogue of events](https://on.cypress.io/catalog-of-events)
+
+## Exceptions
+
+If an application throws an error, it fails the Cypress test automatically.
+
+![Application error fails the test](./images/app-error.gif)
+
+You can see how to ignore such errors in [cypress/integration/app-error.js](./cypress/integration/app-error.js) spec file
+
+## Test fails
+
+If a Cypress command fails, the test fails
+
+![Test fails after it fails to find an element](./images/test-error.gif)
+
+You can listen to the "fail" events and return false to NOT fail the test, as [cypress/integration/test-fails.js](./cypress/integration/test-fails.js) shows.
+
+## Unhandled promise rejections
+
+If the application code creates an unhandled rejected promise, Cypress does NOT see it by default and continues with the test. If you want to fail the test, listen to the unhandled promise event and throw an error.
+
+![Test failing after an application has unhandled rejected promise](./images/unhandled-promise.gif)
+
+You can register your own unhandled promise event listener during `cy.visit` as [cypress/integration/unhandled-promise.js](./cypress/integration/unhandled-promise.js) shows. Or you can register the window handler for all tests using `Cypress.on('window:before:load')` call, see [cypress/integration/unhandled-promise2.js](./cypress/integration/unhandled-promise2.js).

examples/fundamentals__errors/app.js

@@ -0,0 +1,20 @@
+/* eslint-env browser */
+
+/* eslint-disable no-console */
+document.getElementById('error').addEventListener('click', () => {
+  console.log('application will throw an error in 1 second')
+  setTimeout(() => {
+    console.log('application is about to throw an error')
+    throw new Error('Things went bad')
+  }, 1000)
+})
+
+document.getElementById('promise').addEventListener('click', () => {
+  console.log('application with NOT handle a rejected promise in 1 second')
+  new Promise((resolve, reject) => {
+    setTimeout(() => {
+      console.log('application is about to reject a promise')
+      reject('Did not handle this promise')
+    }, 1000)
+  })
+})

examples/fundamentals__errors/cypress.json

@@ -0,0 +1,5 @@
+{
+  "pluginsFile": false,
+  "fixturesFolder": false,
+  "supportFile": false
+}

examples/fundamentals__errors/cypress/integration/app-error.js

@@ -0,0 +1,41 @@
+/// <reference types="cypress" />
+
+/* eslint-disable no-console */
+describe('App error', () => {
+  // NOTE: run this test to see it fail on application error
+  it.skip('fails the Cypress test', () => {
+    cy.visit('index.html')
+    cy.get('button#error').click()
+    // the error happens after 1000ms
+    cy.wait(1500)
+  })
+
+  it('can be ignored', () => {
+    /**
+     * By using "cy.on()" we can ignore an exception in the current test only.
+     * If you want to register exception handler for all tests using "Cypress.on()"
+     * @see https://on.cypress.io/catalog-of-events
+     * @param {Error} e The exception we caught
+     * @param {Mocha.Runnable} runnable is the current test or hook during which the error is caught
+     */
+    cy.on('uncaught:exception', (e, runnable) => {
+      console.log('error', e)
+      console.log('runnable', runnable)
+
+      // we can simply return false to avoid failing the test on uncaught error
+      // return false
+      // but a better strategy is to make sure the error is expected
+      if (e.message.includes('Things went bad')) {
+        // we expected this error, so let's ignore it
+        // and let the test continue
+        return false
+      }
+      // on any other error message the test fails
+    })
+
+    cy.visit('index.html')
+    cy.get('button#error').click()
+    // the error happens after 1000ms
+    cy.wait(1500)
+  })
+})

examples/fundamentals__errors/cypress/integration/test-fails.js

@@ -0,0 +1,43 @@
+/// <reference types="cypress" />
+
+/* eslint-disable no-console */
+describe('Test fails', () => {
+  // NOTE: run this test to see it fail because it tries to get an non-existent button
+  it.skip('when the command fails', () => {
+    cy.visit('index.html')
+    cy.get('button#does-not-exist', { timeout: 1000 }).click()
+  })
+
+  it('can be ignored', () => {
+    /**
+     * By using "cy.on()" we can ignore the current test failing.
+     * If you want to register this handler for all tests use "Cypress.on()"
+     * @see https://on.cypress.io/catalog-of-events
+     * @param {Error} e The exception we caught
+     * @param {Mocha.Runnable} runnable is the current test or hook during which the error is caught
+     */
+    cy.on('fail', (e, runnable) => {
+      console.log('error', e)
+      console.log('runnable', runnable)
+
+      // we can simply return false to avoid failing the test on uncaught error
+      // return false
+      // but a better strategy is to make sure the error is expected
+      if (e.name === 'AssertionError' &&
+        e.message.includes('Expected to find element: `button#does-not-exist`, but never found it')) {
+        // we expected this error, so let's ignore it
+        // and let the test continue
+        return false
+      }
+      // on any other error message the test fails
+    })
+
+    cy.visit('index.html')
+    cy.get('button#does-not-exist', { timeout: 1000 }).click()
+
+    // note: after the cy.get fails and the test fails
+    // the remaining commands are NOT executed
+    // thus this failing assertion never gets to run
+    cy.wrap(false).should('be.true')
+  })
+})

examples/fundamentals__errors/cypress/integration/unhandled-promise.js

@@ -0,0 +1,37 @@
+/// <reference types="cypress" />
+
+/* eslint-disable no-console */
+describe('Unhandled promises', () => {
+  it('does not affect the Cypress test', () => {
+    cy.visit('index.html')
+    cy.get('button#promise').click()
+    // the unhandled promise happens after 1000ms
+    cy.wait(1500)
+    // but our test happily finishes
+  })
+
+  // NOTE: skipping the test because it shows how to fail the test for real
+  it.skip('fails Cypress test if we register our own handler', () => {
+    // we can install our handler to listen for unhandled rejected promises
+    // in the application code and fail the test
+    cy.visit('index.html', {
+      onBeforeLoad (win) {
+        // https://developer.mozilla.org/en-US/docs/Web/API/Window/unhandledrejection_event
+        win.addEventListener('unhandledrejection', (event) => {
+          const msg = `UNHANDLED PROMISE REJECTION: ${event.reason}`
+
+          // fail the test
+          throw new Error(msg)
+        })
+      },
+    })
+
+    cy.get('button#promise').click()
+    // the unhandled promise happens after 1000ms
+    cy.wait(1500)
+  })
+
+  afterEach(() => {
+    console.log('afterEach')
+  })
+})

examples/fundamentals__errors/cypress/integration/unhandled-promise2.js

@@ -0,0 +1,30 @@
+/// <reference types="cypress" />
+
+/* eslint-disable no-console */
+describe('Unhandled promises using window event', () => {
+  // we can bind to the events before each test using "cy.on()" call
+  // or for all events using "Cypress.on()" call, usually placed into support file
+  before(() => {
+    Cypress.on('window:before:load', (win) => {
+      // https://developer.mozilla.org/en-US/docs/Web/API/Window/unhandledrejection_event
+      win.addEventListener('unhandledrejection', (event) => {
+        const msg = `UNHANDLED PROMISE REJECTION: ${event.reason}`
+
+        // fail the test
+        throw new Error(msg)
+      })
+    })
+  })
+
+  // NOTE: skipping the test because it shows how to fail the test for real
+  it.skip('fails Cypress test if we register our own handler', () => {
+    cy.visit('index.html')
+    cy.get('button#promise').click()
+    // the unhandled promise happens after 1000ms
+    cy.wait(1500)
+  })
+
+  afterEach(() => {
+    console.log('afterEach')
+  })
+})

examples/fundamentals__errors/images/app-error.gif

@@ -0,0 +1,17 @@
+<html lang="en">
+  <body>
+    <main>
+      <h1>Handling application errors</h1>
+      <p>
+        Click on the button to cause application error
+        <button id="error">Throw an error</button>
+      </p>
+
+      <p>
+        This button tells the application to create an unhandled rejected promise
+        <button id="promise">Unhandle</button>
+      </p>
+    </main>
+    <script src="app.js"></script>
+  </body>
+</html>

examples/fundamentals__errors/images/test-error.gif

@@ -0,0 +1,12 @@
+{
+  "name": "handling-application-errors",
+  "version": "1.0.0",
+  "description": "Handling application errors example",
+  "private": true,
+  "scripts": {
+    "cypress:open": "../../node_modules/.bin/cypress open",
+    "cypress:run": "../../node_modules/.bin/cypress run",
+    "test:ci": "../../node_modules/.bin/cypress run",
+    "test:ci:record": "../../node_modules/.bin/cypress run --record"
+  }
+}