chore(docs): define events enum for Browser (#6165)

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<Target>((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<Target>(
@@ -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 {