Update errors recipe (#717)

* show example with waiting for an error

* update unhandled project rejection spec file

Author: bahmutov

examples/fundamentals__errors/README.md

@@ -10,6 +10,20 @@ If an application throws an error, it fails the Cypress test automatically.
 
 You can see how to ignore such errors in [cypress/integration/app-error.js](./cypress/integration/app-error.js) spec file.
 
+```js
+// inspect the caught error
+cy.on('uncaught:exception', (e) => {
+  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
+})
+```
+
+Make sure the test is long enough or waits for the error to happen!
+
 See short video about this topic here: [https://www.youtube.com/watch?v=DwVezYq4zPM](https://www.youtube.com/watch?v=DwVezYq4zPM)
 
 ## Test fails
@@ -22,13 +36,7 @@ You can listen to the "fail" events and return false to NOT fail the test, as [c
 
 ## Unhandled promise rejections in the application
 
-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).
-
-You can also watch a small video explaining it here: [https://www.youtube.com/watch?v=VY9yVle8LRQ](https://www.youtube.com/watch?v=VY9yVle8LRQ)
+Cypress v7+ automatically fails the test if the application has an unhandled promise rejection event. See the [cypress/integration/unhandled-promise.js](./cypress/integration/unhandled-promise.js) spec file.
 
 ## Unhandled promise rejections in the test code
 

examples/fundamentals__errors/app.js

@@ -14,7 +14,8 @@ document.getElementById('promise').addEventListener('click', () => {
   new Promise((resolve, reject) => {
     setTimeout(() => {
       console.log('application is about to reject a promise')
-      reject('Did not handle this promise')
+      // important: reject with an Error object
+      reject(new Error('Did not handle this promise'))
     }, 1000)
   })
 })

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

@@ -36,6 +36,42 @@ describe('App error', () => {
     cy.visit('index.html')
     cy.get('button#error').click()
     // the error happens after 1000ms
+    // we can use hard-coded wait, see the other test
+    // to learn how to avoid an unnecessary wait
     cy.wait(1500)
   })
+
+  // if the test finishes before the error is thrown -
+  // the test is still passing!
+  // NOTE: just a demo of the test that does not wait for an error
+  it.skip('does not wait for the error', () => {
+    cy.visit('index.html')
+    cy.get('button#error').click()
+    // the thrown error is "lost" because the test finishes
+  })
+
+  // we can avoid hard-coded waits in the test
+  // by using Cypress retry-ability
+  // https://on.cypress.io/retry-ability
+  it('waits for the error', () => {
+    // place any caught errors in this object
+    const caught = {
+      message: null,
+    }
+
+    cy.on('uncaught:exception', (e) => {
+      caught.message = e.message
+
+      // ignore the error
+      return false
+    })
+
+    cy.visit('index.html')
+    cy.get('button#error').click()
+
+    // waits for the error and confirms the message
+    cy.wrap(caught).should((c) => {
+      expect(c.message).to.include('Things went bad')
+    })
+  })
 })

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

@@ -2,37 +2,32 @@
 
 /* eslint-disable no-console */
 describe('Unhandled promises', () => {
-  // NOTE: this test will pass in Cypress < 7.0 and fail in Cypress 7.0+
-  it.skip('does not affect the Cypress test', () => {
+  // NOTE: this test fails in Cypress 7.0+
+  it.skip('fail 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}`
+  it('handles the promise rejection', () => {
+    // place any caught errors in this object
+    const caught = {
+      message: null,
+    }
 
-          // fail the test
-          throw new Error(msg)
-        })
-      },
+    cy.on('uncaught:exception', (e, runnable, promise) => {
+      caught.message = e.message
+
+      return false
     })
 
-    cy.get('button#promise').click()
-    // the unhandled promise happens after 1000ms
-    cy.wait(1500)
-  })
+    cy.visit('index.html')
 
-  afterEach(() => {
-    console.log('afterEach')
+    cy.get('button#promise').click()
+    // waits for the error and confirms the message
+    cy.wrap(caught).should((c) => {
+      expect(c.message).to.include('Did not handle this promise')
+    })
   })
 })