Add doc for window events

cypress/integration/api_spec.js

@@ -109,14 +109,19 @@ describe('API', () => {
       })
 
       it('displays sidebar in mobile menu on click', () => {
+        const replaceHtmlEntities = (text) => {
+          return text.replace('&lt;', '<').replace('&gt;', '>')
+        }
+
         cy.get('#mobile-nav-toggle').click()
 
         cy.get('#mobile-nav-inner').should('be.visible')
         .find('.sidebar-li')
         .each(function (displayedLink, i) {
-          const englishLink = this.english.sidebar.api[this.sidebarLinkNames[i]]
+          const displayedLinkText = replaceHtmlEntities(displayedLink.text().trim())
+          const englishLink = replaceHtmlEntities(this.english.sidebar.api[this.sidebarLinkNames[i]])
 
-          expect(displayedLink.text().trim()).to.eq(englishLink)
+          expect(displayedLinkText).to.eq(englishLink)
         })
       })
     })

source/_data/sidebar.yml

@@ -177,6 +177,7 @@ api:
     test-start-event: test-start-event.html
     uncaught-exception-event: uncaught-exception-event.html
     viewport-change-event: viewport-change-event.html
+    window-event: window-event.html
   cypress-api:
     custom-commands: custom-commands.html
     cookies: cookies.html

source/api/events/all-events.md

@@ -39,6 +39,7 @@ Event                                                             | Description
 {% url `test:start` test-start-event %}                           | Fires before a test and all its **before** and **beforeEach** hooks run, with details about the test.
 {% url `uncaught:exception` uncaught-exception-event %}           | Fires after an uncaught exception occurs, with the error and the mocha runnable object.
 {% url `viewport:change` viewport-change-event %}                 | Fires after the viewport changes, with the new viewport dimensions.
+{% url `window:<event>` window-event %}                           | Fires when the specified window `<event>` fires.
 
 You can listen to browser events in your spec files or in your {% url "support file" writing-and-organizing-tests#Support-file %} via the `Cypress` and `cy` objects.
 

source/api/events/window-event.md

@@ -0,0 +1,61 @@
+---
+title: window:<event>
+---
+
+You can use the `window:<event>` event to listen for arbitrary events on the page's `window`, where `<event>` is any event name that can be listened for on a page's `window`. This is the same as listening to the events with `window.addEventListener` with the following advantages:
+
+* You can listen before the page has loaded (before {% url "`cy.visit()`" visit %}) and the listener will be bound once the page loads.
+* If the page changes or transitions, the listener will be re-bound when the new page loads.
+* If you listen with `cy.on` (as opposed to `Cypress.on`), the listener will be unbound when the test ends.
+
+There are a large number of events you can listen to. {% url "View this reference" https://developer.mozilla.org/en-US/docs/Web/Events %} for list of many of them.
+
+# Environment
+
+{% wrap_start 'event-environment' %}
+
+Some events run in the {% url "browser" all-events#Browser-Events %}, some in the {% url "background process" background-process %}, and some in both.
+
+Event | Browser | Background Process
+--- | --- | ---
+`window:<event>` | {% fa fa-check-circle green %} | {% fa fa-times-circle grey %}
+
+{% wrap_end %}
+
+# Arguments
+
+**{% fa fa-angle-right %} event** ***(Object)***
+
+The event object. The type of object and properties on the object depend on the event.
+
+# Usage
+
+To listen to an event on the window, prefix it with `window:`. For example, to listen to the `resize` event, listen to `window:resize`.
+
+## In the browser
+
+In a spec file or support file you can tap into the `window:<event>` event. In this example we listen to the `hashchange` event via `window:hashchange` in order to assert that the URL changed as expected.
+
+```javascript
+it('visits about when "about" is clicked', (done) => {
+  cy.on('window:hashchange', (event) => {
+    // event looks like:
+    // {
+    //   bubbles: false
+    //   defaultPrevented: false
+    //   newURL: "http://localhost:8080/index.html#about"
+    //   oldURL: "http://localhost:8080/index.html"
+    //   target: Window {...}
+    //   type: "hashchange"
+    //   ... more properties ...
+    // }
+
+    expect(event.newUrl).to.match(/about/)
+    done()
+  })
+
+  cy.visit('http://localhost:8080/index.html')
+  // this will navigate to #about and trigger a hashchange event
+  cy.get('.nav .about').click()
+})
+```

source/guides/references/migration-guide.md

@@ -85,7 +85,7 @@ If you listen for any of the following events in your test code, you'll need to
 - Rename `window:alert` to `page:alert`
 - Rename `window:confirm` to `page:confirm`
 - Rename `window:before:load` to `page:start`
-- Rename `window:before:unload` to `before:window:unload`
+- Rename `window:before:unload` to `window:beforeunload`
 
 For example, in your test code...
 

themes/cypress/languages/en.yml

@@ -220,6 +220,7 @@ sidebar:
     page-confirm-event: page:confirm
     page-ready-event: page:ready
     page-end-event: page:end
+    window-event: window:<event>
   examples:
     examples: Examples
     recipes: Recipes