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

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

new-docs/puppeteer.browseremittedevents.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BrowserEmittedEvents](./puppeteer.browseremittedevents.md)
+
+## BrowserEmittedEvents enum
+
+All the events a [browser instance](./puppeteer.browser.md) may emit.
+
+<b>Signature:</b>
+
+```typescript
+export declare const enum BrowserEmittedEvents 
+```
+
+## Enumeration Members
+
+|  Member | Value | Description |
+|  --- | --- | --- |
+|  Disconnected | <code>&quot;disconnected&quot;</code> | 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 | <code>&quot;targetchanged&quot;</code> | Emitted when the url of a target changes. Contains a [Target](./puppeteer.target.md) instance. |
+|  TargetCreated | <code>&quot;targetcreated&quot;</code> | 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 | <code>&quot;targetdestroyed&quot;</code> | Emitted when a target is destroyed, for example when a page is closed. Contains a [Target](./puppeteer.target.md) instance. |
+

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

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 {