diff --git a/new-docs/puppeteer.boxmodel.md b/new-docs/puppeteer.boxmodel.md index ffdd69fa..04414d0a 100644 --- a/new-docs/puppeteer.boxmodel.md +++ b/new-docs/puppeteer.boxmodel.md @@ -4,7 +4,6 @@ ## BoxModel interface - Signature: ```typescript diff --git a/new-docs/puppeteer.elementhandle._.md b/new-docs/puppeteer.elementhandle._.md index 6be4b5ec..a6d0df97 100644 --- a/new-docs/puppeteer.elementhandle._.md +++ b/new-docs/puppeteer.elementhandle._.md @@ -4,7 +4,7 @@ ## ElementHandle.$() method -The method runs `element.querySelector` within the page. If no element matches the selector, the return value resolves to `null`. +Runs `element.querySelector` within the page. If no element matches the selector, the return value resolves to `null`. Signature: diff --git a/new-docs/puppeteer.elementhandle.__.md b/new-docs/puppeteer.elementhandle.__.md index 34bfb509..41c9843b 100644 --- a/new-docs/puppeteer.elementhandle.__.md +++ b/new-docs/puppeteer.elementhandle.__.md @@ -4,7 +4,7 @@ ## ElementHandle.$$() method -The method runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`. +Runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`. Signature: diff --git a/new-docs/puppeteer.elementhandle.md b/new-docs/puppeteer.elementhandle.md index a28c12de..9d479637 100644 --- a/new-docs/puppeteer.elementhandle.md +++ b/new-docs/puppeteer.elementhandle.md @@ -30,7 +30,7 @@ const puppeteer = require('puppeteer'); })(); ``` -ElementHandle prevents DOM element from garbage collection unless the handle is [disposed](./puppeteer.jshandle.dispose.md). ElementHandles are auto-disposed when their origin frame gets navigated. +ElementHandle prevents the DOM element from being garbage-collected unless the handle is [disposed](./puppeteer.jshandle.dispose.md). ElementHandles are auto-disposed when their origin frame gets navigated. ElementHandle instances can be used as arguments in [Page.$eval()](./puppeteer.page._eval.md) and [Page.evaluate()](./puppeteer.page.evaluate.md) methods. @@ -40,8 +40,8 @@ The constructor for this class is marked as internal. Third-party code should no | Method | Modifiers | Description | | --- | --- | --- | -| [$(selector)](./puppeteer.elementhandle._.md) | | The method runs element.querySelector within the page. If no element matches the selector, the return value resolves to null. | -| [$$(selector)](./puppeteer.elementhandle.__.md) | | The method runs element.querySelectorAll within the page. If no elements match the selector, the return value resolves to []. | +| [$(selector)](./puppeteer.elementhandle._.md) | | Runs element.querySelector within the page. If no element matches the selector, the return value resolves to null. | +| [$$(selector)](./puppeteer.elementhandle.__.md) | | Runs element.querySelectorAll within the page. If no elements match the selector, the return value resolves to []. | | [$$eval(selector, pageFunction, args)](./puppeteer.elementhandle.__eval.md) | | This method runs document.querySelectorAll within the element and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.If pageFunction returns a Promise, then frame.$$eval would wait for the promise to resolve and return its value. | | [$eval(selector, pageFunction, args)](./puppeteer.elementhandle._eval.md) | | This method runs document.querySelector within the element and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.If pageFunction returns a Promise, then frame.$eval would wait for the promise to resolve and return its value. | | [$x(expression)](./puppeteer.elementhandle._x.md) | | The method evaluates the XPath expression relative to the elementHandle. If there are no such elements, the method will resolve to an empty array. | diff --git a/new-docs/puppeteer.jshandle.aselement.md b/new-docs/puppeteer.jshandle.aselement.md index 87cc90ca..1f2b3517 100644 --- a/new-docs/puppeteer.jshandle.aselement.md +++ b/new-docs/puppeteer.jshandle.aselement.md @@ -4,6 +4,8 @@ ## JSHandle.asElement() method +Returns either `null` or the object handle itself, if the object handle is an instance of [ElementHandle](./puppeteer.elementhandle.md). + Signature: ```typescript diff --git a/new-docs/puppeteer.jshandle.dispose.md b/new-docs/puppeteer.jshandle.dispose.md index e2db3690..869eb0e7 100644 --- a/new-docs/puppeteer.jshandle.dispose.md +++ b/new-docs/puppeteer.jshandle.dispose.md @@ -4,7 +4,7 @@ ## JSHandle.dispose() method -The method stops referencing the element handle. +Stops referencing the element handle, and resolves when the object handle is successfully disposed of. Signature: diff --git a/new-docs/puppeteer.jshandle.evaluatehandle.md b/new-docs/puppeteer.jshandle.evaluatehandle.md index d30cffdd..46078670 100644 --- a/new-docs/puppeteer.jshandle.evaluatehandle.md +++ b/new-docs/puppeteer.jshandle.evaluatehandle.md @@ -25,9 +25,9 @@ Promise<[JSHandle](./puppeteer.jshandle.md)> ## Remarks -The only difference between `evaluateHandle.evaluate` and `evaluateHandle.evaluateHandle` is that `executionContext.evaluateHandle` returns in-page object (JSHandle). +The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle` returns an in-page object (JSHandle). -If the function passed to the `evaluateHandle.evaluateHandle` returns a Promise, then `evaluateHandle.evaluateHandle` would wait for the promise to resolve and return its value. +If the function passed to `jsHandle.evaluateHandle` returns a Promise, then `evaluateHandle.evaluateHandle` waits for the promise to resolve and returns its value. See [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md) for more details. diff --git a/new-docs/puppeteer.jshandle.executioncontext.md b/new-docs/puppeteer.jshandle.executioncontext.md index ed5afb14..462cccf7 100644 --- a/new-docs/puppeteer.jshandle.executioncontext.md +++ b/new-docs/puppeteer.jshandle.executioncontext.md @@ -4,6 +4,8 @@ ## JSHandle.executionContext() method +Returns the execution context the handle belongs to. + Signature: ```typescript diff --git a/new-docs/puppeteer.jshandle.getproperty.md b/new-docs/puppeteer.jshandle.getproperty.md index 589f4fef..5cea2206 100644 --- a/new-docs/puppeteer.jshandle.getproperty.md +++ b/new-docs/puppeteer.jshandle.getproperty.md @@ -4,6 +4,8 @@ ## JSHandle.getProperty() method +Fetches a single property from the referenced object. + Signature: ```typescript diff --git a/new-docs/puppeteer.jshandle.jsonvalue.md b/new-docs/puppeteer.jshandle.jsonvalue.md index aeef8ef1..2cdac0b4 100644 --- a/new-docs/puppeteer.jshandle.jsonvalue.md +++ b/new-docs/puppeteer.jshandle.jsonvalue.md @@ -17,5 +17,5 @@ Promise<{}> ## Remarks -The JSON is generated by running [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on the object in page and consequent [JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) in puppeteer. \*\*NOTE\*\* The method will throw if the referenced object is not stringifiable. +The JSON is generated by running [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on the object in page and consequent [JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) in puppeteer. \*\*NOTE\*\* The method throws if the referenced object is not stringifiable. diff --git a/new-docs/puppeteer.jshandle.md b/new-docs/puppeteer.jshandle.md index afe76f97..97ad93dd 100644 --- a/new-docs/puppeteer.jshandle.md +++ b/new-docs/puppeteer.jshandle.md @@ -4,6 +4,7 @@ ## JSHandle class +Represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle](./puppeteer.page.evaluatehandle.md) method. Signature: @@ -11,6 +12,17 @@ export declare class JSHandle ``` +## Example + + +```js +const windowHandle = await page.evaluateHandle(() => window); + +``` +JSHandle prevents the referenced JavaScript object from being garbage-collected unless the handle is [disposed](./puppeteer.jshandle.dispose.md). JSHandles are auto- disposed when their origin frame gets navigated or the parent context gets destroyed. + +JSHandle instances can be used as arguments for [Page.$eval()](./puppeteer.page._eval.md), [Page.evaluate()](./puppeteer.page.evaluate.md), and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md). + ## Constructors | Constructor | Modifiers | Description | @@ -30,13 +42,13 @@ export declare class JSHandle | Method | Modifiers | Description | | --- | --- | --- | -| [asElement()](./puppeteer.jshandle.aselement.md) | | | -| [dispose()](./puppeteer.jshandle.dispose.md) | | The method stops referencing the element handle. | +| [asElement()](./puppeteer.jshandle.aselement.md) | | Returns either null or the object handle itself, if the object handle is an instance of [ElementHandle](./puppeteer.elementhandle.md). | +| [dispose()](./puppeteer.jshandle.dispose.md) | | Stops referencing the element handle, and resolves when the object handle is successfully disposed of. | | [evaluate(pageFunction, args)](./puppeteer.jshandle.evaluate.md) | | This method passes this handle as the first argument to pageFunction. If pageFunction returns a Promise, then handle.evaluate would wait for the promise to resolve and return its value. | | [evaluateHandle(pageFunction, args)](./puppeteer.jshandle.evaluatehandle.md) | | This method passes this handle as the first argument to pageFunction. | -| [executionContext()](./puppeteer.jshandle.executioncontext.md) | | | +| [executionContext()](./puppeteer.jshandle.executioncontext.md) | | Returns the execution context the handle belongs to. | | [getProperties()](./puppeteer.jshandle.getproperties.md) | | The method returns a map with property names as keys and JSHandle instances for the property values. | -| [getProperty(propertyName)](./puppeteer.jshandle.getproperty.md) | | | +| [getProperty(propertyName)](./puppeteer.jshandle.getproperty.md) | | Fetches a single property from the referenced object. | | [jsonValue()](./puppeteer.jshandle.jsonvalue.md) | | Returns a JSON representation of the object. | -| [toString()](./puppeteer.jshandle.tostring.md) | | | +| [toString()](./puppeteer.jshandle.tostring.md) | | Returns a string representation of the JSHandle. | diff --git a/new-docs/puppeteer.jshandle.tostring.md b/new-docs/puppeteer.jshandle.tostring.md index e81349cd..2062ae6b 100644 --- a/new-docs/puppeteer.jshandle.tostring.md +++ b/new-docs/puppeteer.jshandle.tostring.md @@ -4,6 +4,8 @@ ## JSHandle.toString() method +Returns a string representation of the JSHandle. + Signature: ```typescript @@ -13,3 +15,7 @@ toString(): string; string +## Remarks + +Useful during debugging. + diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 200dab24..98969e96 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -25,7 +25,7 @@ | [FrameManager](./puppeteer.framemanager.md) | | | [HTTPRequest](./puppeteer.httprequest.md) | | | [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. | -| [JSHandle](./puppeteer.jshandle.md) | | +| [JSHandle](./puppeteer.jshandle.md) | Represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle](./puppeteer.page.evaluatehandle.md) method. | | [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. One \[Browser\] instance might have multiple \[Page\] instances. | diff --git a/src/common/JSHandle.ts b/src/common/JSHandle.ts index 2a8f0265..7d37bf0a 100644 --- a/src/common/JSHandle.ts +++ b/src/common/JSHandle.ts @@ -29,9 +29,6 @@ import { EvaluateFnReturnType, } from './EvalTypes'; -/** - * @public - */ export interface BoxModel { content: Array<{ x: number; y: number }>; padding: Array<{ x: number; y: number }>; @@ -85,6 +82,21 @@ export function createJSHandle( } /** + * Represents an in-page JavaScript object. JSHandles can be created with the + * {@link Page.evaluateHandle | page.evaluateHandle} method. + * + * @example + * ```js + * const windowHandle = await page.evaluateHandle(() => window); + * ``` + * + * JSHandle prevents the referenced JavaScript object from being garbage-collected + * unless the handle is {@link JSHandle.dispose | disposed}. JSHandles are auto- + * disposed when their origin frame gets navigated or the parent context gets destroyed. + * + * JSHandle instances can be used as arguments for {@link Page.$eval}, + * {@link Page.evaluate}, and {@link Page.evaluateHandle}. + * * @public */ export class JSHandle { @@ -103,6 +115,8 @@ export class JSHandle { this._remoteObject = remoteObject; } + /** Returns the execution context the handle belongs to. + */ executionContext(): ExecutionContext { return this._context; } @@ -135,13 +149,13 @@ export class JSHandle { * * @remarks * - * The only difference between `evaluateHandle.evaluate` and - * `evaluateHandle.evaluateHandle` is that `executionContext.evaluateHandle` - * returns in-page object (JSHandle). + * The only difference between `jsHandle.evaluate` and + * `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle` + * returns an in-page object (JSHandle). * - * If the function passed to the `evaluateHandle.evaluateHandle` returns a Promise, - * then `evaluateHandle.evaluateHandle` would wait for the promise to resolve and - * return its value. + * If the function passed to `jsHandle.evaluateHandle` returns a Promise, + * then `evaluateHandle.evaluateHandle` waits for the promise to resolve and + * returns its value. * * See {@link Page.evaluateHandle} for more details. */ @@ -156,6 +170,8 @@ export class JSHandle { ); } + /** Fetches a single property from the referenced object. + */ async getProperty(propertyName: string): Promise { const objectHandle = await this.evaluateHandle( (object: HTMLElement, propertyName: string) => { @@ -208,7 +224,7 @@ export class JSHandle { * * The JSON is generated by running {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify | JSON.stringify} * on the object in page and consequent {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse} in puppeteer. - * **NOTE** The method will throw if the referenced object is not stringifiable. + * **NOTE** The method throws if the referenced object is not stringifiable. */ async jsonValue(): Promise<{}> { if (this._remoteObject.objectId) { @@ -223,13 +239,19 @@ export class JSHandle { return helper.valueFromRemoteObject(this._remoteObject); } - /* This always returns null but children can define this and return an ElementHandle */ + /** + * Returns either `null` or the object handle itself, if the object handle is + * an instance of {@link ElementHandle}. + */ asElement(): ElementHandle | null { + // This always returns null, but subclasses can override this and return an + // ElementHandle. return null; } /** - * The method stops referencing the element handle. + * Stops referencing the element handle, and resolves when the object handle is + * successfully disposed of. */ async dispose(): Promise { if (this._disposed) return; @@ -237,6 +259,11 @@ export class JSHandle { await helper.releaseObject(this._client, this._remoteObject); } + /** + * Returns a string representation of the JSHandle. + * + * @remarks Useful during debugging. + */ toString(): string { if (this._remoteObject.objectId) { const type = this._remoteObject.subtype || this._remoteObject.type; @@ -266,9 +293,9 @@ export class JSHandle { * })(); * ``` * - * ElementHandle prevents DOM element from garbage collection unless the handle is - * {@link JSHandle.dispose | disposed}. ElementHandles are auto-disposed when their - * origin frame gets navigated. + * ElementHandle prevents the DOM element from being garbage-collected unless the + * handle is {@link JSHandle.dispose | disposed}. ElementHandles are auto-disposed + * when their origin frame gets navigated. * * ElementHandle instances can be used as arguments in {@link Page.$eval} and * {@link Page.evaluate} methods. @@ -719,8 +746,8 @@ export class ElementHandle extends JSHandle { } /** - * The method runs `element.querySelector` within the page. If no element matches - * the selector, the return value resolves to `null`. + * Runs `element.querySelector` within the page. If no element matches the selector, + * the return value resolves to `null`. */ async $(selector: string): Promise { const defaultHandler = (element: Element, selector: string) => @@ -738,8 +765,8 @@ export class ElementHandle extends JSHandle { } /** - * The method runs `element.querySelectorAll` within the page. If no elements match - * the selector, the return value resolves to `[]`. + * Runs `element.querySelectorAll` within the page. If no elements match the selector, + * the return value resolves to `[]`. */ async $$(selector: string): Promise { const defaultHandler = (element: Element, selector: string) =>