From 2f33237d0443de77d58dca4454b0c9a1d2b57d03 Mon Sep 17 00:00:00 2001
From: jrandolf <101637635+jrandolf@users.noreply.github.com>
Date: Thu, 25 Aug 2022 17:02:44 +0200
Subject: [PATCH] fix!: internalize execution context (#8844)
---
docs/api/index.md | 67 ++++++++---------
.../puppeteer.executioncontext.evaluate.md | 67 -----------------
...ppeteer.executioncontext.evaluatehandle.md | 75 -------------------
docs/api/puppeteer.executioncontext.frame.md | 23 ------
docs/api/puppeteer.executioncontext.md | 38 ----------
...puppeteer.executioncontext.queryobjects.md | 44 -----------
docs/api/puppeteer.frame.executioncontext.md | 23 ------
docs/api/puppeteer.frame.md | 1 -
.../puppeteer.jshandle.executioncontext.md | 19 -----
docs/api/puppeteer.jshandle.md | 1 -
docs/api/puppeteer.page.queryobjects.md | 4 -
.../puppeteer.webworker.executioncontext.md | 23 ------
docs/api/puppeteer.webworker.md | 1 -
src/common/ExecutionContext.ts | 4 +-
src/common/Frame.ts | 4 +-
src/common/JSHandle.ts | 2 +-
src/common/Page.ts | 16 ++--
src/common/WebWorker.ts | 4 +-
18 files changed, 48 insertions(+), 368 deletions(-)
delete mode 100644 docs/api/puppeteer.executioncontext.evaluate.md
delete mode 100644 docs/api/puppeteer.executioncontext.evaluatehandle.md
delete mode 100644 docs/api/puppeteer.executioncontext.frame.md
delete mode 100644 docs/api/puppeteer.executioncontext.md
delete mode 100644 docs/api/puppeteer.executioncontext.queryobjects.md
delete mode 100644 docs/api/puppeteer.frame.executioncontext.md
delete mode 100644 docs/api/puppeteer.jshandle.executioncontext.md
delete mode 100644 docs/api/puppeteer.webworker.executioncontext.md
diff --git a/docs/api/index.md b/docs/api/index.md
index 8a4e32d92b336..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) | |
-| [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.
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).
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
).
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.
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).
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
).
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.
selector
. |
| [goto(url, options)](./puppeteer.frame.goto.md) | | Navigates a frame to the given url. |
| [hover(selector)](./puppeteer.frame.hover.md) | | Hovers the pointer over the center of the first element that matches the selector
. |
diff --git a/docs/api/puppeteer.jshandle.executioncontext.md b/docs/api/puppeteer.jshandle.executioncontext.md
deleted file mode 100644
index 60f9c0ee58751..0000000000000
--- a/docs/api/puppeteer.jshandle.executioncontext.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-sidebar_label: JSHandle.executionContext
----
-
-# JSHandle.executionContext() method
-
-**Signature:**
-
-```typescript
-class JSHandle {
- executionContext(): ExecutionContext;
-}
-```
-
-**Returns:**
-
-[ExecutionContext](./puppeteer.executioncontext.md)
-
-The execution context the handle belongs to.
diff --git a/docs/api/puppeteer.jshandle.md b/docs/api/puppeteer.jshandle.md
index cc1a3e5472682..450a4bc627b01 100644
--- a/docs/api/puppeteer.jshandle.md
+++ b/docs/api/puppeteer.jshandle.md
@@ -40,7 +40,6 @@ const windowHandle = await page.evaluateHandle(() => window);
| [dispose()](./puppeteer.jshandle.dispose.md) | | Releases the object referenced by the handle for garbage collection. |
| [evaluate(pageFunction, args)](./puppeteer.jshandle.evaluate.md) | | Evaluates the given function with the current handle as its first argument. |
| [evaluateHandle(pageFunction, args)](./puppeteer.jshandle.evaluatehandle.md) | | Evaluates the given function with the current handle as its first argument. |
-| [executionContext()](./puppeteer.jshandle.executioncontext.md) | | |
| [getProperties()](./puppeteer.jshandle.getproperties.md) | | Gets a map of handles representing the properties of the current handle. |
| [getProperty(propertyName)](./puppeteer.jshandle.getproperty.md) | | Fetches a single property from the referenced object. |
| [getProperty(propertyName)](./puppeteer.jshandle.getproperty_1.md) | | |
diff --git a/docs/api/puppeteer.page.queryobjects.md b/docs/api/puppeteer.page.queryobjects.md
index 60be51ac4671d..8bed1e0dbd20c 100644
--- a/docs/api/puppeteer.page.queryobjects.md
+++ b/docs/api/puppeteer.page.queryobjects.md
@@ -28,10 +28,6 @@ Promise<[JSHandle](./puppeteer.jshandle.md)<Prototype\[\]>>
Promise which resolves to a handle to an array of objects with this prototype.
-## Remarks
-
-Shortcut for [page.mainFrame().executionContext().queryObjects(prototypeHandle)](./puppeteer.executioncontext.queryobjects.md).
-
## Example
```ts
diff --git a/docs/api/puppeteer.webworker.executioncontext.md b/docs/api/puppeteer.webworker.executioncontext.md
deleted file mode 100644
index 1db00f6c6a457..0000000000000
--- a/docs/api/puppeteer.webworker.executioncontext.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-sidebar_label: WebWorker.executionContext
----
-
-# WebWorker.executionContext() method
-
-> Warning: This API is now obsolete.
->
-> Do not use directly.
-
-**Signature:**
-
-```typescript
-class WebWorker {
- executionContext(): Promiseworker.evaluate
returns a Promise, then worker.evaluate
would wait for the promise to resolve and return its value. If the function passed to the worker.evaluate
returns a non-serializable value, then worker.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. Shortcut for await worker.executionContext()).evaluate(pageFunction, ...args)
. |
| [evaluateHandle(pageFunction, args)](./puppeteer.webworker.evaluatehandle.md) | | The only difference between worker.evaluate
and worker.evaluateHandle
is that worker.evaluateHandle
returns in-page object (JSHandle). If the function passed to the worker.evaluateHandle
returns a Promise
, then worker.evaluateHandle
would wait for the promise to resolve and return its value. Shortcut for await worker.executionContext()).evaluateHandle(pageFunction, ...args)
|
-| [executionContext()](./puppeteer.webworker.executioncontext.md) | | |
| [url()](./puppeteer.webworker.url.md) | | |
diff --git a/src/common/ExecutionContext.ts b/src/common/ExecutionContext.ts
index 114652b0f8998..c4a1ef5136a82 100644
--- a/src/common/ExecutionContext.ts
+++ b/src/common/ExecutionContext.ts
@@ -35,8 +35,6 @@ export const EVALUATION_SCRIPT_URL = 'pptr://__puppeteer_evaluation_script__';
const SOURCE_URL_REGEX = /^[\040\t]*\/\/[@#] sourceURL=\s*(\S*?)\s*$/m;
/**
- * @deprecated Do not use directly.
- *
* Represents a context for JavaScript execution.
*
* @example
@@ -55,6 +53,8 @@ const SOURCE_URL_REGEX = /^[\040\t]*\/\/[@#] sourceURL=\s*(\S*?)\s*$/m;
* @remarks
* Besides pages, execution contexts can be found in
* {@link WebWorker | workers}.
+ *
+ * @internal
*/
export class ExecutionContext {
/**
diff --git a/src/common/Frame.ts b/src/common/Frame.ts
index 0c74b4206ff67..e48719aa1d08d 100644
--- a/src/common/Frame.ts
+++ b/src/common/Frame.ts
@@ -398,9 +398,7 @@ export class Frame {
}
/**
- * @deprecated Do not use the execution context directly.
- *
- * @returns a promise that resolves to the frame's default execution context.
+ * @internal
*/
executionContext(): Promise