diff --git a/cypress/integration/api_spec.js b/cypress/integration/api_spec.js index 5e0d974fd3..0b199c76e5 100644 --- a/cypress/integration/api_spec.js +++ b/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('<', '<').replace('>', '>') + } + 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) }) }) }) diff --git a/source/_data/sidebar.yml b/source/_data/sidebar.yml index dc04d82f99..ff177f941f 100644 --- a/source/_data/sidebar.yml +++ b/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 diff --git a/source/api/events/all-events.md b/source/api/events/all-events.md index 9e36473a73..c769df82e6 100644 --- a/source/api/events/all-events.md +++ b/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:` window-event %} | Fires when the specified window `` 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. diff --git a/source/api/events/window-event.md b/source/api/events/window-event.md new file mode 100644 index 0000000000..60929ecb71 --- /dev/null +++ b/source/api/events/window-event.md @@ -0,0 +1,61 @@ +--- +title: window:<event> +--- + +You can use the `window:` event to listen for arbitrary events on the page's `window`, where `` 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:` | {% 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. 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() +}) +``` diff --git a/source/guides/references/migration-guide.md b/source/guides/references/migration-guide.md index df1f4d2c67..28e62ff208 100644 --- a/source/guides/references/migration-guide.md +++ b/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... diff --git a/themes/cypress/languages/en.yml b/themes/cypress/languages/en.yml index 0f4c3ce3cf..9a40529350 100644 --- a/themes/cypress/languages/en.yml +++ b/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