diff --git a/new-docs/puppeteer.browser._closecallback.md b/new-docs/puppeteer.browser._closecallback.md deleted file mode 100644 index bd2ea2d4a0e..00000000000 --- a/new-docs/puppeteer.browser._closecallback.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_closeCallback](./puppeteer.browser._closecallback.md) - -## Browser.\_closeCallback property - -Signature: - -```typescript -_closeCallback: BrowserCloseCallback; -``` diff --git a/new-docs/puppeteer.browser._connection.md b/new-docs/puppeteer.browser._connection.md deleted file mode 100644 index d5276e720e2..00000000000 --- a/new-docs/puppeteer.browser._connection.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_connection](./puppeteer.browser._connection.md) - -## Browser.\_connection property - -Signature: - -```typescript -_connection: Connection; -``` diff --git a/new-docs/puppeteer.browser._constructor_.md b/new-docs/puppeteer.browser._constructor_.md deleted file mode 100644 index c6c556928fb..00000000000 --- a/new-docs/puppeteer.browser._constructor_.md +++ /dev/null @@ -1,25 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [(constructor)](./puppeteer.browser._constructor_.md) - -## Browser.(constructor) - -Constructs a new instance of the `Browser` class - -Signature: - -```typescript -constructor(connection: Connection, contextIds: string[], ignoreHTTPSErrors: boolean, defaultViewport?: Viewport, process?: ChildProcess, closeCallback?: BrowserCloseCallback); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| connection | [Connection](./puppeteer.connection.md) | | -| contextIds | string\[\] | | -| ignoreHTTPSErrors | boolean | | -| defaultViewport | Viewport | | -| process | ChildProcess | | -| closeCallback | BrowserCloseCallback | | - diff --git a/new-docs/puppeteer.browser._contexts.md b/new-docs/puppeteer.browser._contexts.md deleted file mode 100644 index 6a1cde679a9..00000000000 --- a/new-docs/puppeteer.browser._contexts.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_contexts](./puppeteer.browser._contexts.md) - -## Browser.\_contexts property - -Signature: - -```typescript -_contexts: Map; -``` diff --git a/new-docs/puppeteer.browser._createpageincontext.md b/new-docs/puppeteer.browser._createpageincontext.md deleted file mode 100644 index ad5848d12dd..00000000000 --- a/new-docs/puppeteer.browser._createpageincontext.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_createPageInContext](./puppeteer.browser._createpageincontext.md) - -## Browser.\_createPageInContext() method - -Signature: - -```typescript -_createPageInContext(contextId?: string): Promise; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| contextId | string | | - -Returns: - -Promise<[Page](./puppeteer.page.md)> - diff --git a/new-docs/puppeteer.browser._defaultcontext.md b/new-docs/puppeteer.browser._defaultcontext.md deleted file mode 100644 index 46ae76abdf4..00000000000 --- a/new-docs/puppeteer.browser._defaultcontext.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_defaultContext](./puppeteer.browser._defaultcontext.md) - -## Browser.\_defaultContext property - -Signature: - -```typescript -_defaultContext: BrowserContext; -``` diff --git a/new-docs/puppeteer.browser._defaultviewport.md b/new-docs/puppeteer.browser._defaultviewport.md deleted file mode 100644 index 6495f7261b8..00000000000 --- a/new-docs/puppeteer.browser._defaultviewport.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_defaultViewport](./puppeteer.browser._defaultviewport.md) - -## Browser.\_defaultViewport property - -Signature: - -```typescript -_defaultViewport?: Viewport; -``` diff --git a/new-docs/puppeteer.browser._disposecontext.md b/new-docs/puppeteer.browser._disposecontext.md deleted file mode 100644 index 5268a1fdab0..00000000000 --- a/new-docs/puppeteer.browser._disposecontext.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_disposeContext](./puppeteer.browser._disposecontext.md) - -## Browser.\_disposeContext() method - -Signature: - -```typescript -_disposeContext(contextId?: string): Promise; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| contextId | string | | - -Returns: - -Promise<void> - diff --git a/new-docs/puppeteer.browser._getversion.md b/new-docs/puppeteer.browser._getversion.md deleted file mode 100644 index e9d29e39cb2..00000000000 --- a/new-docs/puppeteer.browser._getversion.md +++ /dev/null @@ -1,15 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_getVersion](./puppeteer.browser._getversion.md) - -## Browser.\_getVersion() method - -Signature: - -```typescript -_getVersion(): Promise; -``` -Returns: - -Promise<Protocol.Browser.getVersionReturnValue> - diff --git a/new-docs/puppeteer.browser._ignorehttpserrors.md b/new-docs/puppeteer.browser._ignorehttpserrors.md deleted file mode 100644 index f32cfb41d66..00000000000 --- a/new-docs/puppeteer.browser._ignorehttpserrors.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_ignoreHTTPSErrors](./puppeteer.browser._ignorehttpserrors.md) - -## Browser.\_ignoreHTTPSErrors property - -Signature: - -```typescript -_ignoreHTTPSErrors: boolean; -``` diff --git a/new-docs/puppeteer.browser._process.md b/new-docs/puppeteer.browser._process.md deleted file mode 100644 index bda68890ea1..00000000000 --- a/new-docs/puppeteer.browser._process.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_process](./puppeteer.browser._process.md) - -## Browser.\_process property - -Signature: - -```typescript -_process?: ChildProcess; -``` diff --git a/new-docs/puppeteer.browser._targetcreated.md b/new-docs/puppeteer.browser._targetcreated.md deleted file mode 100644 index c69a464f637..00000000000 --- a/new-docs/puppeteer.browser._targetcreated.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_targetCreated](./puppeteer.browser._targetcreated.md) - -## Browser.\_targetCreated() method - -Signature: - -```typescript -_targetCreated(event: Protocol.Target.targetCreatedPayload): Promise; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| event | Protocol.Target.targetCreatedPayload | | - -Returns: - -Promise<void> - diff --git a/new-docs/puppeteer.browser._targetdestroyed.md b/new-docs/puppeteer.browser._targetdestroyed.md deleted file mode 100644 index 59b72e52326..00000000000 --- a/new-docs/puppeteer.browser._targetdestroyed.md +++ /dev/null @@ -1,24 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_targetDestroyed](./puppeteer.browser._targetdestroyed.md) - -## Browser.\_targetDestroyed() method - -Signature: - -```typescript -_targetDestroyed(event: { - targetId: string; - }): Promise; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| event | { targetId: string; } | | - -Returns: - -Promise<void> - diff --git a/new-docs/puppeteer.browser._targetinfochanged.md b/new-docs/puppeteer.browser._targetinfochanged.md deleted file mode 100644 index b2469edaa5b..00000000000 --- a/new-docs/puppeteer.browser._targetinfochanged.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_targetInfoChanged](./puppeteer.browser._targetinfochanged.md) - -## Browser.\_targetInfoChanged() method - -Signature: - -```typescript -_targetInfoChanged(event: Protocol.Target.targetInfoChangedPayload): void; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| event | Protocol.Target.targetInfoChangedPayload | | - -Returns: - -void - diff --git a/new-docs/puppeteer.browser._targets.md b/new-docs/puppeteer.browser._targets.md deleted file mode 100644 index 97d7b2bd182..00000000000 --- a/new-docs/puppeteer.browser._targets.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [\_targets](./puppeteer.browser._targets.md) - -## Browser.\_targets property - -Signature: - -```typescript -_targets: Map; -``` diff --git a/new-docs/puppeteer.browser.browsercontexts.md b/new-docs/puppeteer.browser.browsercontexts.md index 0928f7585ac..309170eab08 100644 --- a/new-docs/puppeteer.browser.browsercontexts.md +++ b/new-docs/puppeteer.browser.browsercontexts.md @@ -4,6 +4,8 @@ ## Browser.browserContexts() method +Returns an array of all open browser contexts. In a newly created browser, this will return a single instance of [BrowserContext](./puppeteer.browsercontext.md). + Signature: ```typescript diff --git a/new-docs/puppeteer.browser.close.md b/new-docs/puppeteer.browser.close.md index 67c9289f9fa..714dd1f882f 100644 --- a/new-docs/puppeteer.browser.close.md +++ b/new-docs/puppeteer.browser.close.md @@ -4,6 +4,8 @@ ## Browser.close() method +Closes Chromium and all of its pages (if any were opened). The [Browser](./puppeteer.browser.md) object itself is considered to be disposed and cannot be used anymore. + Signature: ```typescript diff --git a/new-docs/puppeteer.browser.create.md b/new-docs/puppeteer.browser.create.md deleted file mode 100644 index 0774e2ffccc..00000000000 --- a/new-docs/puppeteer.browser.create.md +++ /dev/null @@ -1,27 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Browser](./puppeteer.browser.md) > [create](./puppeteer.browser.create.md) - -## Browser.create() method - -Signature: - -```typescript -static create(connection: Connection, contextIds: string[], ignoreHTTPSErrors: boolean, defaultViewport?: Viewport, process?: ChildProcess, closeCallback?: BrowserCloseCallback): Promise; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| connection | [Connection](./puppeteer.connection.md) | | -| contextIds | string\[\] | | -| ignoreHTTPSErrors | boolean | | -| defaultViewport | Viewport | | -| process | ChildProcess | | -| closeCallback | BrowserCloseCallback | | - -Returns: - -Promise<[Browser](./puppeteer.browser.md)> - diff --git a/new-docs/puppeteer.browser.createincognitobrowsercontext.md b/new-docs/puppeteer.browser.createincognitobrowsercontext.md index bc7349cede0..93b9f963625 100644 --- a/new-docs/puppeteer.browser.createincognitobrowsercontext.md +++ b/new-docs/puppeteer.browser.createincognitobrowsercontext.md @@ -4,6 +4,8 @@ ## Browser.createIncognitoBrowserContext() method +Creates a new incognito browser context. This won't share cookies/cache with other browser contexts. + Signature: ```typescript @@ -13,3 +15,19 @@ createIncognitoBrowserContext(): Promise; Promise<[BrowserContext](./puppeteer.browsercontext.md)> +## Example + + +```js +(async () => { + const browser = await puppeteer.launch(); + // Create a new incognito browser context. + const context = await browser.createIncognitoBrowserContext(); + // Create a new page in a pristine context. + const page = await context.newPage(); + // Do stuff + await page.goto('https://example.com'); +})(); + +``` + diff --git a/new-docs/puppeteer.browser.defaultbrowsercontext.md b/new-docs/puppeteer.browser.defaultbrowsercontext.md index 2c89a3f13c2..88dba1c6c64 100644 --- a/new-docs/puppeteer.browser.defaultbrowsercontext.md +++ b/new-docs/puppeteer.browser.defaultbrowsercontext.md @@ -4,6 +4,8 @@ ## Browser.defaultBrowserContext() method +Returns the default browser context. The default browser context cannot be closed. + Signature: ```typescript diff --git a/new-docs/puppeteer.browser.disconnect.md b/new-docs/puppeteer.browser.disconnect.md index 56e9d73ec5e..1382226c8d0 100644 --- a/new-docs/puppeteer.browser.disconnect.md +++ b/new-docs/puppeteer.browser.disconnect.md @@ -4,6 +4,8 @@ ## Browser.disconnect() method +Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling `disconnect`, the [Browser](./puppeteer.browser.md) object is considered disposed and cannot be used anymore. + Signature: ```typescript diff --git a/new-docs/puppeteer.browser.isconnected.md b/new-docs/puppeteer.browser.isconnected.md index 6e5dfd212bc..987adae7bfe 100644 --- a/new-docs/puppeteer.browser.isconnected.md +++ b/new-docs/puppeteer.browser.isconnected.md @@ -4,6 +4,8 @@ ## Browser.isConnected() method +Indicates that the browser is connected. + Signature: ```typescript diff --git a/new-docs/puppeteer.browser.md b/new-docs/puppeteer.browser.md index 4c669ee5802..13accc2a7c3 100644 --- a/new-docs/puppeteer.browser.md +++ b/new-docs/puppeteer.browser.md @@ -4,6 +4,8 @@ ## Browser class +A Browser is created when Puppeteer connects to a Chromium instance, either through [Puppeteer.launch()](./puppeteer.puppeteer.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). + Signature: ```typescript @@ -11,49 +13,65 @@ export declare class Browser extends EventEmitter ``` Extends: [EventEmitter](./puppeteer.eventemitter.md) -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(connection, contextIds, ignoreHTTPSErrors, defaultViewport, process, closeCallback)](./puppeteer.browser._constructor_.md) | | Constructs a new instance of the Browser class | +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. -## Properties +## Example 1 -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [\_closeCallback](./puppeteer.browser._closecallback.md) | | BrowserCloseCallback | | -| [\_connection](./puppeteer.browser._connection.md) | | [Connection](./puppeteer.connection.md) | | -| [\_contexts](./puppeteer.browser._contexts.md) | | Map<string, [BrowserContext](./puppeteer.browsercontext.md)> | | -| [\_defaultContext](./puppeteer.browser._defaultcontext.md) | | [BrowserContext](./puppeteer.browsercontext.md) | | -| [\_defaultViewport](./puppeteer.browser._defaultviewport.md) | | Viewport | | -| [\_ignoreHTTPSErrors](./puppeteer.browser._ignorehttpserrors.md) | | boolean | | -| [\_process](./puppeteer.browser._process.md) | | ChildProcess | | -| [\_targets](./puppeteer.browser._targets.md) | | Map<string, [Target](./puppeteer.target.md)> | | +An example of using a [Browser](./puppeteer.browser.md) to create a [Page](./puppeteer.page.md): + +```js +const puppeteer = require('puppeteer'); + +(async () => { + const browser = await puppeteer.launch(); + const page = await browser.newPage(); + await page.goto('https://example.com'); + await browser.close(); +})(); + +``` + +## Example 2 + +An example of disconnecting from and reconnecting to a [Browser](./puppeteer.browser.md): + +```js +const puppeteer = require('puppeteer'); + +(async () => { + const browser = await puppeteer.launch(); + // Store the endpoint to be able to reconnect to Chromium + const browserWSEndpoint = browser.wsEndpoint(); + // Disconnect puppeteer from Chromium + browser.disconnect(); + + // Use the endpoint to reestablish a connection + const browser2 = await puppeteer.connect({browserWSEndpoint}); + // Close Chromium + await browser2.close(); +})(); + +``` ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [\_createPageInContext(contextId)](./puppeteer.browser._createpageincontext.md) | | | -| [\_disposeContext(contextId)](./puppeteer.browser._disposecontext.md) | | | -| [\_getVersion()](./puppeteer.browser._getversion.md) | | | -| [\_targetCreated(event)](./puppeteer.browser._targetcreated.md) | | | -| [\_targetDestroyed(event)](./puppeteer.browser._targetdestroyed.md) | | | -| [\_targetInfoChanged(event)](./puppeteer.browser._targetinfochanged.md) | | | -| [browserContexts()](./puppeteer.browser.browsercontexts.md) | | | -| [close()](./puppeteer.browser.close.md) | | | -| [create(connection, contextIds, ignoreHTTPSErrors, defaultViewport, process, closeCallback)](./puppeteer.browser.create.md) | static | | -| [createIncognitoBrowserContext()](./puppeteer.browser.createincognitobrowsercontext.md) | | | -| [defaultBrowserContext()](./puppeteer.browser.defaultbrowsercontext.md) | | | -| [disconnect()](./puppeteer.browser.disconnect.md) | | | -| [isConnected()](./puppeteer.browser.isconnected.md) | | | -| [newPage()](./puppeteer.browser.newpage.md) | | | -| [pages()](./puppeteer.browser.pages.md) | | | -| [process()](./puppeteer.browser.process.md) | | | -| [target()](./puppeteer.browser.target.md) | | | -| [targets()](./puppeteer.browser.targets.md) | | | -| [userAgent()](./puppeteer.browser.useragent.md) | | | -| [version()](./puppeteer.browser.version.md) | | | -| [waitForTarget(predicate, options)](./puppeteer.browser.waitfortarget.md) | | | -| [wsEndpoint()](./puppeteer.browser.wsendpoint.md) | | | +| [browserContexts()](./puppeteer.browser.browsercontexts.md) | | Returns an array of all open browser contexts. In a newly created browser, this will return a single instance of [BrowserContext](./puppeteer.browsercontext.md). | +| [close()](./puppeteer.browser.close.md) | | Closes Chromium and all of its pages (if any were opened). The [Browser](./puppeteer.browser.md) object itself is considered to be disposed and cannot be used anymore. | +| [createIncognitoBrowserContext()](./puppeteer.browser.createincognitobrowsercontext.md) | | Creates a new incognito browser context. This won't share cookies/cache with other browser contexts. | +| [defaultBrowserContext()](./puppeteer.browser.defaultbrowsercontext.md) | | Returns the default browser context. The default browser context cannot be closed. | +| [disconnect()](./puppeteer.browser.disconnect.md) | | Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling disconnect, the [Browser](./puppeteer.browser.md) object is considered disposed and cannot be used anymore. | +| [isConnected()](./puppeteer.browser.isconnected.md) | | Indicates that the browser is connected. | +| [newPage()](./puppeteer.browser.newpage.md) | | Creates a [Page](./puppeteer.page.md) in the default browser context. | +| [pages()](./puppeteer.browser.pages.md) | | An array of all open pages inside the Browser. | +| [process()](./puppeteer.browser.process.md) | | The spawned browser process. Returns null if the browser instance was created with [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | +| [target()](./puppeteer.browser.target.md) | | The target associated with the browser. | +| [targets()](./puppeteer.browser.targets.md) | | All active targets inside the Browser. In case of multiple browser contexts, returns an array with all the targets in all browser contexts. | +| [userAgent()](./puppeteer.browser.useragent.md) | | The browser's original user agent. Pages can override the browser user agent with [Page.setUserAgent()](./puppeteer.page.setuseragent.md). | +| [version()](./puppeteer.browser.version.md) | | A string representing the browser name and version. | +| [waitForTarget(predicate, options)](./puppeteer.browser.waitfortarget.md) | | Searches for a target in all browser contexts. | +| [wsEndpoint()](./puppeteer.browser.wsendpoint.md) | | The browser websocket endpoint which can be used as an argument to [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | diff --git a/new-docs/puppeteer.browser.newpage.md b/new-docs/puppeteer.browser.newpage.md index 3a17599b57a..9b695fe2667 100644 --- a/new-docs/puppeteer.browser.newpage.md +++ b/new-docs/puppeteer.browser.newpage.md @@ -4,6 +4,8 @@ ## Browser.newPage() method +Creates a [Page](./puppeteer.page.md) in the default browser context. + Signature: ```typescript diff --git a/new-docs/puppeteer.browser.pages.md b/new-docs/puppeteer.browser.pages.md index a1632c90446..ea86a7f4032 100644 --- a/new-docs/puppeteer.browser.pages.md +++ b/new-docs/puppeteer.browser.pages.md @@ -4,6 +4,8 @@ ## Browser.pages() method +An array of all open pages inside the Browser. + Signature: ```typescript @@ -13,3 +15,7 @@ pages(): Promise; Promise<[Page](./puppeteer.page.md)\[\]> +## Remarks + +In case of multiple browser contexts, returns an array with all the pages in all browser contexts. Non-visible pages, such as `"background_page"`, will not be listed here. You can find them using [Target.page()](./puppeteer.target.page.md). + diff --git a/new-docs/puppeteer.browser.process.md b/new-docs/puppeteer.browser.process.md index 39efa143fd0..ae112dc170c 100644 --- a/new-docs/puppeteer.browser.process.md +++ b/new-docs/puppeteer.browser.process.md @@ -4,6 +4,8 @@ ## Browser.process() method +The spawned browser process. Returns `null` if the browser instance was created with [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). + Signature: ```typescript diff --git a/new-docs/puppeteer.browser.target.md b/new-docs/puppeteer.browser.target.md index 399cdcfe280..2bc6f43eedb 100644 --- a/new-docs/puppeteer.browser.target.md +++ b/new-docs/puppeteer.browser.target.md @@ -4,6 +4,8 @@ ## Browser.target() method +The target associated with the browser. + Signature: ```typescript diff --git a/new-docs/puppeteer.browser.targets.md b/new-docs/puppeteer.browser.targets.md index ac514b2d248..c823ffeddca 100644 --- a/new-docs/puppeteer.browser.targets.md +++ b/new-docs/puppeteer.browser.targets.md @@ -4,6 +4,8 @@ ## Browser.targets() method +All active targets inside the Browser. In case of multiple browser contexts, returns an array with all the targets in all browser contexts. + Signature: ```typescript diff --git a/new-docs/puppeteer.browser.useragent.md b/new-docs/puppeteer.browser.useragent.md index 9f1f852606b..a93a98ffac8 100644 --- a/new-docs/puppeteer.browser.useragent.md +++ b/new-docs/puppeteer.browser.useragent.md @@ -4,6 +4,8 @@ ## Browser.userAgent() method +The browser's original user agent. Pages can override the browser user agent with [Page.setUserAgent()](./puppeteer.page.setuseragent.md). + Signature: ```typescript diff --git a/new-docs/puppeteer.browser.version.md b/new-docs/puppeteer.browser.version.md index 069c2af31f9..9570f3fc0c4 100644 --- a/new-docs/puppeteer.browser.version.md +++ b/new-docs/puppeteer.browser.version.md @@ -4,6 +4,8 @@ ## Browser.version() method +A string representing the browser name and version. + Signature: ```typescript @@ -13,3 +15,9 @@ version(): Promise; Promise<string> +## Remarks + +For headless Chromium, this is similar to `HeadlessChrome/61.0.3153.0`. For non-headless, this is similar to `Chrome/61.0.3153.0`. + +The format of browser.version() might change with future releases of Chromium. + diff --git a/new-docs/puppeteer.browser.waitfortarget.md b/new-docs/puppeteer.browser.waitfortarget.md index 0cea9e3dec4..15d2806fad6 100644 --- a/new-docs/puppeteer.browser.waitfortarget.md +++ b/new-docs/puppeteer.browser.waitfortarget.md @@ -4,24 +4,34 @@ ## Browser.waitForTarget() method +Searches for a target in all browser contexts. + Signature: ```typescript -waitForTarget(predicate: (x: Target) => boolean, options?: { - timeout?: number; - }): Promise; +waitForTarget(predicate: (x: Target) => boolean, options?: WaitForTargetOptions): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| predicate | (x: [Target](./puppeteer.target.md)) => boolean | | -| options | { timeout?: number; } | | +| predicate | (x: [Target](./puppeteer.target.md)) => boolean | A function to be run for every target. | +| options | [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | | Returns: Promise<[Target](./puppeteer.target.md)> -{!Promise<!Target>} +The first target found that matches the `predicate` function. + +## Example + +An example of finding a target for a page opened via `window.open`: + +```js +await page.evaluate(() => window.open('https://www.example.com/')); +const newWindowTarget = await browser.waitForTarget(target => target.url() === 'https://www.example.com/'); + +``` diff --git a/new-docs/puppeteer.browser.wsendpoint.md b/new-docs/puppeteer.browser.wsendpoint.md index 349e6e5ac76..670c2cef7bd 100644 --- a/new-docs/puppeteer.browser.wsendpoint.md +++ b/new-docs/puppeteer.browser.wsendpoint.md @@ -4,6 +4,8 @@ ## Browser.wsEndpoint() method +The browser websocket endpoint which can be used as an argument to [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). + Signature: ```typescript @@ -13,3 +15,11 @@ wsEndpoint(): string; string +The Browser websocket url. + +## Remarks + +The format is `ws://${host}:${port}/devtools/browser/`. + +You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/version`. Learn more about the [devtools protocol](https://chromedevtools.github.io/devtools-protocol) and the [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target). + diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index df7b96fba7f..706a89e11b2 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -9,7 +9,7 @@ | Class | Description | | --- | --- | | [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access). | -| [Browser](./puppeteer.browser.md) | | +| [Browser](./puppeteer.browser.md) | A Browser is created when Puppeteer connects to a Chromium instance, either through [Puppeteer.launch()](./puppeteer.puppeteer.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | | [BrowserContext](./puppeteer.browsercontext.md) | | | [BrowserFetcher](./puppeteer.browserfetcher.md) | | | [CDPSession](./puppeteer.cdpsession.md) | The CDPSession instances are used to talk raw Chrome Devtools Protocol. | @@ -56,6 +56,7 @@ | [PressOptions](./puppeteer.pressoptions.md) | | | [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. | | [SnapshotOptions](./puppeteer.snapshotoptions.md) | | +| [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | | ## Variables diff --git a/new-docs/puppeteer.waitfortargetoptions.md b/new-docs/puppeteer.waitfortargetoptions.md new file mode 100644 index 00000000000..dbb9f455a7f --- /dev/null +++ b/new-docs/puppeteer.waitfortargetoptions.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) + +## WaitForTargetOptions interface + + +Signature: + +```typescript +export interface WaitForTargetOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [timeout](./puppeteer.waitfortargetoptions.timeout.md) | number | Maximum wait time in milliseconds. Pass 0 to disable the timeout. | + diff --git a/new-docs/puppeteer.waitfortargetoptions.timeout.md b/new-docs/puppeteer.waitfortargetoptions.timeout.md new file mode 100644 index 00000000000..bbf6fb63357 --- /dev/null +++ b/new-docs/puppeteer.waitfortargetoptions.timeout.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) > [timeout](./puppeteer.waitfortargetoptions.timeout.md) + +## WaitForTargetOptions.timeout property + +Maximum wait time in milliseconds. Pass `0` to disable the timeout. + +Signature: + +```typescript +timeout?: number; +``` diff --git a/src/common/Browser.ts b/src/common/Browser.ts index 474b8c93f12..49fe9da7713 100644 --- a/src/common/Browser.ts +++ b/src/common/Browser.ts @@ -27,7 +27,61 @@ import { Viewport } from './PuppeteerViewport'; type BrowserCloseCallback = () => Promise | void; +/** + * @public + */ +export interface WaitForTargetOptions { + /** + * Maximum wait time in milliseconds. Pass `0` to disable the timeout. + * @defaultValue 30 seconds. + */ + timeout?: number; +} + +/** + * A Browser is created when Puppeteer connects to a Chromium instance, either through + * {@link Puppeteer.launch} or {@link Puppeteer.connect}. + * + * @example + * + * An example of using a {@link Browser} to create a {@link Page}: + * ```js + * const puppeteer = require('puppeteer'); + * + * (async () => { + * const browser = await puppeteer.launch(); + * const page = await browser.newPage(); + * await page.goto('https://example.com'); + * await browser.close(); + * })(); + * ``` + * + * @example + * + * An example of disconnecting from and reconnecting to a {@link Browser}: + * ```js + * const puppeteer = require('puppeteer'); + * + * (async () => { + * const browser = await puppeteer.launch(); + * // Store the endpoint to be able to reconnect to Chromium + * const browserWSEndpoint = browser.wsEndpoint(); + * // Disconnect puppeteer from Chromium + * browser.disconnect(); + * + * // Use the endpoint to reestablish a connection + * const browser2 = await puppeteer.connect({browserWSEndpoint}); + * // Close Chromium + * await browser2.close(); + * })(); + * ``` + * + * @public + */ export class Browser extends EventEmitter { + /** + * @internal + */ static async create( connection: Connection, contextIds: string[], @@ -47,15 +101,22 @@ export class Browser extends EventEmitter { await connection.send('Target.setDiscoverTargets', { discover: true }); return browser; } - _ignoreHTTPSErrors: boolean; - _defaultViewport?: Viewport; - _process?: ChildProcess; - _connection: Connection; - _closeCallback: BrowserCloseCallback; - _defaultContext: BrowserContext; - _contexts: Map; + private _ignoreHTTPSErrors: boolean; + private _defaultViewport?: Viewport; + private _process?: ChildProcess; + private _connection: Connection; + private _closeCallback: BrowserCloseCallback; + private _defaultContext: BrowserContext; + private _contexts: Map; + /** + * @internal + * Used in Target.ts directly so cannot be marked private. + */ _targets: Map; + /** + * @internal + */ constructor( connection: Connection, contextIds: string[], @@ -94,10 +155,31 @@ export class Browser extends EventEmitter { ); } + /** + * The spawned browser process. Returns `null` if the browser instance was created with + * {@link Puppeteer.connect}. + */ process(): ChildProcess | null { return this._process; } + /** + * Creates a new incognito browser context. This won't share cookies/cache with other + * browser contexts. + * + * @example + * ```js + * (async () => { + * const browser = await puppeteer.launch(); + * // Create a new incognito browser context. + * const context = await browser.createIncognitoBrowserContext(); + * // Create a new page in a pristine context. + * const page = await context.newPage(); + * // Do stuff + * await page.goto('https://example.com'); + * })(); + * ``` + */ async createIncognitoBrowserContext(): Promise { const { browserContextId } = await this._connection.send( 'Target.createBrowserContext' @@ -111,16 +193,24 @@ export class Browser extends EventEmitter { return context; } + /** + * Returns an array of all open browser contexts. In a newly created browser, this will + * return a single instance of {@link BrowserContext}. + */ browserContexts(): BrowserContext[] { return [this._defaultContext, ...Array.from(this._contexts.values())]; } + /** + * Returns the default browser context. The default browser context cannot be closed. + */ defaultBrowserContext(): BrowserContext { return this._defaultContext; } /** - * @param {?string} contextId + * @internal + * Used by BrowserContext directly so cannot be marked private. */ async _disposeContext(contextId?: string): Promise { await this._connection.send('Target.disposeBrowserContext', { @@ -129,7 +219,7 @@ export class Browser extends EventEmitter { this._contexts.delete(contextId); } - async _targetCreated( + private async _targetCreated( event: Protocol.Target.targetCreatedPayload ): Promise { const targetInfo = event.targetInfo; @@ -158,10 +248,7 @@ export class Browser extends EventEmitter { } } - /** - * @param {{targetId: string}} event - */ - async _targetDestroyed(event: { targetId: string }): Promise { + private async _targetDestroyed(event: { targetId: string }): Promise { const target = this._targets.get(event.targetId); target._initializedCallback(false); this._targets.delete(event.targetId); @@ -174,10 +261,9 @@ export class Browser extends EventEmitter { } } - /** - * @param {!Protocol.Target.targetInfoChangedPayload} event - */ - _targetInfoChanged(event: Protocol.Target.targetInfoChangedPayload): void { + private _targetInfoChanged( + event: Protocol.Target.targetInfoChangedPayload + ): void { const target = this._targets.get(event.targetInfo.targetId); assert(target, 'target should exist before targetInfoChanged'); const previousURL = target.url(); @@ -189,14 +275,38 @@ export class Browser extends EventEmitter { } } + /** + * The browser websocket endpoint which can be used as an argument to + * {@link Puppeteer.connect}. + * + * @returns The Browser websocket url. + * + * @remarks + * + * The format is `ws://${host}:${port}/devtools/browser/`. + * + * You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/version`. + * Learn more about the + * {@link https://chromedevtools.github.io/devtools-protocol | devtools protocol} and + * the {@link + * https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target + * | browser endpoint}. + */ wsEndpoint(): string { return this._connection.url(); } + /** + * Creates a {@link Page} in the default browser context. + */ async newPage(): Promise { return this._defaultContext.newPage(); } + /** + * @internal + * Used by BrowserContext directly so cannot be marked private. + */ async _createPageInContext(contextId?: string): Promise { const { targetId } = await this._connection.send('Target.createTarget', { url: 'about:blank', @@ -211,24 +321,40 @@ export class Browser extends EventEmitter { return page; } + /** + * All active targets inside the Browser. In case of multiple browser contexts, returns + * an array with all the targets in all browser contexts. + */ targets(): Target[] { return Array.from(this._targets.values()).filter( (target) => target._isInitialized ); } + /** + * The target associated with the browser. + */ target(): Target { return this.targets().find((target) => target.type() === 'browser'); } /** - * @param {function(!Target):boolean} predicate - * @param {{timeout?: number}=} options - * @returns {!Promise} + * Searches for a target in all browser contexts. + * + * @param predicate - A function to be run for every target. + * @returns The first target found that matches the `predicate` function. + * + * @example + * + * An example of finding a target for a page opened via `window.open`: + * ```js + * await page.evaluate(() => window.open('https://www.example.com/')); + * const newWindowTarget = await browser.waitForTarget(target => target.url() === 'https://www.example.com/'); + * ``` */ async waitForTarget( predicate: (x: Target) => boolean, - options: { timeout?: number } = {} + options: WaitForTargetOptions = {} ): Promise { const { timeout = 30000 } = options; const existingTarget = this.targets().find(predicate); @@ -254,6 +380,15 @@ export class Browser extends EventEmitter { } } + /** + * An array of all open pages inside the Browser. + * + * @remarks + * + * In case of multiple browser contexts, returns an array with all the pages in all + * browser contexts. Non-visible pages, such as `"background_page"`, will not be listed + * here. You can find them using {@link Target.page}. + */ async pages(): Promise { const contextPages = await Promise.all( this.browserContexts().map((context) => context.pages()) @@ -262,30 +397,56 @@ export class Browser extends EventEmitter { return contextPages.reduce((acc, x) => acc.concat(x), []); } + /** + * A string representing the browser name and version. + * + * @remarks + * + * For headless Chromium, this is similar to `HeadlessChrome/61.0.3153.0`. For + * non-headless, this is similar to `Chrome/61.0.3153.0`. + * + * The format of browser.version() might change with future releases of Chromium. + */ async version(): Promise { const version = await this._getVersion(); return version.product; } + /** + * The browser's original user agent. Pages can override the browser user agent with + * {@link Page.setUserAgent}. + */ async userAgent(): Promise { const version = await this._getVersion(); return version.userAgent; } + /** + * Closes Chromium and all of its pages (if any were opened). The {@link Browser} object + * itself is considered to be disposed and cannot be used anymore. + */ async close(): Promise { await this._closeCallback.call(null); this.disconnect(); } + /** + * Disconnects Puppeteer from the browser, but leaves the Chromium process running. + * After calling `disconnect`, the {@link Browser} object is considered disposed and + * cannot be used anymore. + */ disconnect(): void { this._connection.dispose(); } + /** + * Indicates that the browser is connected. + */ isConnected(): boolean { return !this._connection._closed; } - _getVersion(): Promise { + private _getVersion(): Promise { return this._connection.send('Browser.getVersion'); } } diff --git a/utils/doclint/check_public_api/index.js b/utils/doclint/check_public_api/index.js index cbe74ee11eb..d7d18de2df8 100644 --- a/utils/doclint/check_public_api/index.js +++ b/utils/doclint/check_public_api/index.js @@ -664,6 +664,13 @@ function compareDocumentations(actual, expected) { expectedName: 'SnapshotOptions', }, ], + [ + 'Method Browser.waitForTarget() options', + { + actualName: 'Object', + expectedName: 'WaitForTargetOptions', + }, + ], [ 'Method EventEmitter.emit() event', {