add cy-events recipe (#632)

Author: bahmutov

README.md

@@ -20,6 +20,7 @@ Recipe | Description
 [Use Chrome Remote Interface](./examples/fundamentals__chrome-remote-debugging) | Use Chrome debugger protocol to trigger hover state and print media style
 [Out-of-the-box TypeScript](./examples/fundamentals__typescript) | Write tests in TypeScript without setting up preprocessors
 [Per-test timeout](./examples/fundamentals__timeout) | Fail a test if it runs longer than the specified time limit
+[Cypress events](./examples/fundamentals__cy-events) | Using `Cypress.on` and `cy.on` to listen to [Cypress events](https://on.cypress.io/catalog-of-events) like `before:window:load`
 
 ## Testing the DOM
 

circle.yml

@@ -223,6 +223,8 @@ jobs:
     <<: *defaults
   fundamentals__errors:
     <<: *defaults
+  fundamentals__cy-events:
+    <<: *defaults
   logging-in__csrf-tokens:
     <<: *defaults
   logging-in__html-web-forms:
@@ -433,6 +435,9 @@ all_jobs: &all_jobs
   - fundamentals__errors:
       requires:
         - build
+  - fundamentals__cy-events:
+      requires:
+        - build
   - logging-in__csrf-tokens:
       requires:
         - build
@@ -615,8 +620,9 @@ all_jobs: &all_jobs
         - fundamentals__module-api-wrap
         - fundamentals__add-custom-command
         - fundamentals__add-custom-command-ts
-        - fundamentals__errors
         - fundamentals__typescript
+        - fundamentals__errors
+        - fundamentals__cy-events
         - logging-in__csrf-tokens
         - logging-in__html-web-forms
         - logging-in__single-sign-on

examples/fundamentals__cy-events/README.md

@@ -0,0 +1,10 @@
+# Cypress events
+
+For more details, see [Cypress catalogue of events](https://on.cypress.io/catalog-of-events)
+
+- [cypress-on-spec.js]('./cypress/integration/cypress-on-spec.js) shows how we can add a property to every `window` object before the app load using `Cypress.on('window:before:load', ...)` event listener
+- [cy-on-spec.js]('./cypress/integration/cy-on-spec.js) shows how to add a property to every `window` object before the app loads using `cy.on('window:before:load', ...)` event listener.
+
+## See also
+
+- recipe "Handling errors" from the [Fundamentals recipes](https://github.com/cypress-io/cypress-example-recipes#fundamentals)

examples/fundamentals__cy-events/app.js

@@ -0,0 +1,7 @@
+/* eslint-env browser */
+document
+.getElementById('click-me')
+.addEventListener('click', () => {
+  /* global Analytics */
+  Analytics.sendEvent('click', 'button#click-me')
+})

examples/fundamentals__cy-events/cypress.json

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

examples/fundamentals__cy-events/cypress/integration/cy-on-spec.js

@@ -0,0 +1,36 @@
+/// <reference types="cypress" />
+
+describe('cy.on window:before:load', () => {
+  // @see https://on.cypress.io/catalog-of-events
+  // let's use "window:before:load" to automatically
+  // attach mock Analytics method to the application's "window" object
+  // we will use "cy.on" which requires a test or a hook to work
+  beforeEach(() => {
+    cy.on('window:before:load', (win) => {
+      win.Analytics = {
+        sendEvent: cy.stub().as('sendEvent'),
+      }
+    })
+  })
+
+  it('sends events', () => {
+    cy.visit('index.html')
+    cy.get('button#click-me').click().click()
+    cy.get('@sendEvent').should('be.calledTwice')
+    .invoke('reset') // reset the stub counter
+
+    cy.get('button#click-me').click()
+    cy.get('@sendEvent').should('be.calledOnceWithExactly', 'click', 'button#click-me')
+  })
+
+  it('sends more events', () => {
+    cy.visit('index.html')
+    cy.get('button#click-me').click()
+    // if we do not precise value for one of the arguments
+    // we can "skip" it but make sure it is still a string
+    // using Sinon matchers
+    //
+    cy.get('@sendEvent').should('be.calledOnceWith',
+      Cypress.sinon.match.string, 'button#click-me')
+  })
+})

examples/fundamentals__cy-events/cypress/integration/cypress-on-spec.js

@@ -0,0 +1,33 @@
+/// <reference types="cypress" />
+
+describe('Cypress.on window:before:load', () => {
+  // @see https://on.cypress.io/catalog-of-events
+  // let's use "window:before:load" to automatically
+  // attach mock Analytics method to the application's "window" object
+  Cypress.on('window:before:load', (win) => {
+    win.Analytics = {
+      sendEvent: cy.stub().as('sendEvent'),
+    }
+  })
+
+  it('sends events', () => {
+    cy.visit('index.html')
+    cy.get('button#click-me').click().click()
+    cy.get('@sendEvent').should('be.calledTwice')
+    .invoke('reset') // reset the stub counter
+
+    cy.get('button#click-me').click()
+    cy.get('@sendEvent').should('be.calledOnceWithExactly', 'click', 'button#click-me')
+  })
+
+  it('sends more events', () => {
+    cy.visit('index.html')
+    cy.get('button#click-me').click()
+    // if we do not precise value for one of the arguments
+    // we can "skip" it but make sure it is still a string
+    // using Sinon matchers
+    //
+    cy.get('@sendEvent').should('be.calledOnceWith',
+      Cypress.sinon.match.string, 'button#click-me')
+  })
+})

examples/fundamentals__cy-events/index.html

@@ -0,0 +1,12 @@
+<html lang="en">
+  <body>
+    <main>
+      <h1>Register events</h1>
+      <p>
+        Click on the button to file "analytics" event
+        <button id="click-me">Click me!</button>
+      </p>
+    </main>
+    <script src="app.js"></script>
+  </body>
+</html>

examples/fundamentals__cy-events/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "cy-events",
+  "version": "1.0.0",
+  "description": "Examples of Cypress events",
+  "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"
+  }
+}