{ "doc": { "id": "api/cypress-api/catalog-of-events", "title": "Catalog of Events", "description": null, "section": "api", "source_path": "/llm/markdown/api/cypress-api/catalog-of-events.md", "version": "6a908a532b1fca4ed18538a4c1c5a9bc7f24f403", "updated_at": "2026-05-01T19:25:18.656Z", "headings": [ { "id": "api/cypress-api/catalog-of-events#catalog-of-events", "text": "Catalog of Events", "level": 1 }, { "id": "api/cypress-api/catalog-of-events#event-types", "text": "Event Types", "level": 2 }, { "id": "api/cypress-api/catalog-of-events#app-events", "text": "App Events", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#cypress-events", "text": "Cypress Events", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#other-events", "text": "Other Events", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#binding-to-events", "text": "Binding to Events", "level": 2 }, { "id": "api/cypress-api/catalog-of-events#cypress", "text": "Cypress", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#cy", "text": "cy", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#cleanup-cypress-on-vs-cy-on", "text": "Cleanup: Cypress.on vs cy.on​", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#cypress-commands-inside-cypress-on-listeners", "text": "Cypress commands inside Cypress.on listeners", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#examples", "text": "Examples", "level": 2 }, { "id": "api/cypress-api/catalog-of-events#uncaught-exceptions", "text": "Uncaught Exceptions", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#to-turn-off-all-uncaught-exception-handling", "text": "To turn off all uncaught exception handling", "level": 4 }, { "id": "api/cypress-api/catalog-of-events#to-conditionally-turn-off-uncaught-exception-handling-for-a-certain-error", "text": "To conditionally turn off uncaught exception handling for a certain error", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#to-conditionally-turn-off-uncaught-exception-handling-unhandled-promise-rejections", "text": "To conditionally turn off uncaught exception handling unhandled promise rejections", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#to-catch-a-single-uncaught-exception", "text": "To catch a single uncaught exception", "level": 4 }, { "id": "api/cypress-api/catalog-of-events#catching-test-failures", "text": "Catching Test Failures", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#debug-the-moment-a-test-fails", "text": "Debug the moment a test fails", "level": 4 }, { "id": "api/cypress-api/catalog-of-events#page-navigation", "text": "Page Navigation[", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#test-that-your-application-was-redirected", "text": "Test that your application was redirected", "level": 4 }, { "id": "api/cypress-api/catalog-of-events#window-before-load", "text": "Window Before Load[", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#modify-your-application-before-it-loads-after-page-transitions", "text": "Modify your Application before it loads after page transitions", "level": 4 }, { "id": "api/cypress-api/catalog-of-events#window-confirm", "text": "Window Confirm", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#control-whether-you-accept-or-reject-confirmations", "text": "Control whether you accept or reject confirmations", "level": 4 }, { "id": "api/cypress-api/catalog-of-events#window-alert", "text": "Window Alert", "level": 3 }, { "id": "api/cypress-api/catalog-of-events#assert-on-the-alert-text", "text": "Assert on the alert text", "level": 4 }, { "id": "api/cypress-api/catalog-of-events#notes", "text": "Notes", "level": 2 }, { "id": "api/cypress-api/catalog-of-events#logging-all-events", "text": "Logging All Events", "level": 3 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Catalog of Events" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress emits a series of events as it runs in your browser." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "These events are useful not only to control your application's behavior, but also for debugging purposes." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Here are some examples you can do with these events:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Listen for `uncaught exceptions` and prevent Cypress from failing the test" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Listen for `alert` or `confirm` calls and change the `confirm` behavior" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Listen for `window:before:load` events and modify the `window` before any of your app code runs between page transitions" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Listen for `command:retry` events to understand why Cypress is internally retrying for debugging purposes" } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Event Types" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "App Events" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "These events come from the application currently under test (your application). These are the most useful events for you to listen to." } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`uncaught:exception`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "the error (Object), Mocha runnable (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires when an uncaught exception occurs in your application. Cypress will fail the test when this fires. Return `false` from this event and Cypress will not fail the test. Also useful for debugging purposes because the actual `error` instance is provided to you. See our recipe " }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/recipes.md#Fundamentals", "children": [ { "type": "text", "value": "Handling errors" } ] }, { "type": "text", "value": "." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`window:confirm`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "the confirmation text (String)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires when your app calls the global `window.confirm()` method. Cypress will auto accept confirmations. Return `false` from this event and the confirmation will be canceled." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`window:alert`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "the alert text (String)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires when your app calls the global `window.alert()` method. Cypress will auto accept alerts. You cannot change this behavior." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`window:before:load`[" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "End-to-End Only" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "](/llm/markdown/app/core-concepts/testing-types.md#What-is-E2E-Testing) |\n| Yields: | the remote window (Object) |\n| Description: | Fires as the page begins to load, but before any of your applications JavaScript has executed. This fires at the exact same time as `cy.visit()` `onBeforeLoad` callback. Useful to modify the window on a page transition. |" } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`window:load`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "the remote window (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires after all your resources have finished loading after a page transition. This fires at the exact same time as a `cy.visit()` `onLoad` callback." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`window:before:unload`[" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "End-to-End Only" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "](/llm/markdown/app/core-concepts/testing-types.md#What-is-E2E-Testing) |\n| Yields: | the actual beforeunload event (Object) |\n| Description: | Fires when your application is about to navigate away. The real event object is provided to you. Your app may have set a `returnValue` on the event, which is useful to assert on. |" } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`window:unload`[" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "End-to-End Only" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "](/llm/markdown/app/core-concepts/testing-types.md#What-is-E2E-Testing) |\n| Yields: | the actual unload event (Object) |\n| Description: | Fires when your application has unloaded and is navigating away. The real event object is provided to you. This event is not cancelable. |" } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`url:changed`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "the new url (String)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires whenever Cypress detects that your application's URL has changed." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Cypress Events" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "These events come from Cypress as it issues commands and reacts to their state. These are all useful to listen to for debugging purposes." } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`fail`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "the error (Object), Mocha runnable (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires when the test has failed. Binding to this event without rethrowing the error will prevent the test from having a 'failed' state. Subsequent commands will not be executed. However this is strongly discouraged. Tests should never legitimately fail. This event exists because it's extremely useful for debugging purposes. See our recipe " }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/recipes.md#Fundamentals", "children": [ { "type": "text", "value": "Handling errors" } ] }, { "type": "text", "value": "." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`viewport:changed`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "the new viewport (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires whenever the viewport changes via a `cy.viewport()` or naturally when Cypress resets the viewport to the default between tests. Useful for debugging purposes." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`scrolled`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "the element or window being scrolled (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires whenever Cypress is scrolling your application. This event is fired when Cypress is " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/interacting-with-elements.md", "children": [ { "type": "text", "value": "waiting for and calculating actionability" } ] }, { "type": "text", "value": ". It will scroll to 'uncover' elements currently being covered. This event is extremely useful to debug why Cypress may think an element is not interactive." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`command:enqueued`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "command properties and arguments (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires when a cy command is first invoked and enqueued to be run later. Useful for debugging purposes if you're confused about the order in which commands will execute." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`command:start`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "command instance (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires when cy begins actually running and executing your command. Useful for debugging and understanding how the command queue is async." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`command:end`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "command instance (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires when cy finishes running and executing your command. Useful for debugging and understanding how commands are handled." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`command:retry`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "retry options (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires whenever a command begins its " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/retry-ability.md", "children": [ { "type": "text", "value": "retrying routines" } ] }, { "type": "text", "value": ". This is called on the trailing edge after Cypress has internally waited for the retry interval. Useful to understand why a command is retrying, and generally includes the actual error causing the retry to happen. When commands fail the final error is the one that actually bubbles up to fail the test. This event is essentially to debug why Cypress is failing." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`log:added`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "log attributes (Object), log instance (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires whenever a command emits this event so it can be displayed in the Command Log. Useful to see how internal cypress commands utilize the " }, { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/cypress-log.md", "children": [ { "type": "text", "value": "Cypress.log()" } ] }, { "type": "text", "value": " API." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`log:changed`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "log attributes (Object), log instance (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires whenever a command's attributes changes. This event is debounced to prevent it from firing too quickly and too often. Useful to see how internal cypress commands utilize the " }, { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/cypress-log.md", "children": [ { "type": "text", "value": "Cypress.log()" } ] }, { "type": "text", "value": " API." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`test:before:run`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "test attributes (Object), runnable instance (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires before the test and all before and beforeEach hooks run." } ] } ] } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Event" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Details" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Name:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`test:after:run`" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Yields:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "test attributes (Object), runnable instance (Object)" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Description:" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Fires after the test and all afterEach and after hooks run." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Other Events" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "There are a myriad of other events Cypress fires to communicate with the Node server process, automation servers, mocha, the application, and the reporter. They are strictly internal to the way Cypress works and not useful for users." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Binding to Events" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Both the global `Cypress` and `cy` objects are standard Node event emitters. That means you can use the following methods to bind and unbind from events." } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://nodejs.org/api/events.html#events_emitter_on_eventname_listener", "children": [ { "type": "text", "value": "on" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://nodejs.org/api/events.html#events_emitter_once_eventname_listener", "children": [ { "type": "text", "value": "once" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://nodejs.org/api/events.html#events_emitter_off_eventname_listener", "children": [ { "type": "text", "value": "off" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://nodejs.org/api/events.html#events_emitter_removelistener_eventname_listener", "children": [ { "type": "text", "value": "removeListener" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://nodejs.org/api/events.html#events_emitter_removealllisteners_eventname", "children": [ { "type": "text", "value": "removeAllListeners" } ] } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "It's important to understand why you'd want to bind to either `Cypress` or `cy`." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Cypress" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress is a global object that persists for the entirety of all of your tests. Any events you bind to Cypress will apply to all tests, and will not be unbound unless you manually unbind them. A listener registered inside a hook or an `it` is still a global listener: it is not limited to that hook invocation or to that single test." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "This is useful when you're debugging and want to add a single \"catch-all\" event to track down things like test failures, or uncaught exceptions from your application." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "cy" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `cy` object is bound to each individual test. Events bound to `cy` will automatically be removed when the test ends. You don't have to worry about cleanup, and your event listeners will only be called for the duration of the single test." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Cleanup: `Cypress.on` vs `cy.on`" }, { "type": "link", "title": null, "url": "#Cleanup-Cypresson-vs-cyon", "children": [ { "type": "text", "value": "​" } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Every call to `Cypress.on` adds another listener. Cypress does not remove those listeners between tests or hook runs. If you register the same handler in `beforeEach` without unregistering it, you accumulate duplicate listeners, so one uncaught exception can invoke your handler many times and behavior can drift as the suite runs." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When you only need a global handler for part of a run, register it once (for example in a " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file", "children": [ { "type": "text", "value": "support file" } ] }, { "type": "text", "value": "), or keep a reference to the same function and unregister it with `Cypress.off` or " }, { "type": "link", "title": null, "url": "https://nodejs.org/api/events.html#events_emitter_removelistener_eventname_listener", "children": [ { "type": "text", "value": "`removeListener`" } ] }, { "type": "text", "value": " when the listener is no longer needed." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "By contrast, `cy.on` listeners are torn down when the test finishes, so they are appropriate when you want per-test behavior (for example a one-off `uncaught:exception` handler) without manual cleanup." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Cypress commands inside `Cypress.on` listeners" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "`Cypress.on` callbacks run outside Cypress's normal command queue. `cy` commands, assertions, and `cy.task()` are not supported inside these listeners—they do not execute the way they do in a test body. You may see misleading errors, Command Log entries that do not reflect real execution, or other confusing results. Keep listener code synchronous (for example return `false` from `uncaught:exception` to ignore a known error), or capture data in the listener and act on it later inside a command chain. See " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress/issues/6316", "children": [ { "type": "text", "value": "#6316" } ] }, { "type": "text", "value": " for discussion of this limitation and of surfacing a clearer error when commands are used here." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Examples" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Uncaught Exceptions" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "To turn off all uncaught exception handling" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A great place to put this configuration is in the " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file", "children": [ { "type": "text", "value": "supportFile" } ] }, { "type": "text", "value": ", since it is loaded before any test files are evaluated." } ] }, { "type": "code", "lang": null, "meta": null, "value": "Cypress.on('uncaught:exception', (err, runnable) => { // returning false here prevents Cypress from // failing the test return false})" }, { "type": "paragraph", "children": [ { "type": "text", "value": "If an uncaught exception is thrown from a domain within a `cy.origin()` command, the uncaught exception handler will need to added within the `cy.origin()` command to take effect." } ] }, { "type": "code", "lang": null, "meta": null, "value": "cy.origin('https://example.cypress.io', () => { Cypress.on('uncaught:exception', (err, runnable) => { // returning false here prevents Cypress // inside the cy.origin() method from failing the test return false })})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "To conditionally turn off uncaught exception handling for a certain error" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A great place to put this configuration is in the " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file", "children": [ { "type": "text", "value": "supportFile" } ] }, { "type": "text", "value": ", since it is loaded before any test files are evaluated." } ] }, { "type": "code", "lang": null, "meta": null, "value": "Cypress.on('uncaught:exception', (err, runnable) => { // we expect a 3rd party library error with message 'list not defined' // and don't want to fail the test so we return false if (err.message.includes('list not defined')) { return false } // we still want to ensure there are no other unexpected // errors, so we let them fail the test})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "To conditionally turn off uncaught exception handling unhandled promise rejections" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A great place to put this configuration is in the " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file", "children": [ { "type": "text", "value": "supportFile" } ] }, { "type": "text", "value": ", since it is loaded before any test files are evaluated." } ] }, { "type": "code", "lang": null, "meta": null, "value": "Cypress.on('uncaught:exception', (err, runnable, promise) => { // when the exception originated from an unhandled promise // rejection, the promise is provided as a third argument // you can turn off failing the test in this case if (promise) { return false } // we still want to ensure there are no other unexpected // errors, so we let them fail the test})" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "To catch a single uncaught exception" } ] }, { "type": "code", "lang": null, "meta": null, "value": "it('is doing something very important', (done) => { // this event will automatically be unbound when this // test ends because it's attached to 'cy' cy.on('uncaught:exception', (err, runnable) => { expect(err.message).to.include('something about the error') // using mocha's async done callback to finish // this test so we prove that an uncaught exception // was thrown done() // return false to prevent the error from // failing this test return false }) // assume this causes an error cy.get('button').click()})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Catching Test Failures" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Debug the moment a test fails" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If you want to debug when any test fails you'll likely want to put this in a " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file", "children": [ { "type": "text", "value": "supportFile" } ] }, { "type": "text", "value": ", or at the top of an individual spec file." } ] }, { "type": "code", "lang": null, "meta": null, "value": "Cypress.on('fail', (error, runnable) => { debugger // we now have access to the err instance // and the mocha runnable this failed on throw error // throw error to have test still fail})it('calls the \"fail\" callback when this test fails', () => { // when this cy.get() fails the callback // is invoked with the error cy.get('element-that-does-not-exist')})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Page Navigation[" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "End-to-End Only" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "](/llm/markdown/app/core-concepts/testing-types.md#What-is-E2E-Testing)" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Test that your application was redirected" } ] }, { "type": "code", "lang": null, "meta": null, "value": "// app code$('button').on('click', (e) => { // change the page programmatically window.location.href = '/some/new/link'})// test codeit('redirects to another page on click', (done) => { // this event will automatically be unbound when this // test ends because it's attached to 'cy' cy.on('window:before:unload', (e) => { // no return value on the event expect(e.returnValue).to.be.undefined }) cy.on('window:unload', (e) => { // using mocha's async done callback to finish // this test so we are guaranteed the application // was unloaded while navigating to the new page done() }) // click the button causing the page redirect cy.get('button').click()})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Window Before Load[" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "End-to-End Only" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "](/llm/markdown/app/core-concepts/testing-types.md#What-is-E2E-Testing)" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Modify your Application before it loads after page transitions" } ] }, { "type": "code", "lang": null, "meta": null, "value": "it('can modify the window prior to page load on all pages', () => { // create the stub here const ga = cy.stub().as('ga') // prevent google analytics from loading // and replace it with a stub before every // single page load including all new page // navigations cy.on('window:before:load', (win) => { Object.defineProperty(win, 'ga', { configurable: false, get: () => ga, // always return the stub set: () => {}, // don't allow actual google analytics to overwrite this property }) }) cy // window:before:load will be called here .visit('/first/page') .then((win) => { // and here win.location.href = '/second/page' }) // and here cy.get('a').click()})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Window Confirm" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Control whether you accept or reject confirmations" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "This enables you to test how your application reacts to accepted confirmations and rejected confirmations." } ] }, { "type": "code", "lang": null, "meta": null, "value": "// app code$('button').on('click', (e) => { const one = confirm('first confirm') if (one) { const two = confirm('second confirm') if (!two) { const three = confirm('third confirm') confirm('third confirm was ' + three) } }})// test codeit('can control application confirms', (done) => { let count = 0 // make sure you bind to this **before** the // confirm method is called in your application // // this event will automatically be unbound when this // test ends because it's attached to 'cy' cy.on('window:confirm', (str) => { count += 1 switch (count) { case 1: expect(str).to.eq('first confirm') // returning nothing here automatically // accepts the confirmation case 2: expect(str).to.eq('second confirm') // reject the confirmation return false case 3: expect(str).to.eq('third confirm') // don't have to return true but it works // as well return true case 4: expect(str).to.eq('third confirm was true') // using mocha's async done callback to finish // this test so we are guaranteed everything // got to this point okay without throwing an error done() } }) // click the button causing the confirm to fire cy.get('button').click()})it('could also use a stub instead of imperative code', () => { const stub = cy.stub() // not necessary but showing for clarity stub.onFirstCall().returns(undefined) stub.onSecondCall().returns(false) stub.onThirdCall().returns(true) cy.on('window:confirm', stub) cy.get('button') .click() .then(() => { expect(stub.getCall(0)).to.be.calledWith('first confirm') expect(stub.getCall(1)).to.be.calledWith('second confirm') expect(stub.getCall(2)).to.be.calledWith('third confirm') expect(stub.getCall(3)).to.be.calledWith('third confirm was true') })})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Window Alert" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Assert on the alert text" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress automatically accepts alerts but you can still assert on the text content." } ] }, { "type": "code", "lang": null, "meta": null, "value": "// app code$('button').on('click', (e) => { alert('hi') alert('there') alert('friend')})it('can assert on the alert text content', () => { const stub = cy.stub() cy.on('window:alert', stub) cy.get('button') .click() .then(() => { expect(stub.getCall(0)).to.be.calledWith('hi') expect(stub.getCall(1)).to.be.calledWith('there') expect(stub.getCall(2)).to.be.calledWith('friend') })})" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Notes" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Logging All Events" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress uses the " }, { "type": "link", "title": null, "url": "https://github.com/visionmedia/debug", "children": [ { "type": "text", "value": "`debug`" } ] }, { "type": "text", "value": " node module for both the back end server process, and for everything running in the browser (called the driver)." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If you'd like to see (the huge) stream of events that Cypress emits you can pop open your Dev Tools and write this line in the console." } ] }, { "type": "code", "lang": null, "meta": null, "value": "localStorage.debug = 'cypress:*'" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Reload the browser and turn on 'Verbose' logs to see debug messages within the Developer Tools console." } ] } ] }, "token_estimate": 3751 }