add example wrapping async function in custom command (#424)

Author: bahmutov

examples/fundamentals__add-custom-command/README.md

@@ -46,6 +46,10 @@ And the TypeScript and IntelliSense should be happy
 
 As an example this spec includes 3rd party module [cypress-wait-until](https://github.com/NoriSte/cypress-wait-until). This module ships with its own TypeScript definition, which allows `cy.waitUntil` to work.
 
+## Async commands
+
+A custom command can call an async function from the application, the resolved value will be automatically yielded to the next command or assertion in the test. See [cypress/integration/async-command.js](cypress/integration/async-command.js) file.
+
 ## More info
 
 - [Cypress custom commands](https://on.cypress.io/custom-commands)

examples/fundamentals__add-custom-command/cypress/integration/async-command.js

@@ -0,0 +1,19 @@
+/// <reference types="cypress" />
+Cypress.Commands.add('asyncAdd', (a, b) => {
+  cy.log(`${a} + ${b}`)
+  // our application in "index.html" has placed a promise-returning
+  // method "asyncAdd" onto the "window" object.
+  // from the tests's custom command we can invoke that method
+  // Cypress automatically waits for the promises to resolve
+  // before yielding their value to the next command in the test
+  // https://on.cypress.io/invoke
+  cy.window().invoke('asyncAdd', a, b)
+})
+
+describe('example', () => {
+  it('adds numbers using custom command', () => {
+    cy.visit('index.html')
+    // the custom command will yield resolved value
+    cy.asyncAdd(2, 3).should('equal', 5)
+  })
+})

examples/fundamentals__add-custom-command/index.html

@@ -12,4 +12,15 @@ <h1 data-cy="greeting">Page title</h1>
       document.body.appendChild(el)
     }, 1000)
   </script>
+
+  <script>
+    // method is added to the "window" object dynamically
+    setTimeout(() => {
+      window.asyncAdd = (a, b) => {
+        return new Promise((resolve) => {
+          setTimeout(() => resolve(a + b), 1000)
+        })
+      }
+    }, 1000)
+  </script>
 </body>