Playwright · API reference · all subjects

events & listeners

34 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

What event is dispatched when a Dialog appears

When a Dialog appears (such as alert, prompt, confirm or beforeunload), the BrowserContext.dialog event is dispatched. The listener must either call Dialog.accept() or Dialog.dismiss() on the dialog, otherwise the page will freeze waiting for the dialog.

Frame class lifecycle events

The Frame object's lifecycle is controlled by three events dispatched on the page object: Page.frameAttached (fired when the frame gets attached to the page, which happens only once), Page.frameNavigated (fired when the frame commits navigation to a different URL), and Page.frameDetached (fired when the frame gets detached from the page, which happens only once).

Page.crash event

The Page class emits a 'crash' event with a Page argument when the page crashes, available since v1.8. Browser pages might crash if they try to allocate too much memory. When the page crashes, ongoing and subsequent operations will throw.

Page.dialog event dispatched when JavaScript dialog appears

The Page class emits a 'dialog' event with a Dialog argument when a JavaScript dialog appears, such as alert, prompt, confirm or beforeunload, available since v1.8. The listener must either accept or dismiss the dialog—otherwise the page will freeze waiting for the dialog, and actions like click will never finish. When no Page.dialog or BrowserContext.dialog listeners are present, all dialogs are automatically dismissed.

Page.dialogClosed event

The Page class emits a 'dialogClosed' event with a Dialog argument when a JavaScript dialog has been closed, either by Dialog.accept, by Dialog.dismiss, or manually by the user in the headed browser, available since v1.63.

Page.DOMContentLoaded event

The Page class emits a 'DOMContentLoaded' event with a Page argument when the JavaScript DOMContentLoaded event is dispatched, available since v1.9.

Page.download event

The Page class emits a 'download' event with a Download argument when attachment download started, available since v1.8. The user can access basic file operations on downloaded content via the passed Download instance.

Page.fileChooser event

The Page class emits a 'fileChooser' event with a FileChooser argument when a file chooser is supposed to appear, such as after clicking the <input type=file>, available since v1.9. Playwright can respond to it via setting the input files using FileChooser.setFiles.

Page.frameAttached event

The Page class emits a 'frameAttached' event with a Frame argument when a frame is attached, available since v1.9.

Page.frameDetached event

The Page class emits a 'frameDetached' event with a Frame argument when a frame is detached, available since v1.9.

Page.frameNavigated event

The Page class emits a 'frameNavigated' event with a Frame argument when a frame is navigated to a new url, available since v1.9.

Page.load event

The Page class emits a 'load' event with a Page argument when the JavaScript load event is dispatched, available since v1.8.

Page.pageError event

The Page class emits a 'pageError' event when an uncaught exception happens within the page, available since v1.9. For JavaScript and Python, the argument is of type Error. For C# and Java, the argument is of type string.

Page.popup event

The Page class emits a 'popup' event with a Page argument when the page opens a new tab or window, available since v1.8. This event is emitted in addition to BrowserContext.page, but only for popups relevant to this page. The earliest moment that page is available is when it has navigated to the initial url.

Page.request event

The Page class emits a 'request' event with a Request argument when a page issues a request, available since v1.8. The request object is read-only. To intercept and mutate requests, use Page.route or BrowserContext.route.

Page.requestFailed event

The Page class emits a 'requestFailed' event with a Request argument when a request fails, for example by timing out, available since v1.9. HTTP Error responses such as 404 or 503 are still successful responses from HTTP standpoint, so request will complete with Page.requestFinished event and not with Page.requestFailed. A request will only be considered failed when the client cannot get an HTTP response from the server, e.g. due to network error net::ERR_FAILED.

Page.requestFinished event

The Page class emits a 'requestFinished' event with a Request argument when a request finishes successfully after downloading the response body, available since v1.9. For a successful response, the sequence of events is request, response and requestFinished.

Page.response event

The Page class emits a 'response' event with a Response argument when response status and headers are received for a request, available since v1.8. For a successful response, the sequence of events is request, response and requestFinished.

Page.webSocket event

The Page class emits a 'webSocket' event with a WebSocket argument when WebSocket request is sent, available since v1.9.

Page.worker event

The Page class emits a 'worker' event with a Worker argument when a dedicated WebWorker is spawned by the page, available since v1.8.

Page event listener example - listen for load event

Example showing how to listen for a single page load event: page.once('load', () => console.log('Page loaded!')). The Page class emits various events that can be handled using Node's native EventEmitter methods like on, once, or removeListener.

Page event listener removal example - removeListener

Example showing how to remove an event listener from a page. Define a handler function, add it with page.on('request', logRequest), and remove it later with page.removeListener('request', logRequest).

Page.console event handler example

Example showing how to log console messages from the page. Use page.on('console', async msg => { ... }) to handle console events. Access the arguments passed to console.log via msg.args(), which is an array of JSHandle objects. Call arg.jsonValue() to get the actual values.

Page.crash event handling example

Example showing how to handle page crashes. Wrap page operations in a try-catch block. When the page crashes, the exception message will contain 'crash'. This can happen during page.click() or page.waitForEvent().

Page.dialog event handler example

Example showing how to handle dialog events. Use page.on('dialog', dialog => dialog.accept()) to automatically accept dialogs. The listener must either accept or dismiss the dialog.

Page.fileChooser event handler example

Example showing how to handle file chooser events. Use page.on('filechooser', async fileChooser => { await fileChooser.setFiles(path.join(__dirname, '/tmp/myfile.pdf')); }). This allows setting files to be uploaded after a file chooser appears.

Page.pageError event handler example

Example showing how to log uncaught exceptions. Use page.on('pageerror', exception => { console.log(`Uncaught exception: "${exception}"`); }). This logs all uncaught exceptions that happen within the page.

Page.popup event handler example

Example showing how to wait for and handle popup windows. Use const popupPromise = page.waitForEvent('popup') before clicking, then await the promise to get the popup page. This ensures the popup is captured even if it opens before the listener is fully set up.

Page.requestFailed event handler example

Example showing how to handle failed requests. Use page.on('requestfailed', request => { console.log(request.url() + ' ' + request.failure().errorText); }). Access the URL and failure details from the request object.

Page.onceDialog method for Java

Page.onceDialog adds a one-off Dialog handler that is removed immediately after the next Dialog is created. Takes handler parameter (function receiving Dialog object). The handler must either call Dialog.accept or Dialog.dismiss, otherwise the page will freeze. Available since v1.10 for Java.

Page.removeAllListeners async method for JavaScript

Page.removeAllListeners removes all listeners of the given type, or all registered listeners if no type given. It allows waiting for async listeners to complete or ignoring subsequent errors. Available since v1.47 for JavaScript.

Page.close event

The Page class emits a 'close' event with a Page argument when the page closes, available since v1.8.

Page.removeAllListeners parameters and options

Page.removeAllListeners takes optional type parameter (string - listener type), and option behavior (controls wait behavior for async listeners).

Page.console event

The Page class emits a 'console' event with a ConsoleMessage argument when JavaScript within the page calls console API methods like console.log or console.dir, available since v1.8. In Java, this event is aliased as consoleMessage.

Give your agent this brain