github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(types): add (and fix) evaluateHandle types (#6130)

Browse Source 
This change started as a small change to pull types from DefinitelyTyped over to
Puppeteer for the `evaluateHandle` function but instead ended up also fixing
what looks to be a long standing issue with our existing documentation.

`evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`.
Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically
correct (all ElementHandles are JSHandles) it's confusing because JSHandles
don't have methods like `click` on them, but ElementHandles do.

if you return something that is an HTML element:

```
const button = page.evaluateHandle(() => document.querySelector('button'));
// this is an ElementHandle, not a JSHandle
```

Therefore I've updated the original docs and added a large explanation to the
TSDoc for `page.evaluateHandle`.

In TypeScript land we'll assume the function will return a `JSHandle` but you
can tell TS otherwise via the generic argument, which can only be `JSHandle`
(the default) or `ElementHandle`:

```
const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button'));
```
This commit is contained in:
Jack Franklin
2020-07-01 12:44:08 +01:00
committed by GitHub
parent 3c0dc45e47
commit 8370ec88ae
21 changed files with 235 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
new-docs/puppeteer.evaluatehandlefn.md Normal file
View File

@@ -0,0 +1,12 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [EvaluateHandleFn](./puppeteer.evaluatehandlefn.md)
## EvaluateHandleFn type
<b>Signature:</b>
```typescript
export declare type EvaluateHandleFn = string | ((...args: unknown[]) => unknown);
```

8
new-docs/puppeteer.executioncontext.evaluatehandle.md
View File

@@ -7,19 +7,19 @@
<b>Signature:</b>
```typescript
evaluateHandle(pageFunction: Function | string, ...args: unknown[]): Promise<JSHandle>;
evaluateHandle<HandleType extends JSHandle | ElementHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandleType>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| pageFunction | Function \| string | a function to be evaluated in the <code>executionContext</code> |
| args | unknown\[\] | argument to pass to the page function |
| pageFunction | [EvaluateHandleFn](./puppeteer.evaluatehandlefn.md) | a function to be evaluated in the <code>executionContext</code> |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | argument to pass to the page function |
<b>Returns:</b>
Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
Promise&lt;HandleType&gt;
A promise that resolves to the return value of the given function as an in-page object (a [JSHandle](./puppeteer.jshandle.md)<!-- -->).

8
new-docs/puppeteer.frame.evaluatehandle.md
View File

@@ -7,17 +7,17 @@
<b>Signature:</b>
```typescript
evaluateHandle(pageFunction: Function | string, ...args: unknown[]): Promise<JSHandle>;
evaluateHandle<HandlerType extends JSHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandlerType>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| pageFunction | Function \| string | |
| args | unknown\[\] | |
| pageFunction | [EvaluateHandleFn](./puppeteer.evaluatehandlefn.md) | |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | |
<b>Returns:</b>
Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
Promise&lt;HandlerType&gt;

4
new-docs/puppeteer.frame.waitfor.md
View File

@@ -7,7 +7,7 @@
<b>Signature:</b>
```typescript
waitFor(selectorOrFunctionOrTimeout: string | number | Function, options?: {}, ...args: unknown[]): Promise<JSHandle | null>;
waitFor(selectorOrFunctionOrTimeout: string | number | Function, options?: {}, ...args: SerializableOrJSHandle[]): Promise<JSHandle | null>;
```
## Parameters
@@ -16,7 +16,7 @@ waitFor(selectorOrFunctionOrTimeout: string | number | Function, options?: {}, .
| --- | --- | --- |
| selectorOrFunctionOrTimeout | string \| number \| Function | |
| options | {} | |
| args | unknown\[\] | |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | |
<b>Returns:</b>

4
new-docs/puppeteer.frame.waitforfunction.md
View File

@@ -10,7 +10,7 @@
waitForFunction(pageFunction: Function | string, options?: {
polling?: string | number;
timeout?: number;
}, ...args: unknown[]): Promise<JSHandle>;
}, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
```
## Parameters
@@ -19,7 +19,7 @@ waitForFunction(pageFunction: Function | string, options?: {
| --- | --- | --- |
| pageFunction | Function \| string | |
| options | { polling?: string \| number; timeout?: number; } | |
| args | unknown\[\] | |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | |
<b>Returns:</b>

8
new-docs/puppeteer.jshandle.evaluatehandle.md
View File

@@ -9,19 +9,19 @@ This method passes this handle as the first argument to `pageFunction`<!-- -->.
<b>Signature:</b>
```typescript
evaluateHandle(pageFunction: Function | string, ...args: unknown[]): Promise<JSHandle>;
evaluateHandle<HandleType extends JSHandle | ElementHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandleType>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| pageFunction | Function \| string | |
| args | unknown\[\] | |
| pageFunction | [EvaluateHandleFn](./puppeteer.evaluatehandlefn.md) | |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | |
<b>Returns:</b>
Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
Promise&lt;HandleType&gt;
## Remarks

1
new-docs/puppeteer.md
View File

@@ -82,6 +82,7 @@
| [ConsoleMessageType](./puppeteer.consolemessagetype.md) | The supported types for console messages. |
| [EvaluateFn](./puppeteer.evaluatefn.md) | |
| [EvaluateFnReturnType](./puppeteer.evaluatefnreturntype.md) | |
| [EvaluateHandleFn](./puppeteer.evaluatehandlefn.md) | |
| [JSONArray](./puppeteer.jsonarray.md) | |
| [KeyInput](./puppeteer.keyinput.md) | |
| [MouseButtonInput](./puppeteer.mousebuttoninput.md) | |

53
new-docs/puppeteer.page.evaluatehandle.md
View File

@@ -7,17 +7,62 @@
<b>Signature:</b>
```typescript
evaluateHandle(pageFunction: Function | string, ...args: unknown[]): Promise<JSHandle>;
evaluateHandle<HandlerType extends JSHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandlerType>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| pageFunction | Function \| string | |
| args | unknown\[\] | |
| pageFunction | [EvaluateHandleFn](./puppeteer.evaluatehandlefn.md) | a function that is run within the page |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | arguments to be passed to the pageFunction |
<b>Returns:</b>
Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
Promise&lt;HandlerType&gt;
## Remarks
The only difference between [page.evaluate](./puppeteer.page.evaluate.md) and `page.evaluateHandle` is that `evaluateHandle` will return the value wrapped in an in-page object.
If the function passed to `page.evaluteHandle` returns a Promise, the function will wait for the promise to resolve and return its value.
You can pass a string instead of a function (although functions are recommended as they are easier to debug and use with TypeScript):
## Example 1
```
const aHandle = await page.evaluateHandle('document')
```
## Example 2
[JSHandle](./puppeteer.jshandle.md) instances can be passed as arguments to the `pageFunction`<!-- -->:
```
const aHandle = await page.evaluateHandle(() => document.body);
const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle);
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();
```
Most of the time this function returns a [JSHandle](./puppeteer.jshandle.md)<!-- -->, but if `pageFunction` returns a reference to an element, you instead get an [ElementHandle](./puppeteer.elementhandle.md) back:
## Example 3
```
const button = await page.evaluateHandle(() => document.querySelector('button'));
// can call `click` because `button` is an `ElementHandle`
await button.click();
```
The TypeScript definitions assume that `evaluateHandle` returns a `JSHandle`<!-- -->, but if you know it's going to return an `ElementHandle`<!-- -->, pass it as the generic argument:
```
const button = await page.evaluateHandle<ElementHandle>(...);
```

4
new-docs/puppeteer.page.waitfor.md
View File

@@ -12,7 +12,7 @@ waitFor(selectorOrFunctionOrTimeout: string | number | Function, options?: {
hidden?: boolean;
timeout?: number;
polling?: string | number;
}, ...args: unknown[]): Promise<JSHandle>;
}, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
```
## Parameters
@@ -21,7 +21,7 @@ waitFor(selectorOrFunctionOrTimeout: string | number | Function, options?: {
| --- | --- | --- |
| selectorOrFunctionOrTimeout | string \| number \| Function | |
| options | { visible?: boolean; hidden?: boolean; timeout?: number; polling?: string \| number; } | |
| args | unknown\[\] | |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | |
<b>Returns:</b>

4
new-docs/puppeteer.page.waitforfunction.md
View File

@@ -10,7 +10,7 @@
waitForFunction(pageFunction: Function | string, options?: {
timeout?: number;
polling?: string | number;
}, ...args: unknown[]): Promise<JSHandle>;
}, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
```
## Parameters
@@ -19,7 +19,7 @@ waitForFunction(pageFunction: Function | string, options?: {
| --- | --- | --- |
| pageFunction | Function \| string | |
| options | { timeout?: number; polling?: string \| number; } | |
| args | unknown\[\] | |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | |
<b>Returns:</b>

6
new-docs/puppeteer.webworker.evaluatehandle.md
View File

@@ -9,15 +9,15 @@ The only difference between `worker.evaluate` and `worker.evaluateHandle` is tha
<b>Signature:</b>
```typescript
evaluateHandle(pageFunction: Function | string, ...args: any[]): Promise<JSHandle>;
evaluateHandle<HandlerType extends JSHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| pageFunction | Function \| string | Function to be evaluated in the page context. |
| args | any\[\] | Arguments to pass to <code>pageFunction</code>. |
| pageFunction | [EvaluateHandleFn](./puppeteer.evaluatehandlefn.md) | Function to be evaluated in the page context. |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | Arguments to pass to <code>pageFunction</code>. |
<b>Returns:</b>