Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
docs: migrating Page.ts to TSDoc (#6152)
* docs: a small batch of page TSdoc migration

Co-authored-by: Changhao Han <changhaohan@chromium.org>
  • Loading branch information
hanselfmu and hanselfmu-chromium committed Jul 3, 2020
1 parent d9bb52e commit 4ebf117
Show file tree
Hide file tree
Showing 4 changed files with 71 additions and 10 deletions.
31 changes: 28 additions & 3 deletions new-docs/puppeteer.page.__eval.md
Expand Up @@ -4,6 +4,8 @@

## Page.$$eval() method

This method runs `Array.from(document.querySelectorAll(selector))` within the page and passes the result as the first argument to the `pageFunction`<!-- -->.

<b>Signature:</b>

```typescript
Expand All @@ -14,11 +16,34 @@ $$eval<ReturnType extends any>(selector: string, pageFunction: EvaluateFn | stri
| Parameter | Type | Description |
| --- | --- | --- |
| selector | string | |
| pageFunction | [EvaluateFn](./puppeteer.evaluatefn.md) \| string | |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | |
| selector | string | the [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to query for |
| pageFunction | [EvaluateFn](./puppeteer.evaluatefn.md) \| string | the function to be evaluated in the page context. Will be passed the result of <code>Array.from(document.querySelectorAll(selector))</code> as its first argument. |
| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | any additional arguments to pass through to <code>pageFunction</code>. |
<b>Returns:</b>
Promise&lt;ReturnType&gt;
The result of calling `pageFunction`<!-- -->.
## Remarks
If `pageFunction` returns a promise `$$eval` will wait for the promise to resolve and then return its value.
## Example 1
```js
const divCount = await page.$$eval('div', divs => divs.length);

```

## Example 2


```js
const options = await page.$$eval(
'div > span.options', options => options.map(option => option.textContent));

```

2 changes: 2 additions & 0 deletions new-docs/puppeteer.page.cookies.md
Expand Up @@ -4,6 +4,8 @@

## Page.cookies() method

If no URLs are specified, this method returns cookies for the current page URL. If URLs are specified, only cookies for those URLs are returned.

<b>Signature:</b>

```typescript
Expand Down
4 changes: 2 additions & 2 deletions new-docs/puppeteer.page.md
Expand Up @@ -72,7 +72,7 @@ page.off('request', logRequest);
| --- | --- | --- |
| [$(selector)](./puppeteer.page._.md) | | Runs <code>document.querySelector</code> within the page. If no element matches the selector, the return value resolves to <code>null</code>. |
| [$$(selector)](./puppeteer.page.__.md) | | |
| [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) | | |
| [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) | | This method runs <code>Array.from(document.querySelectorAll(selector))</code> within the page and passes the result as the first argument to the <code>pageFunction</code>. |
| [$eval(selector, pageFunction, args)](./puppeteer.page._eval.md) | | This method runs <code>document.querySelector</code> within the page and passes the result as the first argument to the <code>pageFunction</code>. |
| [$x(expression)](./puppeteer.page._x.md) | | |
| [addScriptTag(options)](./puppeteer.page.addscripttag.md) | | |
Expand All @@ -84,7 +84,7 @@ page.off('request', logRequest);
| [click(selector, options)](./puppeteer.page.click.md) | | |
| [close(options)](./puppeteer.page.close.md) | | |
| [content()](./puppeteer.page.content.md) | | |
| [cookies(urls)](./puppeteer.page.cookies.md) | | |
| [cookies(urls)](./puppeteer.page.cookies.md) | | If no URLs are specified, this method returns cookies for the current page URL. If URLs are specified, only cookies for those URLs are returned. |
| [deleteCookie(cookies)](./puppeteer.page.deletecookie.md) | | |
| [emulate(options)](./puppeteer.page.emulate.md) | | |
| [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) | | |
Expand Down
44 changes: 39 additions & 5 deletions src/common/Page.ts
Expand Up @@ -752,13 +752,13 @@ export class Page extends EventEmitter {
* );
* ```
*
* @param selector the
* @param selector - the
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
* to query for
* @param pageFunction the function to be evaluated in the page context. Will
* be passed the result of `document.querySelector(selector)` as its first
* argument.
* @param args any additional arguments to pass through to `pageFunction`.
* @param pageFunction - the function to be evaluated in the page context.
* Will be passed the result of `document.querySelector(selector)` as its
* first argument.
* @param args - any additional arguments to pass through to `pageFunction`.
*
* @returns The result of calling `pageFunction`. If it returns an element it
* is wrapped in an {@link ElementHandle}, else the raw value itself is
Expand All @@ -785,6 +785,36 @@ export class Page extends EventEmitter {
return this.mainFrame().$eval<ReturnType>(selector, pageFunction, ...args);
}

/**
* This method runs `Array.from(document.querySelectorAll(selector))` within
* the page and passes the result as the first argument to the `pageFunction`.
*
* @remarks
*
* If `pageFunction` returns a promise `$$eval` will wait for the promise to
* resolve and then return its value.
*
* @example
* ```js
* const divCount = await page.$$eval('div', divs => divs.length);
* ```
*
* @example
* ```js
* const options = await page.$$eval(
* 'div > span.options', options => options.map(option => option.textContent));
* ```
*
* @param selector - the
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
* to query for
* @param pageFunction - the function to be evaluated in the page context.
* Will be passed the result of
* `Array.from(document.querySelectorAll(selector))` as its first argument.
* @param args - any additional arguments to pass through to `pageFunction`.
*
* @returns The result of calling `pageFunction`.
*/
async $$eval<ReturnType extends any>(
selector: string,
pageFunction: EvaluateFn | string,
Expand All @@ -801,6 +831,10 @@ export class Page extends EventEmitter {
return this.mainFrame().$x(expression);
}

/**
* If no URLs are specified, this method returns cookies for the current page
* URL. If URLs are specified, only cookies for those URLs are returned.
*/
async cookies(...urls: string[]): Promise<Protocol.Network.Cookie[]> {
const originalCookies = (
await this._client.send('Network.getCookies', {
Expand Down

0 comments on commit 4ebf117

Please sign in to comment.