docs: various doc improvements (#9396)

See commits for details.

Closes #1837, #5880, #7822, #8101, #8821, #9367, #9382, #9378, #4731
This commit is contained in:
Alex Rudenko 2022-12-09 13:57:39 +01:00 committed by GitHub
parent 810e0cd74e
commit 1668d47b2f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
32 changed files with 197 additions and 62 deletions

View File

@ -35,7 +35,7 @@ sidebar_label: API
| [Puppeteer](./puppeteer.puppeteer.md) | <p>The main Puppeteer class.</p><p>IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require <code>puppeteer</code>. That class extends <code>Puppeteer</code>, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).</p> | | [Puppeteer](./puppeteer.puppeteer.md) | <p>The main Puppeteer class.</p><p>IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require <code>puppeteer</code>. That class extends <code>Puppeteer</code>, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).</p> |
| [PuppeteerNode](./puppeteer.puppeteernode.md) | <p>Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.</p><p>If you're using Puppeteer in a Node environment, this is the class you'll get when you run <code>require('puppeteer')</code> (or the equivalent ES <code>import</code>).</p> | | [PuppeteerNode](./puppeteer.puppeteernode.md) | <p>Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.</p><p>If you're using Puppeteer in a Node environment, this is the class you'll get when you run <code>require('puppeteer')</code> (or the equivalent ES <code>import</code>).</p> |
| [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. | | [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. |
| [Target](./puppeteer.target.md) | | | [Target](./puppeteer.target.md) | Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker. |
| [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | | [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. |
| [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | | [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. |
| [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | | [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. |

View File

@ -25,7 +25,7 @@ The constructor for this class is marked as internal. Third-party code should no
An example of using a [Browser](./puppeteer.browser.md) to create a [Page](./puppeteer.page.md): An example of using a [Browser](./puppeteer.browser.md) to create a [Page](./puppeteer.page.md):
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();
@ -40,7 +40,7 @@ const puppeteer = require('puppeteer');
An example of disconnecting from and reconnecting to a [Browser](./puppeteer.browser.md): An example of disconnecting from and reconnecting to a [Browser](./puppeteer.browser.md):
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();

View File

@ -19,7 +19,7 @@ The constructor for this class is marked as internal. Third-party code should no
## Example ## Example
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();

View File

@ -19,7 +19,7 @@ export declare class ElementHandle<ElementType extends Node = Element> extends J
ElementHandles can be created with the [Page.$()](./puppeteer.page._.md) method. ElementHandles can be created with the [Page.$()](./puppeteer.page._.md) method.
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();

View File

@ -39,7 +39,7 @@ Throws if an element matching the given selector doesn't appear.
## Example ## Example
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();

View File

@ -19,7 +19,7 @@ sidebar_label: ElementHandle.waitForXPath
> This method works across navigation. > This method works across navigation.
> >
> ```ts > ```ts
> const puppeteer = require('puppeteer'); > import puppeteer from 'puppeteer';
> (async () => { > (async () => {
> const browser = await puppeteer.launch(); > const browser = await puppeteer.launch();
> const page = await browser.newPage(); > const page = await browser.newPage();

View File

@ -31,7 +31,7 @@ At any point in time, [pages](./puppeteer.page.md) expose their current frame tr
An example of dumping frame tree: An example of dumping frame tree:
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();

View File

@ -38,7 +38,7 @@ the promise which resolve when the `pageFunction` returns a truthy value.
The `waitForFunction` can be used to observe viewport size change: The `waitForFunction` can be used to observe viewport size change:
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
. const browser = await puppeteer.launch(); . const browser = await puppeteer.launch();

View File

@ -39,7 +39,7 @@ Throws if an element matching the given selector doesn't appear.
## Example ## Example
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();

View File

@ -29,7 +29,7 @@ Promise&lt;void&gt;
## Example ## Example
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();

View File

@ -45,8 +45,8 @@ Promise&lt;void&gt;
An example of adding an `md5` function into the page: An example of adding an `md5` function into the page:
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
const crypto = require('crypto'); import crypto from 'crypto';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();
@ -70,8 +70,8 @@ const crypto = require('crypto');
An example of adding a `window.readfile` function into the page: An example of adding a `window.readfile` function into the page:
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
const fs = require('fs'); import fs from 'fs';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();

View File

@ -29,7 +29,7 @@ The constructor for this class is marked as internal. Third-party code should no
This example creates a page, navigates it to a URL, and then saves a screenshot: This example creates a page, navigates it to a URL, and then saves a screenshot:
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();
@ -157,7 +157,7 @@ page.off('request', logRequest);
| [waitForSelector(selector, options)](./puppeteer.page.waitforselector.md) | | <p>Wait for the <code>selector</code> to appear in page. If at the moment of calling the method the <code>selector</code> already exists, the method will return immediately. If the <code>selector</code> doesn't appear after the <code>timeout</code> milliseconds of waiting, the function will throw.</p><p>This method works across navigations:</p> | | [waitForSelector(selector, options)](./puppeteer.page.waitforselector.md) | | <p>Wait for the <code>selector</code> to appear in page. If at the moment of calling the method the <code>selector</code> already exists, the method will return immediately. If the <code>selector</code> doesn't appear after the <code>timeout</code> milliseconds of waiting, the function will throw.</p><p>This method works across navigations:</p> |
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();
const page = await browser.newPage(); const page = await browser.newPage();
@ -181,7 +181,7 @@ const puppeteer = require('puppeteer');
| [waitForXPath(xpath, options)](./puppeteer.page.waitforxpath.md) | | <p>Wait for the <code>xpath</code> to appear in page. If at the moment of calling the method the <code>xpath</code> already exists, the method will return immediately. If the <code>xpath</code> doesn't appear after the <code>timeout</code> milliseconds of waiting, the function will throw.</p><p>This method works across navigation</p> | [waitForXPath(xpath, options)](./puppeteer.page.waitforxpath.md) | | <p>Wait for the <code>xpath</code> to appear in page. If at the moment of calling the method the <code>xpath</code> already exists, the method will return immediately. If the <code>xpath</code> doesn't appear after the <code>timeout</code> milliseconds of waiting, the function will throw.</p><p>This method works across navigation</p>
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();
const page = await browser.newPage(); const page = await browser.newPage();

View File

@ -33,7 +33,7 @@ Promise&lt;void&gt;
An example of a naïve request interceptor that aborts all image requests: An example of a naïve request interceptor that aborts all image requests:
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();
const page = await browser.newPage(); const page = await browser.newPage();

View File

@ -38,7 +38,7 @@ Promise&lt;[HandleFor](./puppeteer.handlefor.md)&lt;Awaited&lt;ReturnType&lt;Fun
The [Page.waitForFunction()](./puppeteer.page.waitforfunction.md) can be used to observe viewport size change: The [Page.waitForFunction()](./puppeteer.page.waitforfunction.md) can be used to observe viewport size change:
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();
const page = await browser.newPage(); const page = await browser.newPage();

View File

@ -9,7 +9,7 @@ Wait for the `selector` to appear in page. If at the moment of calling the metho
This method works across navigations: This method works across navigations:
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();
const page = await browser.newPage(); const page = await browser.newPage();

View File

@ -9,7 +9,7 @@ Wait for the `xpath` to appear in page. If at the moment of calling the method t
This method works across navigation This method works across navigation
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();
const page = await browser.newPage(); const page = await browser.newPage();

View File

@ -29,7 +29,7 @@ The constructor for this class is marked as internal. Third-party code should no
The following is a typical example of using Puppeteer to drive automation: The following is a typical example of using Puppeteer to drive automation:
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();

View File

@ -4,6 +4,8 @@ sidebar_label: Target
# Target class # Target class
Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker.
#### Signature: #### Signature:
```typescript ```typescript

View File

@ -14,10 +14,11 @@ The following is code for getting a handle to the
an extension whose source is located in `./my-extension`: an extension whose source is located in `./my-extension`:
```ts ```ts
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
import path from 'path';
(async () => { (async () => {
const pathToExtension = require('path').join(__dirname, 'my-extension'); const pathToExtension = path.join(process.cwd(), 'my-extension');
const browser = await puppeteer.launch({ const browser = await puppeteer.launch({
headless: 'chrome', headless: 'chrome',
args: [ args: [

View File

@ -17,6 +17,12 @@ as `HTTPS_PROXY`).
::: :::
:::caution
Puppeteer's configuration files and environment variables are ignored by `puppeteer-core`.
:::
## Configuration files ## Configuration files
Configuration files are the **recommended** choice for configuring Puppeteer. Configuration files are the **recommended** choice for configuring Puppeteer.

View File

@ -0,0 +1,107 @@
# Evaluate JavaScript
Puppeteer allows evaluating JavaScript functions in the context of the page
driven by Puppeteer:
```ts
// Import puppeteer
import puppeteer from 'puppeteer';
(async () => {
// Launch the browser
const browser = await puppeteer.launch();
// Create a page
const page = await browser.newPage();
// Go to your site
await page.goto('YOUR_SITE');
// Evaluate JavaScript
const three = await page.evaluate(() => {
return 1 + 2;
});
console.log(three);
// Close browser.
await browser.close();
})();
```
:::caution
Although the function is defined in your script context, it actually gets
stringified by Puppeteer, sent to the target page over Chrome DevTools protocol
and evaluated there. It means that the function cannot access scope variables in
your script.
:::
Alternatively, you can provide a function body as a string:
```ts
// Evaluate JavaScript
const three = await page.evaluate(`
1 + 2
`);
```
:::caution
The example above produces the equivalent results but it also illustrates that
the types and global variables available to the evaluated function cannot be
known. Especially, in TypeScript you should be careful to make sure that objects
referenced by the evaluated function are correct.
:::
## Return types
The functions you evaluate can return values. If the returned value is of a
primitive type, it gets automatically converted by Puppeteer to a primitive type
in the script context like in the previous example.
If the script returns an object, Puppeteer serializes it to a JSON and reconstructs it on the script side. This process might not always yield correct results, for example, when you return a DOM node:
```ts
const body = await page.evaluate(() => {
return document.body;
});
console.log(body); // {}, unexpected!
```
To work with the returned objects, Puppeteer offers a way to return objects by reference:
```ts
const body = await page.evaluateHandle(() => {
return document.body;
});
console.log(body instanceof ElementHandle); // true
```
The returned object is either a `JSHandle` or a `ElementHandle`. `ElementHandle` extends `JSONHandle` and it is only created for DOM elements.
See the [API documentation](https://pptr.dev/api) for more details about what methods are available for handles.
## Passing arguments to the evaluate function
You can provide arguments to your function:
```ts
const three = await page.evaluate(
(a, b) => {
return 1 + 2;
},
1,
2
);
```
The arguments can primitive values or `JSHandle`s.
:::note
Page, JSHandle and ElementHandle offer several different helpers to evaluate JavaScript but they all follow the basic principles outlined in this guide.
:::

View File

@ -6,7 +6,7 @@ continued, responded or aborted.
An example of a naïve request interceptor that aborts all image requests: An example of a naïve request interceptor that aborts all image requests:
```js ```js
const puppeteer = require('puppeteer'); import puppeteer from 'puppeteer';
(async () => { (async () => {
const browser = await puppeteer.launch(); const browser = await puppeteer.launch();

View File

@ -1,5 +1,12 @@
# Troubleshooting # Troubleshooting
:::caution
Chromium currently does not provide arm64 binaries for Linux. There are only binaries
for [Mac ARM with experimental support from Puppeteer](https://pptr.dev/contributing#macos-arm-and-custom-executables).
:::
## `Cannot find module 'puppeteer-core/internal/...'` ## `Cannot find module 'puppeteer-core/internal/...'`
This can occur is your Node.js version is lower than 14 or you are using a This can occur is your Node.js version is lower than 14 or you are using a
@ -75,7 +82,6 @@ missing. The common ones are provided below.
``` ```
ca-certificates ca-certificates
fonts-liberation fonts-liberation
libappindicator3-1
libasound2 libasound2
libatk-bridge2.0-0 libatk-bridge2.0-0
libatk1.0-0 libatk1.0-0
@ -275,6 +281,19 @@ script:
- npm test - npm test
``` ```
## Running Puppeteer on WSL (Windows subsystem for Linux)
See [this thread](https://github.com/puppeteer/puppeteer/issues/1837) with some tips specific to WSL. In a nutshell, you need to install missing dependencies by either:
1. [Installing Chrome on WSL to install all dependencies](https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps#install-google-chrome-for-linux)
2. Installing required dependencies manually: `sudo apt install libgtk-3-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2`.
:::caution
The list of required dependencies might get outdated and depend on what you already have installed.
:::
## Running Puppeteer on CircleCI ## Running Puppeteer on CircleCI
Running Puppeteer smoothly on CircleCI requires the following steps: Running Puppeteer smoothly on CircleCI requires the following steps:

View File

@ -182,7 +182,7 @@ export const enum BrowserEmittedEvents {
* An example of using a {@link Browser} to create a {@link Page}: * An example of using a {@link Browser} to create a {@link Page}:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
@ -196,7 +196,7 @@ export const enum BrowserEmittedEvents {
* An example of disconnecting from and reconnecting to a {@link Browser}: * An example of disconnecting from and reconnecting to a {@link Browser}:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();

View File

@ -390,7 +390,7 @@ export interface PageEventObject {
* This example creates a page, navigates it to a URL, and then saves a screenshot: * This example creates a page, navigates it to a URL, and then saves a screenshot:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
@ -636,7 +636,7 @@ export class Page extends EventEmitter {
* An example of a naïve request interceptor that aborts all image requests: * An example of a naïve request interceptor that aborts all image requests:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
* const page = await browser.newPage(); * const page = await browser.newPage();
@ -1161,8 +1161,8 @@ export class Page extends EventEmitter {
* An example of adding an `md5` function into the page: * An example of adding an `md5` function into the page:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* const crypto = require('crypto'); * import crypto from 'crypto';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
@ -1185,8 +1185,8 @@ export class Page extends EventEmitter {
* An example of adding a `window.readfile` function into the page: * An example of adding a `window.readfile` function into the page:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* const fs = require('fs'); * import fs from 'fs';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
@ -1865,7 +1865,7 @@ export class Page extends EventEmitter {
* @example * @example
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
@ -2371,7 +2371,7 @@ export class Page extends EventEmitter {
* This method works across navigations: * This method works across navigations:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
* const page = await browser.newPage(); * const page = await browser.newPage();
@ -2431,7 +2431,7 @@ export class Page extends EventEmitter {
* This method works across navigation * This method works across navigation
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
* const page = await browser.newPage(); * const page = await browser.newPage();
@ -2491,7 +2491,7 @@ export class Page extends EventEmitter {
* The {@link Page.waitForFunction} can be used to observe viewport size change: * The {@link Page.waitForFunction} can be used to observe viewport size change:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
* const page = await browser.newPage(); * const page = await browser.newPage();

View File

@ -26,7 +26,7 @@ import {Protocol} from 'devtools-protocol';
* @example * @example
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();

View File

@ -53,7 +53,7 @@ const applyOffsetsToQuad = (
* ElementHandles can be created with the {@link Page.$} method. * ElementHandles can be created with the {@link Page.$} method.
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
@ -296,7 +296,7 @@ export class ElementHandle<
* @example * @example
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
@ -356,7 +356,7 @@ export class ElementHandle<
* This method works across navigation. * This method works across navigation.
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
* const page = await browser.newPage(); * const page = await browser.newPage();

View File

@ -127,7 +127,7 @@ export interface FrameAddStyleTagOptions {
* An example of dumping frame tree: * An example of dumping frame tree:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
@ -569,7 +569,7 @@ export class Frame {
* @example * @example
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();
@ -647,7 +647,7 @@ export class Frame {
* The `waitForFunction` can be used to observe viewport size change: * The `waitForFunction` can be used to observe viewport size change:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* . const browser = await puppeteer.launch(); * . const browser = await puppeteer.launch();

View File

@ -26,6 +26,11 @@ import {TargetManager} from './TargetManager.js';
import {CDPPage} from './Page.js'; import {CDPPage} from './Page.js';
/** /**
* Target represents a
* {@link https://chromedevtools.github.io/devtools-protocol/tot/Target/ | CDP target}.
* In CDP a target is something that can be debugged such a frame, a page or a
* worker.
*
* @public * @public
*/ */
export class Target { export class Target {

View File

@ -64,7 +64,7 @@ export interface PuppeteerLaunchOptions
* The following is a typical example of using Puppeteer to drive automation: * The following is a typical example of using Puppeteer to drive automation:
* *
* ```ts * ```ts
* const puppeteer = require('puppeteer'); * import puppeteer from 'puppeteer';
* *
* (async () => { * (async () => {
* const browser = await puppeteer.launch(); * const browser = await puppeteer.launch();

View File

@ -1,4 +1,4 @@
# Puppeteer unit tests # Puppeteer tests
Unit tests in Puppeteer are written using [Mocha] as the test runner and [Expect] as the assertions library. Unit tests in Puppeteer are written using [Mocha] as the test runner and [Expect] as the assertions library.
@ -25,19 +25,11 @@ The best place to look is an existing test to see how they use the helpers.
## Skipping tests in specific conditions ## Skipping tests in specific conditions
Tests that are not expected to pass in Firefox can be skipped. You can skip an individual test by using `itFailsFirefox` rather than `it`. Similarly you can skip a describe block with `describeFailsFirefox`. To skip tests edit the [TestExpecations](https://github.com/puppeteer/puppeteer/blob/main/test/TestExpectations.json) file. See [test runner documentation](https://github.com/puppeteer/puppeteer/tree/main/tools/mochaRunner) for more details.
There is also `describeChromeOnly` and `itChromeOnly` which will only execute the test if running in Chromium. Note that this is different from `describeFailsFirefox`: the goal is to get any `FailsFirefox` calls passing in Firefox, whereas `describeChromeOnly` should be used to test behaviour that will only ever apply in Chromium.
There are also tests that assume a normal install flow, with browser binaries ending up in `.local-<browser>`, for example. Such tests are skipped with
`itOnlyRegularInstall` which checks `BINARY` and `PUPPETEER_ALT_INSTALL` environment variables.
[mocha]: https://mochajs.org/
[expect]: https://www.npmjs.com/package/expect
## Running tests ## Running tests
- To run all tests: - To run all tests applicable for your platform:
```bash ```bash
npm test npm test
@ -46,7 +38,7 @@ npm test
- **Important**: don't forget to first build the code if you're testing local changes: - **Important**: don't forget to first build the code if you're testing local changes:
```bash ```bash
npm run build:test && npm test npm run build && npm test
``` ```
- To run a specific test, substitute the `it` with `it.only`: - To run a specific test, substitute the `it` with `it.only`:
@ -60,12 +52,11 @@ npm run build:test && npm test
}); });
``` ```
- To disable a specific test, substitute the `it` with `xit` (mnemonic rule: '_cross it_'): - To disable a specific test, substitute the `it` with `it.skip`:
```ts ```ts
... ...
// Using "xit" to skip specific test it.skip('should work', async function({server, page}) {
xit('should work', async function({server, page}) {
const {server, page} = getTestState(); const {server, page} = getTestState();
const response = await page.goto(server.EMPTY_PAGE); const response = await page.goto(server.EMPTY_PAGE);
expect(response.ok).toBe(true); expect(response.ok).toBe(true);
@ -83,3 +74,6 @@ npm run test:chrome:headful
```bash ```bash
BINARY=<path-to-executable> npm run test:chrome:headless # Or npm run test:firefox BINARY=<path-to-executable> npm run test:chrome:headless # Or npm run test:firefox
``` ```
[mocha]: https://mochajs.org/
[expect]: https://www.npmjs.com/package/expect

View File

@ -14,6 +14,7 @@ module.exports = {
items: [ items: [
'guides/configuration', 'guides/configuration',
'guides/query-selectors', 'guides/query-selectors',
'guides/evaluate-javascript',
'guides/docker', 'guides/docker',
'guides/request-interception', 'guides/request-interception',
'guides/chrome-extensions', 'guides/chrome-extensions',