diff --git a/.eslintignore b/.eslintignore index bf92b420f3a09..2cd9862cd76d2 100644 --- a/.eslintignore +++ b/.eslintignore @@ -7,7 +7,7 @@ build/ lib/ # Generated files -tsconfig.tsbuildinfo +**/*.tsbuildinfo puppeteer.api.json puppeteer*.tgz yarn.lock @@ -18,9 +18,11 @@ yarn.lock test/output-*/ .dev_profile* coverage/ +src/generated # IDE Artifacts .vscode +.devcontainer # Misc .DS_Store @@ -32,6 +34,7 @@ coverage/ npm-debug.log* yarn-debug.log* yarn-error.log* + ## [END] Keep in sync with .gitignore # ESLint ignores. diff --git a/.github/workflows/pre-release.yml b/.github/workflows/pre-release.yml index 22a43fef7d592..72ab3d7043a07 100644 --- a/.github/workflows/pre-release.yml +++ b/.github/workflows/pre-release.yml @@ -20,7 +20,7 @@ jobs: run: npm install - name: Build run: | - node utils/generate_version_file.js + npm run generate:sources npm run docs - name: Version docs working-directory: ./website diff --git a/.github/workflows/publish-docker.yml b/.github/workflows/publish-docker.yml index 0671a297026b2..a4d88a1d9d5d6 100644 --- a/.github/workflows/publish-docker.yml +++ b/.github/workflows/publish-docker.yml @@ -42,7 +42,7 @@ jobs: - name: Pack Puppeteer for docker run: docker/pack.sh - name: Build and push the Docker image - uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc + uses: docker/build-push-action@c84f38281176d4c9cdb1626ffafcd6b3911b5d94 with: context: ./docker push: true diff --git a/.gitignore b/.gitignore index de382d4b322b4..81ab684afc83e 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,7 @@ yarn.lock test/output-*/ .dev_profile* coverage/ +src/generated # IDE Artifacts .vscode diff --git a/.prettierignore b/.prettierignore index d3d64d2a174de..738ed9e55b2c4 100644 --- a/.prettierignore +++ b/.prettierignore @@ -7,7 +7,7 @@ build/ lib/ # Generated files -tsconfig.tsbuildinfo +**/*.tsbuildinfo puppeteer.api.json puppeteer*.tgz yarn.lock @@ -18,9 +18,11 @@ yarn.lock test/output-*/ .dev_profile* coverage/ +src/generated # IDE Artifacts .vscode +.devcontainer # Misc .DS_Store diff --git a/.release-please-manifest.json b/.release-please-manifest.json index a5c0526bed5b0..841e693b4d8ca 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "16.1.0" + ".": "17.0.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index e25ce083c5a1f..be44426ad824b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,47 @@ All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. +## [17.0.0](https://github.com/puppeteer/puppeteer/compare/v16.2.0...v17.0.0) (2022-08-26) + + +### ⚠ BREAKING CHANGES + +* remove `root` from `WaitForSelectorOptions` (#8848) +* internalize execution context (#8844) + +### Bug Fixes + +* allow multiple navigations to happen in LifecycleWatcher ([#8826](https://github.com/puppeteer/puppeteer/issues/8826)) ([341b669](https://github.com/puppeteer/puppeteer/commit/341b669a5e45ecbb9ffb0f28c45b520660f27ad2)), closes [#8811](https://github.com/puppeteer/puppeteer/issues/8811) +* internalize execution context ([#8844](https://github.com/puppeteer/puppeteer/issues/8844)) ([2f33237](https://github.com/puppeteer/puppeteer/commit/2f33237d0443de77d58dca4454b0c9a1d2b57d03)) +* remove `root` from `WaitForSelectorOptions` ([#8848](https://github.com/puppeteer/puppeteer/issues/8848)) ([1155c8e](https://github.com/puppeteer/puppeteer/commit/1155c8eac85b176c3334cc3d98adfe7d943dfbe6)) +* remove deferred promise timeouts ([#8835](https://github.com/puppeteer/puppeteer/issues/8835)) ([202ffce](https://github.com/puppeteer/puppeteer/commit/202ffce0aa4f34dba35fbb8e7d740af16efee35f)), closes [#8832](https://github.com/puppeteer/puppeteer/issues/8832) + +## [16.2.0](https://github.com/puppeteer/puppeteer/compare/v16.1.1...v16.2.0) (2022-08-18) + + +### Features + +* add Khmer (Cambodian) language support ([#8809](https://github.com/puppeteer/puppeteer/issues/8809)) ([34f8737](https://github.com/puppeteer/puppeteer/commit/34f873721804d57a5faf3eab8ef50340c69ed180)) + + +### Bug Fixes + +* handle service workers in extensions ([#8807](https://github.com/puppeteer/puppeteer/issues/8807)) ([2a0eefb](https://github.com/puppeteer/puppeteer/commit/2a0eefb99f0ae00dacc9e768a253308c0d18a4c3)), closes [#8800](https://github.com/puppeteer/puppeteer/issues/8800) + +## [16.1.1](https://github.com/puppeteer/puppeteer/compare/v16.1.0...v16.1.1) (2022-08-16) + + +### Bug Fixes + +* custom sessions should not emit targetcreated events ([#8788](https://github.com/puppeteer/puppeteer/issues/8788)) ([3fad05d](https://github.com/puppeteer/puppeteer/commit/3fad05d333b79f41a7b58582c4ca493200bb5a79)), closes [#8787](https://github.com/puppeteer/puppeteer/issues/8787) +* deprecate `ExecutionContext` ([#8792](https://github.com/puppeteer/puppeteer/issues/8792)) ([b5da718](https://github.com/puppeteer/puppeteer/commit/b5da718e2e4a2004a36cf23cad555e1fc3b50333)) +* deprecate `root` in `WaitForSelectorOptions` ([#8795](https://github.com/puppeteer/puppeteer/issues/8795)) ([65a5ce8](https://github.com/puppeteer/puppeteer/commit/65a5ce8464c56fcc55e5ac3ed490f31311bbe32a)) +* deprecate `waitForTimeout` ([#8793](https://github.com/puppeteer/puppeteer/issues/8793)) ([8f612d5](https://github.com/puppeteer/puppeteer/commit/8f612d5ff855d48ae4b38bdaacf2a8fbda8e9ce8)) +* make sure there is a check for targets when timeout=0 ([#8765](https://github.com/puppeteer/puppeteer/issues/8765)) ([c23cdb7](https://github.com/puppeteer/puppeteer/commit/c23cdb73a7b113c1dd29f7e4a7a61326422c4080)), closes [#8763](https://github.com/puppeteer/puppeteer/issues/8763) +* resolve navigation flakiness ([#8768](https://github.com/puppeteer/puppeteer/issues/8768)) ([2580347](https://github.com/puppeteer/puppeteer/commit/2580347b50091d172b2a5591138a2e41ede072fe)), closes [#8644](https://github.com/puppeteer/puppeteer/issues/8644) +* specify Puppeteer version for Chromium 105.0.5173.0 ([#8766](https://github.com/puppeteer/puppeteer/issues/8766)) ([b5064b7](https://github.com/puppeteer/puppeteer/commit/b5064b7b8bd3bd9eb481b6807c65d9d06d23b9dd)) +* use targetFilter in puppeteer.launch ([#8774](https://github.com/puppeteer/puppeteer/issues/8774)) ([ee2540b](https://github.com/puppeteer/puppeteer/commit/ee2540baefeced44f6b336f2b979af5c3a4cb040)), closes [#8772](https://github.com/puppeteer/puppeteer/issues/8772) + ## [16.1.0](https://github.com/puppeteer/puppeteer/compare/v16.0.0...v16.1.0) (2022-08-06) diff --git a/docker/Dockerfile b/docker/Dockerfile index 1d7884cd8035d..c820833d46f86 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -8,7 +8,7 @@ RUN apt-get update \ && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \ && sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \ && apt-get update \ - && apt-get install -y google-chrome-stable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf libxss1 \ + && apt-get install -y google-chrome-stable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-khmeros fonts-kacst fonts-freefont-ttf libxss1 \ --no-install-recommends \ && rm -rf /var/lib/apt/lists/* diff --git a/docs/api/index.md b/docs/api/index.md index aab590d9573af..9eabae6bfd517 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -6,40 +6,39 @@ sidebar_label: API ## Classes -| 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) | A Browser is created when Puppeteer connects to a Chromium instance, either through [PuppeteerNode.launch()](./puppeteer.puppeteernode.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | -| [BrowserContext](./puppeteer.browsercontext.md) | BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. | -| [BrowserFetcher](./puppeteer.browserfetcher.md) | BrowserFetcher can download and manage different versions of Chromium and Firefox. | -| [CDPSession](./puppeteer.cdpsession.md) | The CDPSession instances are used to talk raw Chrome Devtools Protocol. | -| [Connection](./puppeteer.connection.md) | | -| [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. | -| [Coverage](./puppeteer.coverage.md) | The Coverage class provides methods to gathers information about parts of JavaScript and CSS that were used by the page. | -| [CSSCoverage](./puppeteer.csscoverage.md) | | -| [CustomError](./puppeteer.customerror.md) | | -| [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) | Represents a context for JavaScript execution. | -| [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. | -| [Frame](./puppeteer.frame.md) | At every point of time, page exposes its current frame tree via the [page.mainFrame](./puppeteer.page.mainframe.md) and [frame.childFrames](./puppeteer.frame.childframes.md) methods. | -| [HTTPRequest](./puppeteer.httprequest.md) | Represents an HTTP request sent by a page. | -| [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. | -| [JSCoverage](./puppeteer.jscoverage.md) | | -| [JSHandle](./puppeteer.jshandle.md) |

Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).

Handles prevent the referenced JavaScript object from being garbage-collected unless the handle is purposely [disposed](./puppeteer.jshandle.dispose.md). JSHandles are auto-disposed when their associated frame is navigated away or the parent context gets destroyed.

Handles can be used as arguments for any evaluation function such as [Page.$eval()](./puppeteer.page._eval.md), [Page.evaluate()](./puppeteer.page.evaluate.md), and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md). They are resolved to their referenced object.

| -| [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. | -| [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.

:::note

One Browser instance might have multiple Page instances.

:::

| -| [ProtocolError](./puppeteer.protocolerror.md) | ProtocolError is emitted whenever there is an error from the protocol. | -| [Puppeteer](./puppeteer.puppeteer.md) |

The main Puppeteer class.

IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require puppeteer. That class extends Puppeteer, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).

| -| [PuppeteerNode](./puppeteer.puppeteernode.md) |

Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.

If you're using Puppeteer in a Node environment, this is the class you'll get when you run require('puppeteer') (or the equivalent ES import).

| -| [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. | -| [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | -| [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | -| [WebWorker](./puppeteer.webworker.md) | This class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | +| 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) | A Browser is created when Puppeteer connects to a Chromium instance, either through [PuppeteerNode.launch()](./puppeteer.puppeteernode.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | +| [BrowserContext](./puppeteer.browsercontext.md) | BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. | +| [BrowserFetcher](./puppeteer.browserfetcher.md) | BrowserFetcher can download and manage different versions of Chromium and Firefox. | +| [CDPSession](./puppeteer.cdpsession.md) | The CDPSession instances are used to talk raw Chrome Devtools Protocol. | +| [Connection](./puppeteer.connection.md) | | +| [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. | +| [Coverage](./puppeteer.coverage.md) | The Coverage class provides methods to gathers information about parts of JavaScript and CSS that were used by the page. | +| [CSSCoverage](./puppeteer.csscoverage.md) | | +| [CustomError](./puppeteer.customerror.md) | | +| [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. | +| [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. | +| [Frame](./puppeteer.frame.md) |

Represents a DOM frame.

To understand frames, you can think of frames as <iframe> elements. Just like iframes, frames can be nested, and when JavaScript is executed in a frame, the JavaScript does not effect frames inside the ambient frame the JavaScript executes in.

| +| [HTTPRequest](./puppeteer.httprequest.md) | Represents an HTTP request sent by a page. | +| [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. | +| [JSCoverage](./puppeteer.jscoverage.md) | | +| [JSHandle](./puppeteer.jshandle.md) |

Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).

Handles prevent the referenced JavaScript object from being garbage-collected unless the handle is purposely [disposed](./puppeteer.jshandle.dispose.md). JSHandles are auto-disposed when their associated frame is navigated away or the parent context gets destroyed.

Handles can be used as arguments for any evaluation function such as [Page.$eval()](./puppeteer.page._eval.md), [Page.evaluate()](./puppeteer.page.evaluate.md), and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md). They are resolved to their referenced object.

| +| [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. | +| [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.

:::note

One Browser instance might have multiple Page instances.

:::

| +| [ProtocolError](./puppeteer.protocolerror.md) | ProtocolError is emitted whenever there is an error from the protocol. | +| [Puppeteer](./puppeteer.puppeteer.md) |

The main Puppeteer class.

IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require puppeteer. That class extends Puppeteer, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).

| +| [PuppeteerNode](./puppeteer.puppeteernode.md) |

Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.

If you're using Puppeteer in a Node environment, this is the class you'll get when you run require('puppeteer') (or the equivalent ES import).

| +| [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. | +| [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | +| [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | +| [WebWorker](./puppeteer.webworker.md) | This class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | ## Enumerations diff --git a/docs/api/puppeteer.elementhandle.waitforselector.md b/docs/api/puppeteer.elementhandle.waitforselector.md index 5f905d1715d6a..2b41e310922ac 100644 --- a/docs/api/puppeteer.elementhandle.waitforselector.md +++ b/docs/api/puppeteer.elementhandle.waitforselector.md @@ -14,17 +14,17 @@ Unlike [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md), this met class ElementHandle { waitForSelector( selector: Selector, - options?: Exclude + options?: WaitForSelectorOptions ): Promise> | null>; } ``` ## Parameters -| Parameter | Type | Description | -| --------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -| selector | Selector | The selector to query and wait for. | -| options | Exclude<[WaitForSelectorOptions](./puppeteer.waitforselectoroptions.md), 'root'> | (Optional) Options for customizing waiting behavior. | +| Parameter | Type | Description | +| --------- | --------------------------------------------------------------- | ----------------------------------------------------------- | +| selector | Selector | The selector to query and wait for. | +| options | [WaitForSelectorOptions](./puppeteer.waitforselectoroptions.md) | (Optional) Options for customizing waiting behavior. | **Returns:** diff --git a/docs/api/puppeteer.executioncontext.evaluate.md b/docs/api/puppeteer.executioncontext.evaluate.md deleted file mode 100644 index 549997871f57f..0000000000000 --- a/docs/api/puppeteer.executioncontext.evaluate.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -sidebar_label: ExecutionContext.evaluate ---- - -# ExecutionContext.evaluate() method - -Evaluates the given function. - -**Signature:** - -```typescript -class ExecutionContext { - evaluate< - Params extends unknown[], - Func extends EvaluateFunc = EvaluateFunc - >( - pageFunction: Func | string, - ...args: Params - ): Promise>>; -} -``` - -## Parameters - -| Parameter | Type | Description | -| ------------ | -------------- | ----------------------------------------------- | -| pageFunction | Func \| string | The function to evaluate. | -| args | Params | Additional arguments to pass into the function. | - -**Returns:** - -Promise<Awaited<ReturnType<Func>>> - -The result of evaluating the function. If the result is an object, a vanilla object containing the serializable properties of the result is returned. - -## Example 1 - -```ts -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: - -```ts -console.log(await executionContext.evaluate('1 + 2')); // prints "3" -``` - -## Example 3 - -Handles can also be passed as `args`. They resolve to their referenced object: - -```ts -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/docs/api/puppeteer.executioncontext.evaluatehandle.md b/docs/api/puppeteer.executioncontext.evaluatehandle.md deleted file mode 100644 index d35dcfa9660f0..0000000000000 --- a/docs/api/puppeteer.executioncontext.evaluatehandle.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -sidebar_label: ExecutionContext.evaluateHandle ---- - -# ExecutionContext.evaluateHandle() method - -Evaluates the given function. - -Unlike [evaluate](./puppeteer.executioncontext.evaluate.md), this method returns a handle to the result of the function. - -This method may be better suited if the object cannot be serialized (e.g. `Map`) and requires further manipulation. - -**Signature:** - -```typescript -class ExecutionContext { - evaluateHandle< - Params extends unknown[], - Func extends EvaluateFunc = EvaluateFunc - >( - pageFunction: Func | string, - ...args: Params - ): Promise>>>; -} -``` - -## Parameters - -| Parameter | Type | Description | -| ------------ | -------------- | ----------------------------------------------- | -| pageFunction | Func \| string | The function to evaluate. | -| args | Params | Additional arguments to pass into the function. | - -**Returns:** - -Promise<[HandleFor](./puppeteer.handlefor.md)<Awaited<ReturnType<Func>>>> - -A [handle](./puppeteer.jshandle.md) to the result of evaluating the function. If the result is a `Node`, then this will return an [element handle](./puppeteer.elementhandle.md). - -## Example 1 - -```ts -const context = await page.mainFrame().executionContext(); -const handle: JSHandle = await context.evaluateHandle(() => - Promise.resolve(self) -); -``` - -## Example 2 - -A string can also be passed in instead of a function. - -```ts -const handle: JSHandle = await context.evaluateHandle('1 + 2'); -``` - -## Example 3 - -Handles can also be passed as `args`. They resolve to their referenced object: - -```ts -const bodyHandle: ElementHandle = await context.evaluateHandle( - () => { - return document.body; - } -); -const stringHandle: JSHandle = await context.evaluateHandle( - body => body.innerHTML, - body -); -console.log(await stringHandle.jsonValue()); // prints body's innerHTML -// Always dispose your garbage! :) -await bodyHandle.dispose(); -await stringHandle.dispose(); -``` diff --git a/docs/api/puppeteer.executioncontext.frame.md b/docs/api/puppeteer.executioncontext.frame.md deleted file mode 100644 index 07afe93bd4701..0000000000000 --- a/docs/api/puppeteer.executioncontext.frame.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: ExecutionContext.frame ---- - -# ExecutionContext.frame() method - -**Signature:** - -```typescript -class ExecutionContext { - frame(): Frame | null; -} -``` - -**Returns:** - -[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](./puppeteer.webworker.md) have execution contexts that are not associated with frames. diff --git a/docs/api/puppeteer.executioncontext.md b/docs/api/puppeteer.executioncontext.md deleted file mode 100644 index 551673050f184..0000000000000 --- a/docs/api/puppeteer.executioncontext.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: ExecutionContext ---- - -# ExecutionContext class - -Represents a context for JavaScript execution. - -**Signature:** - -```typescript -export declare class ExecutionContext -``` - -## Remarks - -Besides pages, execution contexts can be found in [workers](./puppeteer.webworker.md). - -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. - -## Example - -A [Page](./puppeteer.page.md) can have several execution contexts: - -- Each [Frame](./puppeteer.frame.md) of a [page](./puppeteer.page.md) has a "default" execution context that is always created after frame is attached to DOM. This context is returned by the [Frame.executionContext()](./puppeteer.frame.executioncontext.md) method. - Each [Chrome extensions](https://developer.chrome.com/extensions) creates additional execution contexts to isolate their code. - -## Methods - -| Method | Modifiers | Description | -| ------------------------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [evaluate(pageFunction, args)](./puppeteer.executioncontext.evaluate.md) | | Evaluates the given function. | -| [evaluateHandle(pageFunction, args)](./puppeteer.executioncontext.evaluatehandle.md) | |

Evaluates the given function.

Unlike [evaluate](./puppeteer.executioncontext.evaluate.md), this method returns a handle to the result of the function.

This method may be better suited if the object cannot be serialized (e.g. Map) and requires further manipulation.

| -| [frame()](./puppeteer.executioncontext.frame.md) | | | -| [queryObjects(prototypeHandle)](./puppeteer.executioncontext.queryobjects.md) | | Iterates through the JavaScript heap and finds all the objects with the given prototype. | diff --git a/docs/api/puppeteer.executioncontext.queryobjects.md b/docs/api/puppeteer.executioncontext.queryobjects.md deleted file mode 100644 index 8b55d68b0ceb3..0000000000000 --- a/docs/api/puppeteer.executioncontext.queryobjects.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -sidebar_label: ExecutionContext.queryObjects ---- - -# ExecutionContext.queryObjects() method - -Iterates through the JavaScript heap and finds all the objects with the given prototype. - -**Signature:** - -```typescript -class ExecutionContext { - queryObjects( - prototypeHandle: JSHandle - ): Promise>; -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------------- | ---------------------------------------------------- | -------------------------------- | -| prototypeHandle | [JSHandle](./puppeteer.jshandle.md)<Prototype> | a handle to the object prototype | - -**Returns:** - -Promise<[HandleFor](./puppeteer.handlefor.md)<Prototype\[\]>> - -A handle to an array of objects with the given prototype. - -## Example - -```ts -// 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/docs/api/puppeteer.frame.evaluate.md b/docs/api/puppeteer.frame.evaluate.md index 400f752f67773..9804c36a00225 100644 --- a/docs/api/puppeteer.frame.evaluate.md +++ b/docs/api/puppeteer.frame.evaluate.md @@ -22,10 +22,10 @@ class Frame { ## Parameters -| Parameter | Type | Description | -| ------------ | -------------- | ------------------------------------------ | -| pageFunction | Func \| string | a function that is run within the frame | -| args | Params | arguments to be passed to the pageFunction | +| Parameter | Type | Description | +| ------------ | -------------- | ----------- | +| pageFunction | Func \| string | | +| args | Params | | **Returns:** diff --git a/docs/api/puppeteer.frame.evaluatehandle.md b/docs/api/puppeteer.frame.evaluatehandle.md index b9ea0d8294e67..0532cf177a9b8 100644 --- a/docs/api/puppeteer.frame.evaluatehandle.md +++ b/docs/api/puppeteer.frame.evaluatehandle.md @@ -22,10 +22,10 @@ class Frame { ## Parameters -| Parameter | Type | Description | -| ------------ | -------------- | ------------------------------------------ | -| pageFunction | Func \| string | a function that is run within the frame | -| args | Params | arguments to be passed to the pageFunction | +| Parameter | Type | Description | +| ------------ | -------------- | ----------- | +| pageFunction | Func \| string | | +| args | Params | | **Returns:** diff --git a/docs/api/puppeteer.frame.executioncontext.md b/docs/api/puppeteer.frame.executioncontext.md deleted file mode 100644 index cb6c95555bb51..0000000000000 --- a/docs/api/puppeteer.frame.executioncontext.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_label: Frame.executionContext ---- - -# Frame.executionContext() method - -**Signature:** - -```typescript -class Frame { - executionContext(): Promise; -} -``` - -**Returns:** - -Promise<[ExecutionContext](./puppeteer.executioncontext.md)> - -a promise that resolves to the frame's default execution context. diff --git a/docs/api/puppeteer.frame.isoopframe.md b/docs/api/puppeteer.frame.isoopframe.md index 323e2c10a7fba..c818d8a2f6b15 100644 --- a/docs/api/puppeteer.frame.isoopframe.md +++ b/docs/api/puppeteer.frame.isoopframe.md @@ -16,4 +16,4 @@ class Frame { boolean -`true` if the frame is an OOP frame, or `false` otherwise. +`true` if the frame is an out-of-process (OOP) frame. Otherwise, `false`. diff --git a/docs/api/puppeteer.frame.md b/docs/api/puppeteer.frame.md index c8732d22e1db1..0d94f79992ce3 100644 --- a/docs/api/puppeteer.frame.md +++ b/docs/api/puppeteer.frame.md @@ -4,7 +4,9 @@ sidebar_label: Frame # Frame class -At every point of time, page exposes its current frame tree via the [page.mainFrame](./puppeteer.page.mainframe.md) and [frame.childFrames](./puppeteer.frame.childframes.md) methods. +Represents a DOM frame. + +To understand frames, you can think of frames as `