From 782c1d487327f69aea3cbab769d5270a77578b4a Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Mon, 6 Jul 2020 12:23:40 +0100 Subject: [PATCH] chore(docs): define events enum for `Browser` (#6165) --- new-docs/puppeteer.browser.md | 2 + new-docs/puppeteer.browseremittedevents.md | 23 ++++++++ new-docs/puppeteer.md | 1 + src/common/Browser.ts | 69 +++++++++++++++++++--- 4 files changed, 87 insertions(+), 8 deletions(-) create mode 100644 new-docs/puppeteer.browseremittedevents.md diff --git a/new-docs/puppeteer.browser.md b/new-docs/puppeteer.browser.md index 13accc2a..7e93c935 100644 --- a/new-docs/puppeteer.browser.md +++ b/new-docs/puppeteer.browser.md @@ -15,6 +15,8 @@ export declare class Browser extends EventEmitter ## Remarks +The Browser class extends from Puppeteer's [EventEmitter](./puppeteer.eventemitter.md) class and will emit various events which are documented in the [BrowserEmittedEvents](./puppeteer.browseremittedevents.md) enum. + The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Browser` class. ## Example 1 diff --git a/new-docs/puppeteer.browseremittedevents.md b/new-docs/puppeteer.browseremittedevents.md new file mode 100644 index 00000000..1a8feaf8 --- /dev/null +++ b/new-docs/puppeteer.browseremittedevents.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BrowserEmittedEvents](./puppeteer.browseremittedevents.md) + +## BrowserEmittedEvents enum + +All the events a [browser instance](./puppeteer.browser.md) may emit. + +Signature: + +```typescript +export declare const enum BrowserEmittedEvents +``` + +## Enumeration Members + +| Member | Value | Description | +| --- | --- | --- | +| Disconnected | "disconnected" | Emitted when Puppeteer gets disconnected from the Chromium instance. This might happen because of one of the following:- Chromium is closed or crashed- The [browser.disconnect](./puppeteer.browser.disconnect.md) method was called. | +| TargetChanged | "targetchanged" | Emitted when the url of a target changes. Contains a [Target](./puppeteer.target.md) instance. | +| TargetCreated | "targetcreated" | Emitted when a target is created, for example when a new page is opened by [window.open](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) or by [browser.newPage](./puppeteer.browser.newpage.md)Contains a [Target](./puppeteer.target.md) instance. | +| TargetDestroyed | "targetdestroyed" | Emitted when a target is destroyed, for example when a page is closed. Contains a [Target](./puppeteer.target.md) instance. | + diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 64bee969..99574354 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -40,6 +40,7 @@ | Enumeration | Description | | --- | --- | +| [BrowserEmittedEvents](./puppeteer.browseremittedevents.md) | All the events a [browser instance](./puppeteer.browser.md) may emit. | | [PageEmittedEvents](./puppeteer.pageemittedevents.md) | All the events that a page instance may emit. | ## Interfaces diff --git a/src/common/Browser.ts b/src/common/Browser.ts index 05fc859d..f82ea91a 100644 --- a/src/common/Browser.ts +++ b/src/common/Browser.ts @@ -38,10 +38,63 @@ export interface WaitForTargetOptions { timeout?: number; } +/** + * All the events a {@link Browser | browser instance} may emit. + * + * @public + */ +export const enum BrowserEmittedEvents { + /** + * Emitted when Puppeteer gets disconnected from the Chromium instance. This + * might happen because of one of the following: + * + * - Chromium is closed or crashed + * + * - The {@link Browser.disconnect | browser.disconnect } method was called. + */ + Disconnected = 'disconnected', + + /** + * Emitted when the url of a target changes. Contains a {@link Target} instance. + * + * @remarks + * + * Note that this includes target changes in incognito browser contexts. + */ + TargetChanged = 'targetchanged', + + /** + * Emitted when a target is created, for example when a new page is opened by + * {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/open | window.open} + * or by {@link Browser.newPage | browser.newPage} + * + * Contains a {@link Target} instance. + * + * @remarks + * + * Note that this includes target creations in incognito browser contexts. + */ + TargetCreated = 'targetcreated', + /** + * Emitted when a target is destroyed, for example when a page is closed. + * Contains a {@link Target} instance. + * + * @remarks + * + * Note that this includes target destructions in incognito browser contexts. + */ + TargetDestroyed = 'targetdestroyed', +} + /** * A Browser is created when Puppeteer connects to a Chromium instance, either through * {@link Puppeteer.launch} or {@link Puppeteer.connect}. * + * @remarks + * + * The Browser class extends from Puppeteer's {@link EventEmitter} class and will + * emit various events which are documented in the {@link BrowserEmittedEvents} enum. + * * @example * * An example of using a {@link Browser} to create a {@link Page}: @@ -142,7 +195,7 @@ export class Browser extends EventEmitter { this._targets = new Map(); this._connection.on(Events.Connection.Disconnected, () => - this.emit(Events.Browser.Disconnected) + this.emit(BrowserEmittedEvents.Disconnected) ); this._connection.on('Target.targetCreated', this._targetCreated.bind(this)); this._connection.on( @@ -243,7 +296,7 @@ export class Browser extends EventEmitter { this._targets.set(event.targetInfo.targetId, target); if (await target._initializedPromise) { - this.emit(Events.Browser.TargetCreated, target); + this.emit(BrowserEmittedEvents.TargetCreated, target); context.emit(Events.BrowserContext.TargetCreated, target); } } @@ -254,7 +307,7 @@ export class Browser extends EventEmitter { this._targets.delete(event.targetId); target._closedCallback(); if (await target._initializedPromise) { - this.emit(Events.Browser.TargetDestroyed, target); + this.emit(BrowserEmittedEvents.TargetDestroyed, target); target .browserContext() .emit(Events.BrowserContext.TargetDestroyed, target); @@ -270,7 +323,7 @@ export class Browser extends EventEmitter { const wasInitialized = target._isInitialized; target._targetInfoChanged(event.targetInfo); if (wasInitialized && previousURL !== target.url()) { - this.emit(Events.Browser.TargetChanged, target); + this.emit(BrowserEmittedEvents.TargetChanged, target); target.browserContext().emit(Events.BrowserContext.TargetChanged, target); } } @@ -361,8 +414,8 @@ export class Browser extends EventEmitter { if (existingTarget) return existingTarget; let resolve; const targetPromise = new Promise((x) => (resolve = x)); - this.on(Events.Browser.TargetCreated, check); - this.on(Events.Browser.TargetChanged, check); + this.on(BrowserEmittedEvents.TargetCreated, check); + this.on(BrowserEmittedEvents.TargetChanged, check); try { if (!timeout) return await targetPromise; return await helper.waitWithTimeout( @@ -371,8 +424,8 @@ export class Browser extends EventEmitter { timeout ); } finally { - this.removeListener(Events.Browser.TargetCreated, check); - this.removeListener(Events.Browser.TargetChanged, check); + this.removeListener(BrowserEmittedEvents.TargetCreated, check); + this.removeListener(BrowserEmittedEvents.TargetChanged, check); } function check(target: Target): void {