diff --git a/new-docs/puppeteer.executioncontext._adoptbackendnodeid.md b/new-docs/puppeteer.executioncontext._adoptbackendnodeid.md deleted file mode 100644 index 1bdf1e05bf9eb..0000000000000 --- a/new-docs/puppeteer.executioncontext._adoptbackendnodeid.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ExecutionContext](./puppeteer.executioncontext.md) > [\_adoptBackendNodeId](./puppeteer.executioncontext._adoptbackendnodeid.md) - -## ExecutionContext.\_adoptBackendNodeId() method - -Signature: - -```typescript -_adoptBackendNodeId(backendNodeId: Protocol.DOM.BackendNodeId): Promise; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| backendNodeId | Protocol.DOM.BackendNodeId | | - -Returns: - -Promise<[ElementHandle](./puppeteer.elementhandle.md)> - diff --git a/new-docs/puppeteer.executioncontext._adoptelementhandle.md b/new-docs/puppeteer.executioncontext._adoptelementhandle.md deleted file mode 100644 index a211a82592e1c..0000000000000 --- a/new-docs/puppeteer.executioncontext._adoptelementhandle.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ExecutionContext](./puppeteer.executioncontext.md) > [\_adoptElementHandle](./puppeteer.executioncontext._adoptelementhandle.md) - -## ExecutionContext.\_adoptElementHandle() method - -Signature: - -```typescript -_adoptElementHandle(elementHandle: ElementHandle): Promise; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| elementHandle | [ElementHandle](./puppeteer.elementhandle.md) | | - -Returns: - -Promise<[ElementHandle](./puppeteer.elementhandle.md)> - diff --git a/new-docs/puppeteer.executioncontext._client.md b/new-docs/puppeteer.executioncontext._client.md deleted file mode 100644 index b3ad759f69844..0000000000000 --- a/new-docs/puppeteer.executioncontext._client.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ExecutionContext](./puppeteer.executioncontext.md) > [\_client](./puppeteer.executioncontext._client.md) - -## ExecutionContext.\_client property - -Signature: - -```typescript -_client: CDPSession; -``` diff --git a/new-docs/puppeteer.executioncontext._constructor_.md b/new-docs/puppeteer.executioncontext._constructor_.md deleted file mode 100644 index 8271648e1566e..0000000000000 --- a/new-docs/puppeteer.executioncontext._constructor_.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ExecutionContext](./puppeteer.executioncontext.md) > [(constructor)](./puppeteer.executioncontext._constructor_.md) - -## ExecutionContext.(constructor) - -Constructs a new instance of the `ExecutionContext` class - -Signature: - -```typescript -constructor(client: CDPSession, contextPayload: Protocol.Runtime.ExecutionContextDescription, world: DOMWorld); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| client | [CDPSession](./puppeteer.cdpsession.md) | | -| contextPayload | Protocol.Runtime.ExecutionContextDescription | | -| world | DOMWorld | | - diff --git a/new-docs/puppeteer.executioncontext._contextid.md b/new-docs/puppeteer.executioncontext._contextid.md deleted file mode 100644 index 3a8457c534803..0000000000000 --- a/new-docs/puppeteer.executioncontext._contextid.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ExecutionContext](./puppeteer.executioncontext.md) > [\_contextId](./puppeteer.executioncontext._contextid.md) - -## ExecutionContext.\_contextId property - -Signature: - -```typescript -_contextId: number; -``` diff --git a/new-docs/puppeteer.executioncontext._world.md b/new-docs/puppeteer.executioncontext._world.md deleted file mode 100644 index e01b99a26ef63..0000000000000 --- a/new-docs/puppeteer.executioncontext._world.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ExecutionContext](./puppeteer.executioncontext.md) > [\_world](./puppeteer.executioncontext._world.md) - -## ExecutionContext.\_world property - -Signature: - -```typescript -_world: DOMWorld; -``` diff --git a/new-docs/puppeteer.executioncontext.evaluate.md b/new-docs/puppeteer.executioncontext.evaluate.md index c59be4be33342..7c767e125c15c 100644 --- a/new-docs/puppeteer.executioncontext.evaluate.md +++ b/new-docs/puppeteer.executioncontext.evaluate.md @@ -14,10 +14,51 @@ evaluate(pageFunction: Function | string, ...args: unkno | Parameter | Type | Description | | --- | --- | --- | -| pageFunction | Function \| string | | -| args | unknown\[\] | | +| pageFunction | Function \| string | a function to be evaluated in the executionContext | +| args | unknown\[\] | argument to pass to the page function | Returns: Promise<ReturnType> +A promise that resolves to the return value of the given function. + +## Remarks + +If the function passed to the `executionContext.evaluate` returns a Promise, then `executionContext.evaluate` would wait for the promise to resolve and return its value. If the function passed to the `executionContext.evaluate` returns a non-serializable value, then `executionContext.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals. + +## Example 1 + + +```js +const executionContext = await page.mainFrame().executionContext(); +const result = await executionContext.evaluate(() => Promise.resolve(8 * 7))* ; +console.log(result); // prints "56" + +``` + +## Example 2 + +A string can also be passed in instead of a function. + +```js +console.log(await executionContext.evaluate('1 + 2')); // prints "3" + +``` + +## Example 3 + +[JSHandle](./puppeteer.jshandle.md) instances can be passed as arguments to the `executionContext.* evaluate`: + +```js +const oneHandle = await executionContext.evaluateHandle(() => 1); +const twoHandle = await executionContext.evaluateHandle(() => 2); +const result = await executionContext.evaluate( + (a, b) => a + b, oneHandle, * twoHandle +); +await oneHandle.dispose(); +await twoHandle.dispose(); +console.log(result); // prints '3'. + +``` + diff --git a/new-docs/puppeteer.executioncontext.evaluatehandle.md b/new-docs/puppeteer.executioncontext.evaluatehandle.md index 4ddf2d737a682..7730949164dc4 100644 --- a/new-docs/puppeteer.executioncontext.evaluatehandle.md +++ b/new-docs/puppeteer.executioncontext.evaluatehandle.md @@ -14,10 +14,49 @@ evaluateHandle(pageFunction: Function | string, ...args: unknown[]): PromiseexecutionContext | +| args | unknown\[\] | argument to pass to the page function | Returns: Promise<[JSHandle](./puppeteer.jshandle.md)> +A promise that resolves to the return value of the given function as an in-page object (a [JSHandle](./puppeteer.jshandle.md)). + +## Remarks + +The only difference between `executionContext.evaluate` and `executionContext.evaluateHandle` is that `executionContext.evaluateHandle` returns an in-page object (a [JSHandle](./puppeteer.jshandle.md)). If the function passed to the `executionContext.evaluateHandle` returns a Promise, then `executionContext.evaluateHandle` would wait for the promise to resolve and return its value. + +## Example 1 + + +```js +const context = await page.mainFrame().executionContext(); +const aHandle = await context.evaluateHandle(() => Promise.resolve(self)); +aHandle; // Handle for the global object. + +``` + +## Example 2 + +A string can also be passed in instead of a function. + +```js +// Handle for the '3' * object. +const aHandle = await context.evaluateHandle('1 + 2'); + +``` + +## Example 3 + +JSHandle instances can be passed as arguments to the `executionContext.* evaluateHandle`: + +```js +const aHandle = await context.evaluateHandle(() => document.body); +const resultHandle = await context.evaluateHandle(body => body.innerHTML, * aHandle); +console.log(await resultHandle.jsonValue()); // prints body's innerHTML +await aHandle.dispose(); +await resultHandle.dispose(); + +``` + diff --git a/new-docs/puppeteer.executioncontext.frame.md b/new-docs/puppeteer.executioncontext.frame.md index 112e4b7f60250..94a9dbab56252 100644 --- a/new-docs/puppeteer.executioncontext.frame.md +++ b/new-docs/puppeteer.executioncontext.frame.md @@ -13,3 +13,9 @@ frame(): Frame | null; [Frame](./puppeteer.frame.md) \| null +The frame associated with this execution context. + +## Remarks + +Not every execution context is associated with a frame. For example, workers and extensions have execution contexts that are not associated with frames. + diff --git a/new-docs/puppeteer.executioncontext.md b/new-docs/puppeteer.executioncontext.md index c07e290665284..c4902fd6d744c 100644 --- a/new-docs/puppeteer.executioncontext.md +++ b/new-docs/puppeteer.executioncontext.md @@ -4,34 +4,26 @@ ## ExecutionContext class +This class represents a context for JavaScript execution. A \[Page\] might have many execution contexts: - each [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) has "default" execution context that is always created after frame is attached to DOM. This context is returned by the method. - [Extension](https://developer.chrome.com/extensions)'s content scripts create additional execution contexts. + +Besides pages, execution contexts can be found in [workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). + Signature: ```typescript export declare class ExecutionContext ``` -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(client, contextPayload, world)](./puppeteer.executioncontext._constructor_.md) | | Constructs a new instance of the ExecutionContext class | - -## Properties +## Remarks -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [\_client](./puppeteer.executioncontext._client.md) | | [CDPSession](./puppeteer.cdpsession.md) | | -| [\_contextId](./puppeteer.executioncontext._contextid.md) | | number | | -| [\_world](./puppeteer.executioncontext._world.md) | | DOMWorld | | +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ExecutionContext` class. ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [\_adoptBackendNodeId(backendNodeId)](./puppeteer.executioncontext._adoptbackendnodeid.md) | | | -| [\_adoptElementHandle(elementHandle)](./puppeteer.executioncontext._adoptelementhandle.md) | | | | [evaluate(pageFunction, args)](./puppeteer.executioncontext.evaluate.md) | | | | [evaluateHandle(pageFunction, args)](./puppeteer.executioncontext.evaluatehandle.md) | | | | [frame()](./puppeteer.executioncontext.frame.md) | | | -| [queryObjects(prototypeHandle)](./puppeteer.executioncontext.queryobjects.md) | | | +| [queryObjects(prototypeHandle)](./puppeteer.executioncontext.queryobjects.md) | | This method iterates the JavaScript heap and finds all the objects with the given prototype. | diff --git a/new-docs/puppeteer.executioncontext.queryobjects.md b/new-docs/puppeteer.executioncontext.queryobjects.md index ae9f7c8e0fa6d..1401d91df4a77 100644 --- a/new-docs/puppeteer.executioncontext.queryobjects.md +++ b/new-docs/puppeteer.executioncontext.queryobjects.md @@ -4,6 +4,8 @@ ## ExecutionContext.queryObjects() method +This method iterates the JavaScript heap and finds all the objects with the given prototype. + Signature: ```typescript @@ -14,9 +16,31 @@ queryObjects(prototypeHandle: JSHandle): Promise; | Parameter | Type | Description | | --- | --- | --- | -| prototypeHandle | [JSHandle](./puppeteer.jshandle.md) | | +| prototypeHandle | [JSHandle](./puppeteer.jshandle.md) | a handle to the object prototype | Returns: Promise<[JSHandle](./puppeteer.jshandle.md)> +A handle to an array of objects with the given prototype. + +## Remarks + + +## Example + + +```js +// Create a Map object +await page.evaluate(() => window.map = new Map()); +// Get a handle to the Map object prototype +const mapPrototype = await page.evaluateHandle(() => Map.prototype); +// Query all map instances into an array +const mapInstances = await page.queryObjects(mapPrototype); +// Count amount of map objects in heap +const count = await page.evaluate(maps => maps.length, mapInstances); +await mapInstances.dispose(); +await mapPrototype.dispose(); + +``` + diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index e201778516537..e5b543386da5f 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -19,7 +19,7 @@ | [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the dialog event. | | [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. | | [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. | -| [ExecutionContext](./puppeteer.executioncontext.md) | | +| [ExecutionContext](./puppeteer.executioncontext.md) | This class represents a context for JavaScript execution. A \[Page\] might have many execution contexts: - each [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) has "default" execution context that is always created after frame is attached to DOM. This context is returned by the method. - [Extension](https://developer.chrome.com/extensions)'s content scripts create additional execution contexts.Besides pages, execution contexts can be found in [workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | | [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. | | [Frame](./puppeteer.frame.md) | | | [FrameManager](./puppeteer.framemanager.md) | | @@ -29,7 +29,7 @@ | [Keyboard](./puppeteer.keyboard.md) | | | [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. | | [Page](./puppeteer.page.md) | Page provides methods to interact with a single tab or \[extension background page\](https://developer.chrome.com/extensions/background\_pages) in Chromium. One \[Browser\] instance might have multiple \[Page\] instances. | -| [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class | +| [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class Puppeteer module provides a method to launch a browser instance. | | [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. | | [Target](./puppeteer.target.md) | | | [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | diff --git a/new-docs/puppeteer.puppeteer.__experimental_clearqueryhandlers.md b/new-docs/puppeteer.puppeteer.__experimental_clearqueryhandlers.md deleted file mode 100644 index 472cda91f80d8..0000000000000 --- a/new-docs/puppeteer.puppeteer.__experimental_clearqueryhandlers.md +++ /dev/null @@ -1,15 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [\_\_experimental\_clearQueryHandlers](./puppeteer.puppeteer.__experimental_clearqueryhandlers.md) - -## Puppeteer.\_\_experimental\_clearQueryHandlers() method - -Signature: - -```typescript -__experimental_clearQueryHandlers(): void; -``` -Returns: - -void - diff --git a/new-docs/puppeteer.puppeteer.__experimental_customqueryhandlers.md b/new-docs/puppeteer.puppeteer.__experimental_customqueryhandlers.md deleted file mode 100644 index a0a3a011db2bd..0000000000000 --- a/new-docs/puppeteer.puppeteer.__experimental_customqueryhandlers.md +++ /dev/null @@ -1,15 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [\_\_experimental\_customQueryHandlers](./puppeteer.puppeteer.__experimental_customqueryhandlers.md) - -## Puppeteer.\_\_experimental\_customQueryHandlers() method - -Signature: - -```typescript -__experimental_customQueryHandlers(): Map; -``` -Returns: - -Map<string, QueryHandler> - diff --git a/new-docs/puppeteer.puppeteer.__experimental_registercustomqueryhandler.md b/new-docs/puppeteer.puppeteer.__experimental_registercustomqueryhandler.md deleted file mode 100644 index a82909a005054..0000000000000 --- a/new-docs/puppeteer.puppeteer.__experimental_registercustomqueryhandler.md +++ /dev/null @@ -1,23 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [\_\_experimental\_registerCustomQueryHandler](./puppeteer.puppeteer.__experimental_registercustomqueryhandler.md) - -## Puppeteer.\_\_experimental\_registerCustomQueryHandler() method - -Signature: - -```typescript -__experimental_registerCustomQueryHandler(name: string, queryHandler: QueryHandler): void; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| name | string | | -| queryHandler | QueryHandler | | - -Returns: - -void - diff --git a/new-docs/puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md b/new-docs/puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md deleted file mode 100644 index 849952443275a..0000000000000 --- a/new-docs/puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [\_\_experimental\_unregisterCustomQueryHandler](./puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md) - -## Puppeteer.\_\_experimental\_unregisterCustomQueryHandler() method - -Signature: - -```typescript -__experimental_unregisterCustomQueryHandler(name: string): void; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| name | string | | - -Returns: - -void - diff --git a/new-docs/puppeteer.puppeteer._constructor_.md b/new-docs/puppeteer.puppeteer._constructor_.md deleted file mode 100644 index 1c81db8fe1cf0..0000000000000 --- a/new-docs/puppeteer.puppeteer._constructor_.md +++ /dev/null @@ -1,23 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [(constructor)](./puppeteer.puppeteer._constructor_.md) - -## Puppeteer.(constructor) - -Constructs a new instance of the `Puppeteer` class - -Signature: - -```typescript -constructor(projectRoot: string, preferredRevision: string, isPuppeteerCore: boolean, productName: string); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| projectRoot | string | | -| preferredRevision | string | | -| isPuppeteerCore | boolean | | -| productName | string | | - diff --git a/new-docs/puppeteer.puppeteer._launcher.md b/new-docs/puppeteer.puppeteer._launcher.md deleted file mode 100644 index df1596e2e3211..0000000000000 --- a/new-docs/puppeteer.puppeteer._launcher.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [\_launcher](./puppeteer.puppeteer._launcher.md) - -## Puppeteer.\_launcher property - -Signature: - -```typescript -get _launcher(): ProductLauncher; -``` diff --git a/new-docs/puppeteer.puppeteer._productname.md b/new-docs/puppeteer.puppeteer._productname.md deleted file mode 100644 index 9c00de81a9d5e..0000000000000 --- a/new-docs/puppeteer.puppeteer._productname.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [\_productName](./puppeteer.puppeteer._productname.md) - -## Puppeteer.\_productName property - -Signature: - -```typescript -get _productName(): string; - -set _productName(name: string); -``` diff --git a/new-docs/puppeteer.puppeteer.connect.md b/new-docs/puppeteer.puppeteer.connect.md index 36baa350a0ac4..6431e3848f958 100644 --- a/new-docs/puppeteer.puppeteer.connect.md +++ b/new-docs/puppeteer.puppeteer.connect.md @@ -4,6 +4,8 @@ ## Puppeteer.connect() method +This method attaches Puppeteer to an existing browser instance. + Signature: ```typescript @@ -19,9 +21,14 @@ connect(options: BrowserOptions & { | Parameter | Type | Description | | --- | --- | --- | -| options | BrowserOptions & { browserWSEndpoint?: string; browserURL?: string; transport?: ConnectionTransport; product?: string; } | | +| options | BrowserOptions & { browserWSEndpoint?: string; browserURL?: string; transport?: ConnectionTransport; product?: string; } | Set of configurable options to set on the browser. | Returns: Promise<[Browser](./puppeteer.browser.md)> +Promise which resolves to browser instance. + +## Remarks + + diff --git a/new-docs/puppeteer.puppeteer.createbrowserfetcher.md b/new-docs/puppeteer.puppeteer.createbrowserfetcher.md index dffbddfa87dfd..0aecc97bec783 100644 --- a/new-docs/puppeteer.puppeteer.createbrowserfetcher.md +++ b/new-docs/puppeteer.puppeteer.createbrowserfetcher.md @@ -14,9 +14,11 @@ createBrowserFetcher(options: BrowserFetcherOptions): BrowserFetcher; | Parameter | Type | Description | | --- | --- | --- | -| options | [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | | +| options | [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | Set of configurable options to specify the settings of the BrowserFetcher. | Returns: [BrowserFetcher](./puppeteer.browserfetcher.md) +A new BrowserFetcher instance. + diff --git a/new-docs/puppeteer.puppeteer.defaultargs.md b/new-docs/puppeteer.puppeteer.defaultargs.md index ff0d72ee55c62..f7e8cc269dfb9 100644 --- a/new-docs/puppeteer.puppeteer.defaultargs.md +++ b/new-docs/puppeteer.puppeteer.defaultargs.md @@ -14,9 +14,11 @@ defaultArgs(options?: ChromeArgOptions): string[]; | Parameter | Type | Description | | --- | --- | --- | -| options | ChromeArgOptions | | +| options | ChromeArgOptions | Set of configurable options to set on the browser. | Returns: string\[\] +The default flags that Chromium will be launched with. + diff --git a/new-docs/puppeteer.puppeteer.devices.md b/new-docs/puppeteer.puppeteer.devices.md index 82469af5b85c4..9a5379dc44363 100644 --- a/new-docs/puppeteer.puppeteer.devices.md +++ b/new-docs/puppeteer.puppeteer.devices.md @@ -9,3 +9,25 @@ ```typescript get devices(): DevicesMap; ``` + +## Remarks + + +## Example + + +```js +const puppeteer = require('puppeteer'); +const iPhone = puppeteer.devices['iPhone 6']; + +(async () => { + const browser = await puppeteer.launch(); + const page = await browser.newPage(); + await page.emulate(iPhone); + await page.goto('https://www.google.com'); + // other actions... + await browser.close(); +})(); + +``` + diff --git a/new-docs/puppeteer.puppeteer.errors.md b/new-docs/puppeteer.puppeteer.errors.md index a614dbd5b59cb..f81b4cb41899b 100644 --- a/new-docs/puppeteer.puppeteer.errors.md +++ b/new-docs/puppeteer.puppeteer.errors.md @@ -9,3 +9,25 @@ ```typescript get errors(): PuppeteerErrors; ``` + +## Remarks + +Puppeteer methods might throw errors if they are unable to fulfill a request. For example, `page.waitForSelector(selector[, options])` might fail if the selector doesn't match any nodes during the given timeframe. + +For certain types of errors Puppeteer uses specific error classes. These classes are available via `puppeteer.errors` + +## Example + +An example of handling a timeout error: + +```js +try { + await page.waitForSelector('.foo'); +} catch (e) { + if (e instanceof puppeteer.errors.TimeoutError) { + // Do something if this is a timeout. + } +} + +``` + diff --git a/new-docs/puppeteer.puppeteer.executablepath.md b/new-docs/puppeteer.puppeteer.executablepath.md index 7e05dc3a81ba0..970f70a81d071 100644 --- a/new-docs/puppeteer.puppeteer.executablepath.md +++ b/new-docs/puppeteer.puppeteer.executablepath.md @@ -13,3 +13,9 @@ executablePath(): string; string +A path where Puppeteer expects to find the bundled browser. The browser binary might not be there if the download was skipped with the `PUPPETEER_SKIP_DOWNLOAD` environment variable. + +## Remarks + +\*\*NOTE\*\* `puppeteer.executablePath()` is affected by the `PUPPETEER_EXECUTABLE_PATH` and `PUPPETEER_CHROMIUM_REVISION` environment variables. + diff --git a/new-docs/puppeteer.puppeteer.launch.md b/new-docs/puppeteer.puppeteer.launch.md index 6b458e5c9c105..604cca0bc6afa 100644 --- a/new-docs/puppeteer.puppeteer.launch.md +++ b/new-docs/puppeteer.puppeteer.launch.md @@ -4,6 +4,8 @@ ## Puppeteer.launch() method +Launches puppeteer and launches a browser instance with given arguments and options when specified. + Signature: ```typescript @@ -17,9 +19,26 @@ launch(options?: LaunchOptions & ChromeArgOptions & BrowserOptions & { | Parameter | Type | Description | | --- | --- | --- | -| options | LaunchOptions & ChromeArgOptions & BrowserOptions & { product?: string; extraPrefsFirefox?: {}; } | | +| options | LaunchOptions & ChromeArgOptions & BrowserOptions & { product?: string; extraPrefsFirefox?: {}; } | Set of configurable options to set on the browser. | Returns: Promise<[Browser](./puppeteer.browser.md)> +Promise which resolves to browser instance. + +## Remarks + + +## Example + +You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments: + +```js +const browser = await puppeteer.launch({ + ignoreDefaultArgs: ['--mute-audio'] +}); + +``` +\*\*NOTE\*\* Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution. If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. In `puppeteer.launch([options])`, any mention of Chromium also applies to Chrome. See [this article](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [This article](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. + diff --git a/new-docs/puppeteer.puppeteer.md b/new-docs/puppeteer.puppeteer.md index bfbf737dc2e11..f27df977800aa 100644 --- a/new-docs/puppeteer.puppeteer.md +++ b/new-docs/puppeteer.puppeteer.md @@ -4,7 +4,7 @@ ## Puppeteer class -The main Puppeteer class +The main Puppeteer class Puppeteer module provides a method to launch a browser instance. Signature: @@ -12,11 +12,26 @@ The main Puppeteer class export declare class Puppeteer ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(projectRoot, preferredRevision, isPuppeteerCore, productName)](./puppeteer.puppeteer._constructor_.md) | | Constructs a new instance of the Puppeteer 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 `Puppeteer` class. + +## Example + +The following is a typical example of using Puppeteer to drive automation: + +```js +const puppeteer = require('puppeteer'); + +(async () => { + const browser = await puppeteer.launch(); + const page = await browser.newPage(); + await page.goto('https://www.google.com'); + // other actions... + await browser.close(); +})(); + +``` ## Properties @@ -25,10 +40,8 @@ export declare class Puppeteer | [\_\_productName](./puppeteer.puppeteer.__productname.md) | | string | | | [\_changedProduct](./puppeteer.puppeteer._changedproduct.md) | | boolean | | | [\_isPuppeteerCore](./puppeteer.puppeteer._ispuppeteercore.md) | | boolean | | -| [\_launcher](./puppeteer.puppeteer._launcher.md) | | ProductLauncher | | | [\_lazyLauncher](./puppeteer.puppeteer._lazylauncher.md) | | ProductLauncher | | | [\_preferredRevision](./puppeteer.puppeteer._preferredrevision.md) | | string | | -| [\_productName](./puppeteer.puppeteer._productname.md) | | string | | | [\_projectRoot](./puppeteer.puppeteer._projectroot.md) | | string | | | [devices](./puppeteer.puppeteer.devices.md) | | DevicesMap | | | [errors](./puppeteer.puppeteer.errors.md) | | [PuppeteerErrors](./puppeteer.puppeteererrors.md) | | @@ -38,13 +51,9 @@ export declare class Puppeteer | Method | Modifiers | Description | | --- | --- | --- | -| [\_\_experimental\_clearQueryHandlers()](./puppeteer.puppeteer.__experimental_clearqueryhandlers.md) | | | -| [\_\_experimental\_customQueryHandlers()](./puppeteer.puppeteer.__experimental_customqueryhandlers.md) | | | -| [\_\_experimental\_registerCustomQueryHandler(name, queryHandler)](./puppeteer.puppeteer.__experimental_registercustomqueryhandler.md) | | | -| [\_\_experimental\_unregisterCustomQueryHandler(name)](./puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md) | | | -| [connect(options)](./puppeteer.puppeteer.connect.md) | | | +| [connect(options)](./puppeteer.puppeteer.connect.md) | | This method attaches Puppeteer to an existing browser instance. | | [createBrowserFetcher(options)](./puppeteer.puppeteer.createbrowserfetcher.md) | | | | [defaultArgs(options)](./puppeteer.puppeteer.defaultargs.md) | | | | [executablePath()](./puppeteer.puppeteer.executablepath.md) | | | -| [launch(options)](./puppeteer.puppeteer.launch.md) | | | +| [launch(options)](./puppeteer.puppeteer.launch.md) | | Launches puppeteer and launches a browser instance with given arguments and options when specified. | diff --git a/new-docs/puppeteer.puppeteer.product.md b/new-docs/puppeteer.puppeteer.product.md index 93ef07315b4c6..465211c69b426 100644 --- a/new-docs/puppeteer.puppeteer.product.md +++ b/new-docs/puppeteer.puppeteer.product.md @@ -9,3 +9,8 @@ ```typescript get product(): string; ``` + +## Remarks + +The product is set by the `PUPPETEER_PRODUCT` environment variable or the `product` option in `puppeteer.launch([options])` and defaults to `chrome`. Firefox support is experimental. + diff --git a/src/common/ExecutionContext.ts b/src/common/ExecutionContext.ts index b653895e4e796..5681e9d0bc0af 100644 --- a/src/common/ExecutionContext.ts +++ b/src/common/ExecutionContext.ts @@ -25,11 +25,37 @@ import Protocol from '../protocol'; export const EVALUATION_SCRIPT_URL = '__puppeteer_evaluation_script__'; const SOURCE_URL_REGEX = /^[\040\t]*\/\/[@#] sourceURL=\s*(\S*?)\s*$/m; +/** + * This class represents a context for JavaScript execution. A [Page] might have + * many execution contexts: + * - each + * {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe | + * frame } has "default" execution context that is always created after frame is + * attached to DOM. This context is returned by the + * {@link frame.executionContext()} method. + * - {@link https://developer.chrome.com/extensions | Extension}'s content scripts + * create additional execution contexts. + * + * Besides pages, execution contexts can be found in + * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | + * workers }. + * + * @public + */ export class ExecutionContext { + /** + * @internal + */ _client: CDPSession; + /** + * @internal + */ _world: DOMWorld; - _contextId: number; + private _contextId: number; + /** + * @internal + */ constructor( client: CDPSession, contextPayload: Protocol.Runtime.ExecutionContextDescription, @@ -40,10 +66,62 @@ export class ExecutionContext { this._contextId = contextPayload.id; } + /** + * @remarks + * + * Not every execution context is associated with a frame. For + * example, workers and extensions have execution contexts that are not + * associated with frames. + * + * @returns The frame associated with this execution context. + */ frame(): Frame | null { return this._world ? this._world.frame() : null; } + /** + * @remarks + * If the function passed to the `executionContext.evaluate` returns a + * Promise, then `executionContext.evaluate` would wait for the promise to + * resolve and return its value. If the function passed to the + * `executionContext.evaluate` returns a non-serializable value, then + * `executionContext.evaluate` resolves to `undefined`. DevTools Protocol also + * supports transferring some additional values that are not serializable by + * `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals. + * + * + * @example + * ```js + * const executionContext = await page.mainFrame().executionContext(); + * const result = await executionContext.evaluate(() => Promise.resolve(8 * 7))* ; + * console.log(result); // prints "56" + * ``` + * + * @example + * A string can also be passed in instead of a function. + * + * ```js + * console.log(await executionContext.evaluate('1 + 2')); // prints "3" + * ``` + * + * @example + * {@link JSHandle} instances can be passed as arguments to the + * `executionContext.* evaluate`: + * ```js + * const oneHandle = await executionContext.evaluateHandle(() => 1); + * const twoHandle = await executionContext.evaluateHandle(() => 2); + * const result = await executionContext.evaluate( + * (a, b) => a + b, oneHandle, * twoHandle + * ); + * await oneHandle.dispose(); + * await twoHandle.dispose(); + * console.log(result); // prints '3'. + * ``` + * @param pageFunction a function to be evaluated in the `executionContext` + * @param args argument to pass to the page function + * + * @returns A promise that resolves to the return value of the given function. + */ async evaluate( pageFunction: Function | string, ...args: unknown[] @@ -55,6 +133,48 @@ export class ExecutionContext { ); } + /** + * @remarks + * The only difference between `executionContext.evaluate` and + * `executionContext.evaluateHandle` is that `executionContext.evaluateHandle` + * returns an in-page object (a {@link JSHandle}). + * If the function passed to the `executionContext.evaluateHandle` returns a + * Promise, then `executionContext.evaluateHandle` would wait for the + * promise to resolve and return its value. + * + * @example + * ```js + * const context = await page.mainFrame().executionContext(); + * const aHandle = await context.evaluateHandle(() => Promise.resolve(self)); + * aHandle; // Handle for the global object. + * ``` + * + * @example + * A string can also be passed in instead of a function. + * + * ```js + * // Handle for the '3' * object. + * const aHandle = await context.evaluateHandle('1 + 2'); + * ``` + * + * @example + * JSHandle instances can be passed as arguments + * to the `executionContext.* evaluateHandle`: + * + * ```js + * const aHandle = await context.evaluateHandle(() => document.body); + * const resultHandle = await context.evaluateHandle(body => body.innerHTML, * aHandle); + * console.log(await resultHandle.jsonValue()); // prints body's innerHTML + * await aHandle.dispose(); + * await resultHandle.dispose(); + * ``` + * + * @param pageFunction a function to be evaluated in the `executionContext` + * @param args argument to pass to the page function + * + * @returns A promise that resolves to the return value of the given function + * as an in-page object (a {@link JSHandle}). + */ async evaluateHandle( pageFunction: Function | string, ...args: unknown[] @@ -197,6 +317,28 @@ export class ExecutionContext { } } + /** + * This method iterates the JavaScript heap and finds all the objects with the + * given prototype. + * @remarks + * @example + * ```js + * // Create a Map object + * await page.evaluate(() => window.map = new Map()); + * // Get a handle to the Map object prototype + * const mapPrototype = await page.evaluateHandle(() => Map.prototype); + * // Query all map instances into an array + * const mapInstances = await page.queryObjects(mapPrototype); + * // Count amount of map objects in heap + * const count = await page.evaluate(maps => maps.length, mapInstances); + * await mapInstances.dispose(); + * await mapPrototype.dispose(); + * ``` + * + * @param prototypeHandle a handle to the object prototype + * + * @returns A handle to an array of objects with the given prototype. + */ async queryObjects(prototypeHandle: JSHandle): Promise { assert(!prototypeHandle._disposed, 'Prototype JSHandle is disposed!'); assert( @@ -209,6 +351,9 @@ export class ExecutionContext { return createJSHandle(this, response.objects); } + /** + * @internal + */ async _adoptBackendNodeId( backendNodeId: Protocol.DOM.BackendNodeId ): Promise { @@ -219,6 +364,9 @@ export class ExecutionContext { return createJSHandle(this, object) as ElementHandle; } + /** + * @internal + */ async _adoptElementHandle( elementHandle: ElementHandle ): Promise { diff --git a/src/common/Puppeteer.ts b/src/common/Puppeteer.ts index e81ca0af9a145..5996298cc604e 100644 --- a/src/common/Puppeteer.ts +++ b/src/common/Puppeteer.ts @@ -37,6 +37,23 @@ import { /** * The main Puppeteer class + * Puppeteer module provides a method to launch a browser instance. + * + * @remarks + * + * @example + * The following is a typical example of using Puppeteer to drive automation: + * ```js + * const puppeteer = require('puppeteer'); + * + * (async () => { + * const browser = await puppeteer.launch(); + * const page = await browser.newPage(); + * await page.goto('https://www.google.com'); + * // other actions... + * await browser.close(); + * })(); + * ``` * @public */ export class Puppeteer { @@ -47,6 +64,9 @@ export class Puppeteer { __productName: string; _lazyLauncher: ProductLauncher; + /** + * @internal + */ constructor( projectRoot: string, preferredRevision: string, @@ -60,6 +80,31 @@ export class Puppeteer { this.__productName = productName; } + /** + * Launches puppeteer and launches a browser instance with given arguments + * and options when specified. + * + * @remarks + * + * @example + * You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments: + * ```js + * const browser = await puppeteer.launch({ + * ignoreDefaultArgs: ['--mute-audio'] + * }); + * ``` + * + * **NOTE** Puppeteer can also be used to control the Chrome browser, + * but it works best with the version of Chromium it is bundled with. + * There is no guarantee it will work with any other version. + * Use `executablePath` option with extreme caution. + * If Google Chrome (rather than Chromium) is preferred, a {@link https://www.google.com/chrome/browser/canary.html | Chrome Canary} or {@link https://www.chromium.org/getting-involved/dev-channel | Dev Channel} build is suggested. + * In `puppeteer.launch([options])`, any mention of Chromium also applies to Chrome. + * See {@link https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/ | this article} for a description of the differences between Chromium and Chrome. {@link https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md | This article} describes some differences for Linux users. + * + * @param options - Set of configurable options to set on the browser. + * @returns Promise which resolves to browser instance. + */ launch( options: LaunchOptions & ChromeArgOptions & @@ -69,6 +114,14 @@ export class Puppeteer { return this._launcher.launch(options); } + /** + * This method attaches Puppeteer to an existing browser instance. + * + * @remarks + * + * @param options - Set of configurable options to set on the browser. + * @returns Promise which resolves to browser instance. + */ connect( options: BrowserOptions & { browserWSEndpoint?: string; @@ -81,19 +134,38 @@ export class Puppeteer { return this._launcher.connect(options); } + /** + * @internal + */ set _productName(name: string) { if (this.__productName !== name) this._changedProduct = true; this.__productName = name; } + /** + * @internal + */ get _productName(): string { return this.__productName; } + /** + * @remarks + * + * **NOTE** `puppeteer.executablePath()` is affected by the `PUPPETEER_EXECUTABLE_PATH` + * and `PUPPETEER_CHROMIUM_REVISION` environment variables. + * + * @returns A path where Puppeteer expects to find the bundled browser. + * The browser binary might not be there if the download was skipped with + * the `PUPPETEER_SKIP_DOWNLOAD` environment variable. + */ executablePath(): string { return this._launcher.executablePath(); } + /** + * @internal + */ get _launcher(): ProductLauncher { if ( !this._lazyLauncher || @@ -122,26 +194,89 @@ export class Puppeteer { return this._lazyLauncher; } + /** + * @returns The name of the browser that is under automation (`"chrome"` or `"firefox"`) + * + * @remarks + * The product is set by the `PUPPETEER_PRODUCT` environment variable or the `product` + * option in `puppeteer.launch([options])` and defaults to `chrome`. + * Firefox support is experimental. + */ get product(): string { return this._launcher.product; } + /** + * @remarks + * @example + * + * ```js + * const puppeteer = require('puppeteer'); + * const iPhone = puppeteer.devices['iPhone 6']; + * + * (async () => { + * const browser = await puppeteer.launch(); + * const page = await browser.newPage(); + * await page.emulate(iPhone); + * await page.goto('https://www.google.com'); + * // other actions... + * await browser.close(); + * })(); + * ``` + * + * @returns a list of devices to be used with `page.emulate(options)`. Actual list of devices can be found in {@link https://github.com/puppeteer/puppeteer/blob/main/src/DeviceDescriptors.ts | src/DeviceDescriptors.ts}. + */ get devices(): DevicesMap { return devicesMap; } + /** + * @remarks + * + * Puppeteer methods might throw errors if they are unable to fulfill a request. + * For example, `page.waitForSelector(selector[, options])` might fail if + * the selector doesn't match any nodes during the given timeframe. + * + * For certain types of errors Puppeteer uses specific error classes. + * These classes are available via `puppeteer.errors` + * @example + * An example of handling a timeout error: + * ```js + * try { + * await page.waitForSelector('.foo'); + * } catch (e) { + * if (e instanceof puppeteer.errors.TimeoutError) { + * // Do something if this is a timeout. + * } + * } + * ``` + */ get errors(): PuppeteerErrors { return puppeteerErrors; } + /** + * + * @param options Set of configurable options to set on the browser. + * @returns The default flags that Chromium will be launched with. + */ defaultArgs(options: ChromeArgOptions = {}): string[] { return this._launcher.defaultArgs(options); } + /** + * + * @param options Set of configurable options to specify the settings + * of the BrowserFetcher. + * @returns A new BrowserFetcher instance. + */ createBrowserFetcher(options: BrowserFetcherOptions): BrowserFetcher { return new BrowserFetcher(this._projectRoot, options); } + /** + * @internal + */ // eslint-disable-next-line @typescript-eslint/camelcase __experimental_registerCustomQueryHandler( name: string, @@ -150,16 +285,25 @@ export class Puppeteer { registerCustomQueryHandler(name, queryHandler); } + /** + * @internal + */ // eslint-disable-next-line @typescript-eslint/camelcase __experimental_unregisterCustomQueryHandler(name: string): void { unregisterCustomQueryHandler(name); } + /** + * @internal + */ // eslint-disable-next-line @typescript-eslint/camelcase __experimental_customQueryHandlers(): Map { return customQueryHandlers(); } + /** + * @internal + */ // eslint-disable-next-line @typescript-eslint/camelcase __experimental_clearQueryHandlers(): void { clearQueryHandlers();