Skip to content

Commit

Permalink
fix: deprecate ExecutionContext (#8792)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jrandolf
jrandolf committed Aug 16, 2022
1 parent 90aa628 commit b5da718
Show file tree
Hide file tree
Showing 11 changed files with 57 additions and 33 deletions.
4 changes: 2 additions & 2 deletions docs/api/index.md
View file
Expand Up @@ -21,9 +21,9 @@ sidebar_label: API
| [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the <code>dialog</code> 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. |
| [ExecutionContext](./puppeteer.executioncontext.md) | |
| [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. |
| [Frame](./puppeteer.frame.md) | <p>Represents a DOM frame.</p><p>To understand frames, you can think of frames as <code>&lt;iframe&gt;</code> 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.</p> |
| [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) | |
Expand Down
6 changes: 5 additions & 1 deletion docs/api/puppeteer.executioncontext.md
View file
Expand Up @@ -4,7 +4,11 @@ sidebar_label: ExecutionContext

# ExecutionContext class

Represents a context for JavaScript execution.
> Warning: This API is now obsolete.
>
> Do not use directly.
>
> Represents a context for JavaScript execution.
**Signature:**

Expand Down
8 changes: 4 additions & 4 deletions docs/api/puppeteer.frame.evaluate.md
View file
Expand Up @@ -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:**

Expand Down
8 changes: 4 additions & 4 deletions docs/api/puppeteer.frame.evaluatehandle.md
View file
Expand Up @@ -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:**

Expand Down
4 changes: 4 additions & 0 deletions docs/api/puppeteer.frame.executioncontext.md
View file
Expand Up @@ -4,6 +4,10 @@ sidebar_label: Frame.executionContext

# Frame.executionContext() method

> Warning: This API is now obsolete.
>
> Do not use the execution context directly.
**Signature:**

```typescript
Expand Down
2 changes: 1 addition & 1 deletion docs/api/puppeteer.frame.isoopframe.md
View file
Expand Up @@ -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`.
14 changes: 10 additions & 4 deletions docs/api/puppeteer.frame.md
View file
Expand Up @@ -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 `<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.

**Signature:**

Expand All @@ -14,14 +16,18 @@ export declare class Frame

## Remarks

`Frame` object lifecycles are controlled by three events that are all dispatched on the page object:
Frame lifecycles are controlled by three events that are all dispatched on the parent [page](./puppeteer.frame.page.md):

- [PageEmittedEvents.FrameAttached](./puppeteer.pageemittedevents.md) - [PageEmittedEvents.FrameNavigated](./puppeteer.pageemittedevents.md) - [PageEmittedEvents.FrameDetached](./puppeteer.pageemittedevents.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 `Frame` class.

## Example 1

At any point in time, [pages](./puppeteer.page.md) expose their current frame tree via the [Page.mainFrame()](./puppeteer.page.mainframe.md) and [Frame.childFrames()](./puppeteer.frame.childframes.md) methods.

## Example 2

An example of dumping frame tree:

```ts
Expand All @@ -43,7 +49,7 @@ const puppeteer = require('puppeteer');
})();
```

## Example 2
## Example 3

An example of getting text from an iframe element:

Expand Down Expand Up @@ -86,6 +92,6 @@ console.log(text);
| [url()](./puppeteer.frame.url.md) | | |
| [waitForFunction(pageFunction, options, args)](./puppeteer.frame.waitforfunction.md) | | |
| [waitForNavigation(options)](./puppeteer.frame.waitfornavigation.md) | | <p>Waits for the frame to navigate. It is useful for when you run code which will indirectly cause the frame to navigate.</p><p>Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is considered a navigation.</p> |
| [waitForSelector(selector, options)](./puppeteer.frame.waitforselector.md) | | <p>Wait for an element matching the given selector to appear in the frame.</p><p>This method works across navigations.</p> |
| [waitForSelector(selector, options)](./puppeteer.frame.waitforselector.md) | | <p>Waits for an element matching the given selector to appear in the frame.</p><p>This method works across navigations.</p> |
| [waitForTimeout(milliseconds)](./puppeteer.frame.waitfortimeout.md) | | Causes your script to wait for the given number of milliseconds. |
| [waitForXPath(xpath, options)](./puppeteer.frame.waitforxpath.md) | | |
2 changes: 1 addition & 1 deletion docs/api/puppeteer.frame.waitforselector.md
View file
Expand Up @@ -4,7 +4,7 @@ sidebar_label: Frame.waitForSelector

# Frame.waitForSelector() method

Wait for an element matching the given selector to appear in the frame.
Waits for an element matching the given selector to appear in the frame.

This method works across navigations.

Expand Down
2 changes: 1 addition & 1 deletion package-lock.json
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions src/common/ExecutionContext.ts
View file
Expand Up @@ -35,6 +35,8 @@ 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
Expand Down
38 changes: 23 additions & 15 deletions src/common/FrameManager.ts
View file
Expand Up @@ -602,17 +602,16 @@ export interface FrameAddStyleTagOptions {
}

/**
* At every point of time, page exposes its current frame tree via the
* {@link Page.mainFrame | page.mainFrame} and
* {@link Frame.childFrames | frame.childFrames} methods.
* Represents a DOM frame.
*
* @remarks
* `Frame` object lifecycles are controlled by three events that are all
* dispatched on the page object:
* 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.
*
* - {@link PageEmittedEvents.FrameAttached}
* - {@link PageEmittedEvents.FrameNavigated}
* - {@link PageEmittedEvents.FrameDetached}
* @example
* At any point in time, {@link Page | pages} expose their current frame
* tree via the {@link Page.mainFrame} and {@link Frame.childFrames} methods.
*
* @example
* An example of dumping frame tree:
Expand Down Expand Up @@ -645,6 +644,14 @@ export interface FrameAddStyleTagOptions {
* console.log(text);
* ```
*
* @remarks
* Frame lifecycles are controlled by three events that are all dispatched on
* the parent {@link Frame.page | page}:
*
* - {@link PageEmittedEvents.FrameAttached}
* - {@link PageEmittedEvents.FrameNavigated}
* - {@link PageEmittedEvents.FrameDetached}
*
* @public
*/
export class Frame {
Expand Down Expand Up @@ -740,7 +747,8 @@ export class Frame {
}

/**
* @returns `true` if the frame is an OOP frame, or `false` otherwise.
* @returns `true` if the frame is an out-of-process (OOP) frame. Otherwise,
* `false`.
*/
isOOPFrame(): boolean {
return this.#client !== this._frameManager.client;
Expand Down Expand Up @@ -915,6 +923,8 @@ export class Frame {
}

/**
* @deprecated Do not use the execution context directly.
*
* @returns a promise that resolves to the frame's default execution context.
*/
executionContext(): Promise<ExecutionContext> {
Expand All @@ -925,8 +935,7 @@ export class Frame {
* Behaves identically to {@link Page.evaluateHandle} except it's run within
* the context of this frame.
*
* @param pageFunction - a function that is run within the frame
* @param args - arguments to be passed to the pageFunction
* @see {@link Page.evaluateHandle} for details.
*/
async evaluateHandle<
Params extends unknown[],
Expand All @@ -942,8 +951,7 @@ export class Frame {
* Behaves identically to {@link Page.evaluate} except it's run within the
* the context of this frame.
*
* @param pageFunction - a function that is run within the frame
* @param args - arguments to be passed to the pageFunction
* @see {@link Page.evaluate} for details.
*/
async evaluate<
Params extends unknown[],
Expand Down Expand Up @@ -1060,7 +1068,7 @@ export class Frame {
}

/**
* Wait for an element matching the given selector to appear in the frame.
* Waits for an element matching the given selector to appear in the frame.
*
* This method works across navigations.
*
Expand Down

0 comments on commit b5da718

Please sign in to comment.