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

docs: various documentation updates (#12500)

Browse Source
This commit is contained in:
Alex Rudenko 2024-05-29 11:14:12 +02:00 committed by GitHub
parent 33beb50903
commit e2e13eb4f0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
27 changed files with 349 additions and 290 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
README.md
View File

@ -6,48 +6,49 @@
<img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" height="200" align="right"/>
> Puppeteer is a Node.js library which provides a high-level API to control
> Chrome/Chromium over the
> [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
> Puppeteer runs in
> [headless](https://developer.chrome.com/docs/chromium/new-headless/)
> mode by default, but can be configured to run in full ("headful")
> Chrome/Chromium.
> Chrome or Firefox over the
> [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) or [WebDriver BiDi](https://pptr.dev/webdriver-bidi).
> Puppeteer runs in the headless (no visible UI) by default
> but can be configured to run in a visible ("headful") browser.
## [Get started](https://pptr.dev/docs) | [API](https://pptr.dev/api) | [FAQ](https://pptr.dev/faq) | [Contributing](https://pptr.dev/contributing) | [Troubleshooting](https://pptr.dev/troubleshooting)
## Installation
```bash npm2yarn
npm i puppeteer # Downloads compatible Chrome during installation.
npm i puppeteer-core # Alternatively, install as a library, without downloading Chrome.
```
## Example
```ts
import puppeteer from 'puppeteer';
import puppeteer from 'puppeteer'; // or import puppeteer from 'puppeteer-core';
(async () => {
// Launch the browser and open a new blank page
const browser = await puppeteer.launch();
const page = await browser.newPage();
// Launch the browser and open a new blank page
const browser = await puppeteer.launch();
const page = await browser.newPage();
// Navigate the page to a URL
await page.goto('https://developer.chrome.com/');
// Navigate the page to a URL.
await page.goto('https://developer.chrome.com/');
// Set screen size
await page.setViewport({width: 1080, height: 1024});
// Set screen size.
await page.setViewport({width: 1080, height: 1024});
// Type into search box
await page.type('.devsite-search-field', 'automate beyond recorder');
// Type into search box.
await page.type('.devsite-search-field', 'automate beyond recorder');
// Wait and click on first result
const searchResultSelector = '.devsite-result-item-link';
await page.waitForSelector(searchResultSelector);
await page.click(searchResultSelector);
// Wait and click on first result.
const searchResultSelector = '.devsite-result-item-link';
await page.waitForSelector(searchResultSelector);
await page.click(searchResultSelector);
// Locate the full title with a unique string
const textSelector = await page.waitForSelector(
'text/Customize and automate'
);
const fullTitle = await textSelector?.evaluate(el => el.textContent);
// Locate the full title with a unique string.
const textSelector = await page.waitForSelector('text/Customize and automate');
const fullTitle = await textSelector?.evaluate(el => el.textContent);
// Print the full title
console.log('The title of this blog post is "%s".', fullTitle);
// Print the full title.
console.log('The title of this blog post is "%s".', fullTitle);
await browser.close();
})();
await browser.close();
```

2
docs/api/index.md
View File

@ -1063,6 +1063,8 @@ Generic launch options that can be passed when launching any browser.
</td><td>
A media feature to emulate.
</td></tr>
<tr><td>

2
docs/api/puppeteer.frame._.md
View File

@ -41,7 +41,7 @@ Selector
</td><td>
The selector to query for.
[selector](https://pptr.dev/guides/page-interactions#query-selectors) to query page for. [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) can be passed as-is and a [Puppeteer-specific seletor syntax](https://pptr.dev/guides/page-interactions#p-selectors) allows quering by [text](https://pptr.dev/guides/page-interactions#text-selectors--p-text), [a11y role and name](https://pptr.dev/guides/page-interactions#aria-selectors--p-aria), and [xpath](https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath) and [combining these queries across shadow roots](https://pptr.dev/guides/page-interactions#-and--combinators). Alternatively, you can specify a selector type using a prefix [prefix](https://pptr.dev/guides/page-interactions#built-in-selectors).
</td></tr>
</tbody></table>

2
docs/api/puppeteer.frame.__.md
View File

@ -41,7 +41,7 @@ Selector
</td><td>
The selector to query for.
[selector](https://pptr.dev/guides/page-interactions#query-selectors) to query page for. [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) can be passed as-is and a [Puppeteer-specific seletor syntax](https://pptr.dev/guides/page-interactions#p-selectors) allows quering by [text](https://pptr.dev/guides/page-interactions#text-selectors--p-text), [a11y role and name](https://pptr.dev/guides/page-interactions#aria-selectors--p-aria), and [xpath](https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath) and [combining these queries across shadow roots](https://pptr.dev/guides/page-interactions#-and--combinators). Alternatively, you can specify a selector type using a prefix [prefix](https://pptr.dev/guides/page-interactions#built-in-selectors).
</td></tr>
</tbody></table>

2
docs/api/puppeteer.frame.__eval.md
View File

@ -52,7 +52,7 @@ Selector
</td><td>
The selector to query for.
[selector](https://pptr.dev/guides/page-interactions#query-selectors) to query page for. [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) can be passed as-is and a [Puppeteer-specific seletor syntax](https://pptr.dev/guides/page-interactions#p-selectors) allows quering by [text](https://pptr.dev/guides/page-interactions#text-selectors--p-text), [a11y role and name](https://pptr.dev/guides/page-interactions#aria-selectors--p-aria), and [xpath](https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath) and [combining these queries across shadow roots](https://pptr.dev/guides/page-interactions#-and--combinators). Alternatively, you can specify a selector type using a prefix [prefix](https://pptr.dev/guides/page-interactions#built-in-selectors).
</td></tr>
<tr><td>

2
docs/api/puppeteer.frame._eval.md
View File

@ -52,7 +52,7 @@ Selector
</td><td>
The selector to query for.
[selector](https://pptr.dev/guides/page-interactions#query-selectors) to query page for. [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) can be passed as-is and a [Puppeteer-specific seletor syntax](https://pptr.dev/guides/page-interactions#p-selectors) allows quering by [text](https://pptr.dev/guides/page-interactions#text-selectors--p-text), [a11y role and name](https://pptr.dev/guides/page-interactions#aria-selectors--p-aria), and [xpath](https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath) and [combining these queries across shadow roots](https://pptr.dev/guides/page-interactions#-and--combinators). Alternatively, you can specify a selector type using a prefix [prefix](https://pptr.dev/guides/page-interactions#built-in-selectors).
</td></tr>
<tr><td>

16
docs/api/puppeteer.frame.goto.md
View File

@ -4,7 +4,7 @@ sidebar_label: Frame.goto
# Frame.goto() method
Navigates the frame to the given `url`.
Navigates the frame or page to the given `url`.
#### Signature:
@ -69,9 +69,15 @@ A promise which resolves to the main resource response. In case of multiple redi
If:
- there's an SSL error (e.g. in case of self-signed certificates). - target URL is invalid. - the timeout is exceeded during navigation. - the remote server does not respond or is unreachable. - the main resource failed to load.
- there's an SSL error (e.g. in case of self-signed certificates).
This method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [HTTPResponse.status()](./puppeteer.httpresponse.status.md).
- target URL is invalid.
- the timeout is exceeded during navigation.
- the remote server does not respond or is unreachable.
- the main resource failed to load.
## Remarks
@ -79,6 +85,8 @@ Navigation to `about:blank` or navigation to the same URL with a different hash
:::warning
Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
Headless shell mode doesn't support navigation to a PDF document. See the [upstream issue](https://crbug.com/761295).
:::
In headless shell, this method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [HTTPResponse.status()](./puppeteer.httpresponse.status.md).

4
docs/api/puppeteer.frame.isoopframe.md
View File

@ -4,6 +4,10 @@ sidebar_label: Frame.isOOPFrame
# Frame.isOOPFrame() method
> Warning: This API is now obsolete.
>
> Generally, there should be no difference between local and out-of-process frames from the Puppeteer API perspective. This is an implementation detail that should not have been exposed.
Is `true` if the frame is an out-of-process (OOP) frame. Otherwise, `false`.
#### Signature:

12
docs/api/puppeteer.frame.md
View File

@ -287,7 +287,7 @@ Focuses the first element that matches the `selector`.
</td><td>
Navigates the frame to the given `url`.
Navigates the frame or page to the given `url`.
**Remarks:**
@ -295,10 +295,12 @@ Navigation to `about:blank` or navigation to the same URL with a different hash
:::warning
Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
Headless shell mode doesn't support navigation to a PDF document. See the [upstream issue](https://crbug.com/761295).
:::
In headless shell, this method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [HTTPResponse.status()](./puppeteer.httpresponse.status.md).
</td></tr>
<tr><td>
@ -334,10 +336,16 @@ Use the `detached` getter.
</td><td>
`deprecated`
</td><td>
Is `true` if the frame is an out-of-process (OOP) frame. Otherwise, `false`.
**Deprecated:**
Generally, there should be no difference between local and out-of-process frames from the Puppeteer API perspective. This is an implementation detail that should not have been exposed.
</td></tr>
<tr><td>

6
docs/api/puppeteer.mediafeature.md
View File

@ -4,6 +4,8 @@ sidebar_label: MediaFeature
# MediaFeature interface
A media feature to emulate.
#### Signature:
```typescript
@ -45,6 +47,8 @@ string
</td><td>
A name of the feature, for example, 'prefers-reduced-motion'.
</td><td>
</td></tr>
@ -60,6 +64,8 @@ string
</td><td>
A value for the feature, for example, 'reduce'.
</td><td>
</td></tr>

8
docs/api/puppeteer.page._.md
View File

@ -4,7 +4,7 @@ sidebar_label: Page.$
# Page.$() method
Runs `document.querySelector` within the page. If no element matches the selector, the return value resolves to `null`.
Finds the first element that matches the selector. If no element matches the selector, the return value resolves to `null`.
#### Signature:
@ -41,10 +41,14 @@ Selector
</td><td>
A `selector` to query page for [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to query page for.
[selector](https://pptr.dev/guides/page-interactions#query-selectors) to query page for. [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) can be passed as-is and a [Puppeteer-specific seletor syntax](https://pptr.dev/guides/page-interactions#p-selectors) allows quering by [text](https://pptr.dev/guides/page-interactions#text-selectors--p-text), [a11y role and name](https://pptr.dev/guides/page-interactions#aria-selectors--p-aria), and [xpath](https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath) and [combining these queries across shadow roots](https://pptr.dev/guides/page-interactions#-and--combinators). Alternatively, you can specify a selector type using a prefix [prefix](https://pptr.dev/guides/page-interactions#built-in-selectors).
</td></tr>
</tbody></table>
**Returns:**
Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)&lt;[NodeFor](./puppeteer.nodefor.md)&lt;Selector&gt;&gt; \| null&gt;
## Remarks
Shortcut for [Page.mainFrame().$(selector)](./puppeteer.frame._.md).

4
docs/api/puppeteer.page.__.md
View File

@ -4,7 +4,7 @@ sidebar_label: Page.$$
# Page.$$() method
The method runs `document.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`.
Finds elements on the page that match the selector. If no elements match the selector, the return value resolves to `[]`.
#### Signature:
@ -41,7 +41,7 @@ Selector
</td><td>
A `selector` to query page for
[selector](https://pptr.dev/guides/page-interactions#query-selectors) to query page for. [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) can be passed as-is and a [Puppeteer-specific seletor syntax](https://pptr.dev/guides/page-interactions#p-selectors) allows quering by [text](https://pptr.dev/guides/page-interactions#text-selectors--p-text), [a11y role and name](https://pptr.dev/guides/page-interactions#aria-selectors--p-aria), and [xpath](https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath) and [combining these queries across shadow roots](https://pptr.dev/guides/page-interactions#-and--combinators). Alternatively, you can specify a selector type using a prefix [prefix](https://pptr.dev/guides/page-interactions#built-in-selectors).
</td></tr>
</tbody></table>

6
docs/api/puppeteer.page.__eval.md
View File

@ -4,7 +4,7 @@ sidebar_label: Page.$$eval
# 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`.
This method returns all elements matching the selector and passes the resulting array as the first argument to the `pageFunction`.
#### Signature:
@ -50,7 +50,7 @@ Selector
</td><td>
the [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to query for
[selector](https://pptr.dev/guides/page-interactions#query-selectors) to query page for. [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) can be passed as-is and a [Puppeteer-specific seletor syntax](https://pptr.dev/guides/page-interactions#p-selectors) allows quering by [text](https://pptr.dev/guides/page-interactions#text-selectors--p-text), [a11y role and name](https://pptr.dev/guides/page-interactions#aria-selectors--p-aria), and [xpath](https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath) and [combining these queries across shadow roots](https://pptr.dev/guides/page-interactions#-and--combinators). Alternatively, you can specify a selector type using a prefix [prefix](https://pptr.dev/guides/page-interactions#built-in-selectors).
</td></tr>
<tr><td>
@ -63,7 +63,7 @@ Func \| string
</td><td>
the function to be evaluated in the page context. Will be passed the result of `Array.from(document.querySelectorAll(selector))` as its first argument.
the function to be evaluated in the page context. Will be passed an array of matching elements as its first argument.
</td></tr>
<tr><td>

6
docs/api/puppeteer.page._eval.md
View File

@ -4,7 +4,7 @@ sidebar_label: Page.$eval
# Page.$eval() method
This method runs `document.querySelector` within the page and passes the result as the first argument to the `pageFunction`.
This method finds the first element within the page that matches the selector and passes the result as the first argument to the `pageFunction`.
#### Signature:
@ -50,7 +50,7 @@ Selector
</td><td>
the [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to query for
[selector](https://pptr.dev/guides/page-interactions#query-selectors) to query page for. [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) can be passed as-is and a [Puppeteer-specific seletor syntax](https://pptr.dev/guides/page-interactions#p-selectors) allows quering by [text](https://pptr.dev/guides/page-interactions#text-selectors--p-text), [a11y role and name](https://pptr.dev/guides/page-interactions#aria-selectors--p-aria), and [xpath](https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath) and [combining these queries across shadow roots](https://pptr.dev/guides/page-interactions#-and--combinators). Alternatively, you can specify a selector type using a prefix [prefix](https://pptr.dev/guides/page-interactions#built-in-selectors).
</td></tr>
<tr><td>
@ -63,7 +63,7 @@ Func \| string
</td><td>
the function to be evaluated in the page context. Will be passed the result of `document.querySelector(selector)` as its first argument.
the function to be evaluated in the page context. Will be passed the result of the element matching the selector as its first argument.
</td></tr>
<tr><td>

6
docs/api/puppeteer.page.authenticate.md
View File

@ -6,6 +6,12 @@ sidebar_label: Page.authenticate
Provide credentials for `HTTP authentication`.
:::note
Request interception will be turned on behind the scenes to implement authentication. This might affect performance.
:::
#### Signature:
```typescript

8
docs/api/puppeteer.page.goback.md
View File

@ -48,11 +48,3 @@ _(Optional)_ Navigation parameters
Promise&lt;[HTTPResponse](./puppeteer.httpresponse.md) \| null&gt;
Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If can not go back, resolves to `null`.
## Remarks
The argument `options` might have the following properties:
- `timeout` : Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) or [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) methods.
- `waitUntil` : When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:<br/> - `load` : consider navigation to be finished when the load event is fired.<br/> - `domcontentloaded` : consider navigation to be finished when the DOMContentLoaded event is fired.<br/> - `networkidle0` : consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.<br/> - `networkidle2` : consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.

8
docs/api/puppeteer.page.goforward.md
View File

@ -48,11 +48,3 @@ _(Optional)_ Navigation Parameter
Promise&lt;[HTTPResponse](./puppeteer.httpresponse.md) \| null&gt;
Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If can not go forward, resolves to `null`.
## Remarks
The argument `options` might have the following properties:
- `timeout` : Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) or [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) methods.
- `waitUntil`: When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:<br/> - `load` : consider navigation to be finished when the load event is fired.<br/> - `domcontentloaded` : consider navigation to be finished when the DOMContentLoaded event is fired.<br/> - `networkidle0` : consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.<br/> - `networkidle2` : consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.

16
docs/api/puppeteer.page.goto.md
View File

@ -4,7 +4,7 @@ sidebar_label: Page.goto
# Page.goto() method
Navigates the page to the given `url`.
Navigates the frame or page to the given `url`.
#### Signature:
@ -39,7 +39,7 @@ string
</td><td>
URL to navigate page to. The URL should include scheme, e.g. `https://`
URL to navigate the frame to. The URL should include scheme, e.g. `https://`
</td></tr>
<tr><td>
@ -62,22 +62,14 @@ Promise&lt;[HTTPResponse](./puppeteer.httpresponse.md) \| null&gt;
A promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
## Exceptions
If:
- there's an SSL error (e.g. in case of self-signed certificates). - target URL is invalid. - the timeout is exceeded during navigation. - the remote server does not respond or is unreachable. - the main resource failed to load.
This method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [HTTPResponse.status()](./puppeteer.httpresponse.status.md).
## Remarks
Navigation to `about:blank` or navigation to the same URL with a different hash will succeed and return `null`.
:::warning
Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
Headless shell mode doesn't support navigation to a PDF document. See the [upstream issue](https://crbug.com/761295).
:::
Shortcut for [page.mainFrame().goto(url, options)](./puppeteer.frame.goto.md).
In headless shell, this method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [HTTPResponse.status()](./puppeteer.httpresponse.status.md).

2
docs/api/puppeteer.page.locator.md
View File

@ -41,6 +41,8 @@ Selector
</td><td>
[selector](https://pptr.dev/guides/page-interactions#query-selectors) to query page for. [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) can be passed as-is and a [Puppeteer-specific seletor syntax](https://pptr.dev/guides/page-interactions#p-selectors) allows quering by [text](https://pptr.dev/guides/page-interactions#text-selectors--p-text), [a11y role and name](https://pptr.dev/guides/page-interactions#aria-selectors--p-aria), and [xpath](https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath) and [combining these queries across shadow roots](https://pptr.dev/guides/page-interactions#-and--combinators). Alternatively, you can specify a selector type using a prefix [prefix](https://pptr.dev/guides/page-interactions#built-in-selectors).
</td></tr>
</tbody></table>
**Returns:**

4
docs/api/puppeteer.page.mainframe.md
View File

@ -17,7 +17,3 @@ class Page {
**Returns:**
[Frame](./puppeteer.frame.md)
## Remarks
Page is guaranteed to have a main frame which persists during navigations.

58
docs/api/puppeteer.page.md
View File

@ -241,7 +241,11 @@ Description
</td><td>
Runs `document.querySelector` within the page. If no element matches the selector, the return value resolves to `null`.
Finds the first element that matches the selector. If no element matches the selector, the return value resolves to `null`.
**Remarks:**
Shortcut for [Page.mainFrame().$(selector)](./puppeteer.frame._.md).
</td></tr>
<tr><td>
@ -252,7 +256,7 @@ Runs `document.querySelector` within the page. If no element matches the selecto
</td><td>
The method runs `document.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`.
Finds elements on the page that match the selector. If no elements match the selector, the return value resolves to `[]`.
**Remarks:**
@ -267,7 +271,7 @@ Shortcut for [Page.mainFrame().$$(selector)](./puppeteer.frame.__.md).
</td><td>
This method runs `Array.from(document.querySelectorAll(selector))` within the page and passes the result as the first argument to the `pageFunction`.
This method returns all elements matching the selector and passes the resulting array as the first argument to the `pageFunction`.
**Remarks:**
@ -282,7 +286,7 @@ If `pageFunction` returns a promise `$$eval` will wait for the promise to resolv
</td><td>
This method runs `document.querySelector` within the page and passes the result as the first argument to the `pageFunction`.
This method finds the first element within the page that matches the selector and passes the result as the first argument to the `pageFunction`.
**Remarks:**
@ -338,6 +342,12 @@ Shortcut for [page.mainFrame().addStyleTag(options)](./puppeteer.frame.addstylet
Provide credentials for `HTTP authentication`.
:::note
Request interception will be turned on behind the scenes to implement authentication. This might affect performance.
:::
**Remarks:**
To disable authentication, pass `null`.
@ -673,14 +683,6 @@ Maximum time in milliseconds.
This method navigate to the previous page in history.
**Remarks:**
The argument `options` might have the following properties:
- `timeout` : Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) or [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) methods.
- `waitUntil` : When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:<br/> - `load` : consider navigation to be finished when the load event is fired.<br/> - `domcontentloaded` : consider navigation to be finished when the DOMContentLoaded event is fired.<br/> - `networkidle0` : consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.<br/> - `networkidle2` : consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
</td></tr>
<tr><td>
@ -692,14 +694,6 @@ The argument `options` might have the following properties:
This method navigate to the next page in history.
**Remarks:**
The argument `options` might have the following properties:
- `timeout` : Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) or [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) methods.
- `waitUntil`: When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:<br/> - `load` : consider navigation to be finished when the load event is fired.<br/> - `domcontentloaded` : consider navigation to be finished when the DOMContentLoaded event is fired.<br/> - `networkidle0` : consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.<br/> - `networkidle2` : consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
</td></tr>
<tr><td>
@ -709,7 +703,7 @@ The argument `options` might have the following properties:
</td><td>
Navigates the page to the given `url`.
Navigates the frame or page to the given `url`.
**Remarks:**
@ -717,11 +711,11 @@ Navigation to `about:blank` or navigation to the same URL with a different hash
:::warning
Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
Headless shell mode doesn't support navigation to a PDF document. See the [upstream issue](https://crbug.com/761295).
:::
Shortcut for [page.mainFrame().goto(url, options)](./puppeteer.frame.goto.md).
In headless shell, this method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [HTTPResponse.status()](./puppeteer.httpresponse.status.md).
</td></tr>
<tr><td>
@ -829,10 +823,6 @@ Locators API is experimental and we will not follow semver for breaking change i
The page's main frame.
**Remarks:**
Page is guaranteed to have a main frame which persists during navigations.
</td></tr>
<tr><td>
@ -1009,14 +999,6 @@ Toggles ignoring cache for each request based on the enabled state. By default,
Set the content of the page.
**Remarks:**
The parameter `options` might have the following options.
- `timeout` : Maximum time in milliseconds for resources to load, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) or [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) methods.
- `waitUntil`: When to consider setting markup succeeded, defaults to `load`. Given an array of event strings, setting content is considered to be successful after all events have been fired. Events can be either:<br/> - `load` : consider setting content to be finished when the `load` event is fired.<br/> - `domcontentloaded` : consider setting content to be finished when the `DOMContentLoaded` event is fired.<br/> - `networkidle0` : consider setting content to be finished when there are no more than 0 network connections for at least `500` ms.<br/> - `networkidle2` : consider setting content to be finished when there are no more than 2 network connections for at least `500` ms.
</td></tr>
<tr><td>
@ -1300,6 +1282,12 @@ This must be called before the file chooser is launched. It will not return a cu
:::
:::caution
Interception of file dialogs triggered via DOM APIs such as window.showOpenFilePicker is currently not supported.
:::
**Remarks:**
In the "headful" browser, this method results in the native file picker dialog `not showing up` for the user.

8
docs/api/puppeteer.page.setcontent.md
View File

@ -59,11 +59,3 @@ _(Optional)_ Parameters that has some properties.
**Returns:**
Promise&lt;void&gt;
## Remarks
The parameter `options` might have the following options.
- `timeout` : Maximum time in milliseconds for resources to load, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) or [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) methods.
- `waitUntil`: When to consider setting markup succeeded, defaults to `load`. Given an array of event strings, setting content is considered to be successful after all events have been fired. Events can be either:<br/> - `load` : consider setting content to be finished when the `load` event is fired.<br/> - `domcontentloaded` : consider setting content to be finished when the `DOMContentLoaded` event is fired.<br/> - `networkidle0` : consider setting content to be finished when there are no more than 0 network connections for at least `500` ms.<br/> - `networkidle2` : consider setting content to be finished when there are no more than 2 network connections for at least `500` ms.

6
docs/api/puppeteer.page.waitforfilechooser.md
View File

@ -12,6 +12,12 @@ This must be called before the file chooser is launched. It will not return a cu
:::
:::caution
Interception of file dialogs triggered via DOM APIs such as window.showOpenFilePicker is currently not supported.
:::
#### Signature:
```typescript

61
docs/index.md
View File

@ -10,48 +10,49 @@ hide_table_of_contents: true
<img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" height="200" align="right"/>
> Puppeteer is a Node.js library which provides a high-level API to control
> Chrome/Chromium over the
> [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
> Puppeteer runs in
> [headless](https://developer.chrome.com/docs/chromium/new-headless/)
> mode by default, but can be configured to run in full ("headful")
> Chrome/Chromium.
> Chrome or Firefox over the
> [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) or [WebDriver BiDi](https://pptr.dev/webdriver-bidi).
> Puppeteer runs in the headless (no visible UI) by default
> but can be configured to run in a visible ("headful") browser.
## [Get started](https://pptr.dev/docs) | [API](https://pptr.dev/api) | [FAQ](https://pptr.dev/faq) | [Contributing](https://pptr.dev/contributing) | [Troubleshooting](https://pptr.dev/troubleshooting)
## Installation
```bash npm2yarn
npm i puppeteer # Downloads compatible Chrome during installation.
npm i puppeteer-core # Alternatively, install as a library, without downloading Chrome.
```
## Example
```ts
import puppeteer from 'puppeteer';
import puppeteer from 'puppeteer'; // or import puppeteer from 'puppeteer-core';
(async () => {
// Launch the browser and open a new blank page
const browser = await puppeteer.launch();
const page = await browser.newPage();
// Launch the browser and open a new blank page
const browser = await puppeteer.launch();
const page = await browser.newPage();
// Navigate the page to a URL
await page.goto('https://developer.chrome.com/');
// Navigate the page to a URL.
await page.goto('https://developer.chrome.com/');
// Set screen size
await page.setViewport({width: 1080, height: 1024});
// Set screen size.
await page.setViewport({width: 1080, height: 1024});
// Type into search box
await page.type('.devsite-search-field', 'automate beyond recorder');
// Type into search box.
await page.type('.devsite-search-field', 'automate beyond recorder');
// Wait and click on first result
const searchResultSelector = '.devsite-result-item-link';
await page.waitForSelector(searchResultSelector);
await page.click(searchResultSelector);
// Wait and click on first result.
const searchResultSelector = '.devsite-result-item-link';
await page.waitForSelector(searchResultSelector);
await page.click(searchResultSelector);
// Locate the full title with a unique string
const textSelector = await page.waitForSelector(
'text/Customize and automate'
);
const fullTitle = await textSelector?.evaluate(el => el.textContent);
// Locate the full title with a unique string.
const textSelector = await page.waitForSelector('text/Customize and automate');
const fullTitle = await textSelector?.evaluate(el => el.textContent);
// Print the full title
console.log('The title of this blog post is "%s".', fullTitle);
// Print the full title.
console.log('The title of this blog post is "%s".', fullTitle);
await browser.close();
})();
await browser.close();
```

4
docs/webdriver-bidi.md
View File

@ -122,7 +122,9 @@ This is an exciting step towards a more unified and efficient cross-browser auto
- HTTPRequest.isInterceptResolutionHandled()
- HTTPRequest.respond()
- HTTPRequest.responseForRequest()
- Page.authenticate()
- Page.setRequestInterception()
- Page.setUserAgent()
## Puppeteer features not yet supported over WebDriver BiDi
@ -160,7 +162,6 @@ This is an exciting step towards a more unified and efficient cross-browser auto
- Input.dragAndDrop()
- Input.dragOver()
- Input.drop()
- Page.authenticate()
- Page.emulateNetworkConditions()
- Page.isDragInterceptionEnabled()
- Page.isJavaScriptEnabled() (supported only in Chrome)
@ -171,7 +172,6 @@ This is an exciting step towards a more unified and efficient cross-browser auto
- Page.setBypassServiceWorker()
- Page.setDragInterception()
- Page.setOfflineMode()
- Page.setUserAgent()
- Page.waitForDevicePrompt()
- Page.waitForFileChooser()
- PageEvent.popup

97
packages/puppeteer-core/src/api/Frame.ts
View File

@ -297,11 +297,15 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
/**
* Is `true` if the frame is an out-of-process (OOP) frame. Otherwise,
* `false`.
*
* @deprecated Generally, there should be no difference between local and
* out-of-process frames from the Puppeteer API perspective. This is an
* implementation detail that should not have been exposed.
*/
abstract isOOPFrame(): boolean;
/**
* Navigates the frame to the given `url`.
* Navigates the frame or page to the given `url`.
*
* @remarks
* Navigation to `about:blank` or navigation to the same URL with a different
@ -309,12 +313,16 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
*
* :::warning
*
* Headless mode doesn't support navigation to a PDF document. See the {@link
* https://bugs.chromium.org/p/chromium/issues/detail?id=761295 | upstream
* issue}.
* Headless shell mode doesn't support navigation to a PDF document. See the
* {@link https://crbug.com/761295 | upstream issue}.
*
* :::
*
* In headless shell, this method will not throw an error when any valid HTTP
* status code is returned by the remote server, including 404 "Not Found" and
* 500 "Internal Server Error". The status code for such responses can be
* retrieved by calling {@link HTTPResponse.status}.
*
* @param url - URL to navigate the frame to. The URL should include scheme,
* e.g. `https://`
* @param options - Options to configure waiting behavior.
@ -324,15 +332,14 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
* @throws If:
*
* - there's an SSL error (e.g. in case of self-signed certificates).
* - target URL is invalid.
* - the timeout is exceeded during navigation.
* - the remote server does not respond or is unreachable.
* - the main resource failed to load.
*
* This method will not throw an error when any valid HTTP status code is
* returned by the remote server, including 404 "Not Found" and 500 "Internal
* Server Error". The status code for such responses can be retrieved by
* calling {@link HTTPResponse.status}.
* - target URL is invalid.
*
* - the timeout is exceeded during navigation.
*
* - the remote server does not respond or is unreachable.
*
* - the main resource failed to load.
*/
abstract goto(
url: string,
@ -508,7 +515,22 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
/**
* Queries the frame for an element matching the given selector.
*
* @param selector - The selector to query for.
* @param selector -
* {@link https://pptr.dev/guides/page-interactions#query-selectors | selector}
* to query page for.
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | CSS selectors}
* can be passed as-is and a
* {@link https://pptr.dev/guides/page-interactions#p-selectors | Puppeteer-specific seletor syntax}
* allows quering by
* {@link https://pptr.dev/guides/page-interactions#text-selectors--p-text | text},
* {@link https://pptr.dev/guides/page-interactions#aria-selectors--p-aria | a11y role and name},
* and
* {@link https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath | xpath}
* and
* {@link https://pptr.dev/guides/page-interactions#-and--combinators | combining these queries across shadow roots}.
* Alternatively, you can specify a selector type using a prefix
* {@link https://pptr.dev/guides/page-interactions#built-in-selectors | prefix}.
*
* @returns A {@link ElementHandle | element handle} to the first element
* matching the given selector. Otherwise, `null`.
*/
@ -524,7 +546,22 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
/**
* Queries the frame for all elements matching the given selector.
*
* @param selector - The selector to query for.
* @param selector -
* {@link https://pptr.dev/guides/page-interactions#query-selectors | selector}
* to query page for.
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | CSS selectors}
* can be passed as-is and a
* {@link https://pptr.dev/guides/page-interactions#p-selectors | Puppeteer-specific seletor syntax}
* allows quering by
* {@link https://pptr.dev/guides/page-interactions#text-selectors--p-text | text},
* {@link https://pptr.dev/guides/page-interactions#aria-selectors--p-aria | a11y role and name},
* and
* {@link https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath | xpath}
* and
* {@link https://pptr.dev/guides/page-interactions#-and--combinators | combining these queries across shadow roots}.
* Alternatively, you can specify a selector type using a prefix
* {@link https://pptr.dev/guides/page-interactions#built-in-selectors | prefix}.
*
* @returns An array of {@link ElementHandle | element handles} that point to
* elements matching the given selector.
*/
@ -550,7 +587,21 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
* const searchValue = await frame.$eval('#search', el => el.value);
* ```
*
* @param selector - The selector to query for.
* @param selector -
* {@link https://pptr.dev/guides/page-interactions#query-selectors | selector}
* to query page for.
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | CSS selectors}
* can be passed as-is and a
* {@link https://pptr.dev/guides/page-interactions#p-selectors | Puppeteer-specific seletor syntax}
* allows quering by
* {@link https://pptr.dev/guides/page-interactions#text-selectors--p-text | text},
* {@link https://pptr.dev/guides/page-interactions#aria-selectors--p-aria | a11y role and name},
* and
* {@link https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath | xpath}
* and
* {@link https://pptr.dev/guides/page-interactions#-and--combinators | combining these queries across shadow roots}.
* Alternatively, you can specify a selector type using a prefix
* {@link https://pptr.dev/guides/page-interactions#built-in-selectors | prefix}.
* @param pageFunction - The function to be evaluated in the frame's context.
* The first element matching the selector will be passed to the function as
* its first argument.
@ -589,7 +640,21 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
* const divsCounts = await frame.$$eval('div', divs => divs.length);
* ```
*
* @param selector - The selector to query for.
* @param selector -
* {@link https://pptr.dev/guides/page-interactions#query-selectors | selector}
* to query page for.
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | CSS selectors}
* can be passed as-is and a
* {@link https://pptr.dev/guides/page-interactions#p-selectors | Puppeteer-specific seletor syntax}
* allows quering by
* {@link https://pptr.dev/guides/page-interactions#text-selectors--p-text | text},
* {@link https://pptr.dev/guides/page-interactions#aria-selectors--p-aria | a11y role and name},
* and
* {@link https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath | xpath}
* and
* {@link https://pptr.dev/guides/page-interactions#-and--combinators | combining these queries across shadow roots}.
* Alternatively, you can specify a selector type using a prefix
* {@link https://pptr.dev/guides/page-interactions#built-in-selectors | prefix}.
* @param pageFunction - The function to be evaluated in the frame's context.
* An array of elements matching the given selector will be passed to the
* function as its first argument.

228
packages/puppeteer-core/src/api/Page.ts
View File

@ -223,10 +223,18 @@ export interface GeolocationOptions {
}
/**
* A media feature to emulate.
*
* @public
*/
export interface MediaFeature {
/**
* A name of the feature, for example, 'prefers-reduced-motion'.
*/
name: string;
/**
* A value for the feature, for example, 'reduce'.
*/
value: string;
}
@ -727,6 +735,13 @@ export abstract class Page extends EventEmitter<PageEvents> {
*
* :::
*
* :::caution
*
* Interception of file dialogs triggered via DOM APIs such as
* window.showOpenFilePicker is currently not supported.
*
* :::
*
* @remarks
* In the "headful" browser, this method results in the native file picker
* dialog `not showing up` for the user.
@ -782,9 +797,6 @@ export abstract class Page extends EventEmitter<PageEvents> {
/**
* The page's main frame.
*
* @remarks
* Page is guaranteed to have a main frame which persists during navigations.
*/
abstract mainFrame(): Frame;
@ -960,6 +972,22 @@ export abstract class Page extends EventEmitter<PageEvents> {
* Creates a locator for the provided selector. See {@link Locator} for
* details and supported actions.
*
* @param selector -
* {@link https://pptr.dev/guides/page-interactions#query-selectors | selector}
* to query page for.
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | CSS selectors}
* can be passed as-is and a
* {@link https://pptr.dev/guides/page-interactions#p-selectors | Puppeteer-specific seletor syntax}
* allows quering by
* {@link https://pptr.dev/guides/page-interactions#text-selectors--p-text | text},
* {@link https://pptr.dev/guides/page-interactions#aria-selectors--p-aria | a11y role and name},
* and
* {@link https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath | xpath}
* and
* {@link https://pptr.dev/guides/page-interactions#-and--combinators | combining these queries across shadow roots}.
* Alternatively, you can specify a selector type using a prefix
* {@link https://pptr.dev/guides/page-interactions#built-in-selectors | prefix}.
*
* @remarks
* Locators API is experimental and we will not follow semver for breaking
* change in the Locators API.
@ -999,12 +1027,28 @@ export abstract class Page extends EventEmitter<PageEvents> {
}
/**
* Runs `document.querySelector` within the page. If no element matches the
* selector, the return value resolves to `null`.
* Finds the first element that matches the selector. If no element matches
* the selector, the return value resolves to `null`.
*
* @param selector - A `selector` to query page for
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
* @param selector -
* {@link https://pptr.dev/guides/page-interactions#query-selectors | selector}
* to query page for.
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | CSS selectors}
* can be passed as-is and a
* {@link https://pptr.dev/guides/page-interactions#p-selectors | Puppeteer-specific seletor syntax}
* allows quering by
* {@link https://pptr.dev/guides/page-interactions#text-selectors--p-text | text},
* {@link https://pptr.dev/guides/page-interactions#aria-selectors--p-aria | a11y role and name},
* and
* {@link https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath | xpath}
* and
* {@link https://pptr.dev/guides/page-interactions#-and--combinators | combining these queries across shadow roots}.
* Alternatively, you can specify a selector type using a prefix
* {@link https://pptr.dev/guides/page-interactions#built-in-selectors | prefix}.
*
* @remarks
*
* Shortcut for {@link Frame.$ | Page.mainFrame().$(selector) }.
*/
async $<Selector extends string>(
selector: Selector
@ -1013,10 +1057,24 @@ export abstract class Page extends EventEmitter<PageEvents> {
}
/**
* The method runs `document.querySelectorAll` within the page. If no elements
* Finds elements on the page that match the selector. If no elements
* match the selector, the return value resolves to `[]`.
*
* @param selector - A `selector` to query page for
* @param selector -
* {@link https://pptr.dev/guides/page-interactions#query-selectors | selector}
* to query page for.
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | CSS selectors}
* can be passed as-is and a
* {@link https://pptr.dev/guides/page-interactions#p-selectors | Puppeteer-specific seletor syntax}
* allows quering by
* {@link https://pptr.dev/guides/page-interactions#text-selectors--p-text | text},
* {@link https://pptr.dev/guides/page-interactions#aria-selectors--p-aria | a11y role and name},
* and
* {@link https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath | xpath}
* and
* {@link https://pptr.dev/guides/page-interactions#-and--combinators | combining these queries across shadow roots}.
* Alternatively, you can specify a selector type using a prefix
* {@link https://pptr.dev/guides/page-interactions#built-in-selectors | prefix}.
*
* @remarks
*
@ -1127,8 +1185,8 @@ export abstract class Page extends EventEmitter<PageEvents> {
): Promise<JSHandle<Prototype[]>>;
/**
* This method runs `document.querySelector` within the page and passes the
* result as the first argument to the `pageFunction`.
* This method finds the first element within the page that matches the selector
* and passes the result as the first argument to the `pageFunction`.
*
* @remarks
*
@ -1176,11 +1234,23 @@ export abstract class Page extends EventEmitter<PageEvents> {
* );
* ```
*
* @param selector - the
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
* to query for
* @param selector -
* {@link https://pptr.dev/guides/page-interactions#query-selectors | selector}
* to query page for.
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | CSS selectors}
* can be passed as-is and a
* {@link https://pptr.dev/guides/page-interactions#p-selectors | Puppeteer-specific seletor syntax}
* allows quering by
* {@link https://pptr.dev/guides/page-interactions#text-selectors--p-text | text},
* {@link https://pptr.dev/guides/page-interactions#aria-selectors--p-aria | a11y role and name},
* and
* {@link https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath | xpath}
* and
* {@link https://pptr.dev/guides/page-interactions#-and--combinators | combining these queries across shadow roots}.
* Alternatively, you can specify a selector type using a prefix
* {@link https://pptr.dev/guides/page-interactions#built-in-selectors | prefix}.
* @param pageFunction - the function to be evaluated in the page context.
* Will be passed the result of `document.querySelector(selector)` as its
* Will be passed the result of the element matching the selector as its
* first argument.
* @param args - any additional arguments to pass through to `pageFunction`.
*
@ -1205,8 +1275,8 @@ export abstract class Page extends EventEmitter<PageEvents> {
}
/**
* This method runs `Array.from(document.querySelectorAll(selector))` within
* the page and passes the result as the first argument to the `pageFunction`.
* This method returns all elements matching the selector and passes the
* resulting array as the first argument to the `pageFunction`.
*
* @remarks
* If `pageFunction` returns a promise `$$eval` will wait for the promise to
@ -1249,12 +1319,23 @@ export abstract class Page extends EventEmitter<PageEvents> {
* );
* ```
*
* @param selector - the
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
* to query for
* @param selector -
* {@link https://pptr.dev/guides/page-interactions#query-selectors | selector}
* to query page for.
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | CSS selectors}
* can be passed as-is and a
* {@link https://pptr.dev/guides/page-interactions#p-selectors | Puppeteer-specific seletor syntax}
* allows quering by
* {@link https://pptr.dev/guides/page-interactions#text-selectors--p-text | text},
* {@link https://pptr.dev/guides/page-interactions#aria-selectors--p-aria | a11y role and name},
* and
* {@link https://pptr.dev/guides/page-interactions#xpath-selectors--p-xpath | xpath}
* and
* {@link https://pptr.dev/guides/page-interactions#-and--combinators | combining these queries across shadow roots}.
* Alternatively, you can specify a selector type using a prefix
* {@link https://pptr.dev/guides/page-interactions#built-in-selectors | prefix}.
* @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.
* Will be passed an array of matching elements 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
@ -1417,6 +1498,13 @@ export abstract class Page extends EventEmitter<PageEvents> {
/**
* Provide credentials for `HTTP authentication`.
*
* :::note
*
* Request interception will be turned on behind the scenes to
* implement authentication. This might affect performance.
*
* :::
*
* @remarks
* To disable authentication, pass `null`.
*/
@ -1516,69 +1604,13 @@ export abstract class Page extends EventEmitter<PageEvents> {
*
* @param html - HTML markup to assign to the page.
* @param options - Parameters that has some properties.
*
* @remarks
*
* The parameter `options` might have the following options.
*
* - `timeout` : Maximum time in milliseconds for resources to load, defaults
* to 30 seconds, pass `0` to disable timeout. The default value can be
* changed by using the {@link Page.setDefaultNavigationTimeout} or
* {@link Page.setDefaultTimeout} methods.
*
* - `waitUntil`: When to consider setting markup succeeded, defaults to
* `load`. Given an array of event strings, setting content is considered
* to be successful after all events have been fired. Events can be
* either:<br/>
* - `load` : consider setting content to be finished when the `load` event
* is fired.<br/>
* - `domcontentloaded` : consider setting content to be finished when the
* `DOMContentLoaded` event is fired.<br/>
* - `networkidle0` : consider setting content to be finished when there are
* no more than 0 network connections for at least `500` ms.<br/>
* - `networkidle2` : consider setting content to be finished when there are
* no more than 2 network connections for at least `500` ms.
*/
async setContent(html: string, options?: WaitForOptions): Promise<void> {
await this.mainFrame().setContent(html, options);
}
/**
* Navigates the page to the given `url`.
*
* @remarks
*
* Navigation to `about:blank` or navigation to the same URL with a different
* hash will succeed and return `null`.
*
* :::warning
*
* Headless mode doesn't support navigation to a PDF document. See the {@link
* https://bugs.chromium.org/p/chromium/issues/detail?id=761295 | upstream
* issue}.
*
* :::
*
* Shortcut for {@link Frame.goto | page.mainFrame().goto(url, options)}.
*
* @param url - URL to navigate page to. The URL should include scheme, e.g.
* `https://`
* @param options - Options to configure waiting behavior.
* @returns A promise which resolves to the main resource response. In case of
* multiple redirects, the navigation will resolve with the response of the
* last redirect.
* @throws If:
*
* - there's an SSL error (e.g. in case of self-signed certificates).
* - target URL is invalid.
* - the timeout is exceeded during navigation.
* - the remote server does not respond or is unreachable.
* - the main resource failed to load.
*
* This method will not throw an error when any valid HTTP status code is
* returned by the remote server, including 404 "Not Found" and 500 "Internal
* Server Error". The status code for such responses can be retrieved by
* calling {@link HTTPResponse.status}.
* {@inheritDoc Frame.goto}
*/
async goto(url: string, options?: GoToOptions): Promise<HTTPResponse | null> {
return await this.mainFrame().goto(url, options);
@ -1818,25 +1850,6 @@ export abstract class Page extends EventEmitter<PageEvents> {
* @returns Promise which resolves to the main resource response. In case of
* multiple redirects, the navigation will resolve with the response of the
* last redirect. If can not go back, resolves to `null`.
* @remarks
* The argument `options` might have the following properties:
*
* - `timeout` : Maximum navigation time in milliseconds, defaults to 30
* seconds, pass 0 to disable timeout. The default value can be changed by
* using the {@link Page.setDefaultNavigationTimeout} or
* {@link Page.setDefaultTimeout} methods.
*
* - `waitUntil` : When to consider navigation succeeded, defaults to `load`.
* Given an array of event strings, navigation is considered to be
* successful after all events have been fired. Events can be either:<br/>
* - `load` : consider navigation to be finished when the load event is
* fired.<br/>
* - `domcontentloaded` : consider navigation to be finished when the
* DOMContentLoaded event is fired.<br/>
* - `networkidle0` : consider navigation to be finished when there are no
* more than 0 network connections for at least `500` ms.<br/>
* - `networkidle2` : consider navigation to be finished when there are no
* more than 2 network connections for at least `500` ms.
*/
abstract goBack(options?: WaitForOptions): Promise<HTTPResponse | null>;
@ -1846,25 +1859,6 @@ export abstract class Page extends EventEmitter<PageEvents> {
* @returns Promise which resolves to the main resource response. In case of
* multiple redirects, the navigation will resolve with the response of the
* last redirect. If can not go forward, resolves to `null`.
* @remarks
* The argument `options` might have the following properties:
*
* - `timeout` : Maximum navigation time in milliseconds, defaults to 30
* seconds, pass 0 to disable timeout. The default value can be changed by
* using the {@link Page.setDefaultNavigationTimeout} or
* {@link Page.setDefaultTimeout} methods.
*
* - `waitUntil`: When to consider navigation succeeded, defaults to `load`.
* Given an array of event strings, navigation is considered to be
* successful after all events have been fired. Events can be either:<br/>
* - `load` : consider navigation to be finished when the load event is
* fired.<br/>
* - `domcontentloaded` : consider navigation to be finished when the
* DOMContentLoaded event is fired.<br/>
* - `networkidle0` : consider navigation to be finished when there are no
* more than 0 network connections for at least `500` ms.<br/>
* - `networkidle2` : consider navigation to be finished when there are no
* more than 2 network connections for at least `500` ms.
*/
abstract goForward(options?: WaitForOptions): Promise<HTTPResponse | null>;