diff --git a/docs/api/index.md b/docs/api/index.md index 1831c8af3c9c3..09fa283fa5530 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -35,7 +35,7 @@ sidebar_label: API | [Puppeteer](./puppeteer.puppeteer.md) |

The main Puppeteer class.

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 puppeteer. That class extends Puppeteer, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).

| | [PuppeteerNode](./puppeteer.puppeteernode.md) |

Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.

If you're using Puppeteer in a Node environment, this is the class you'll get when you run require('puppeteer') (or the equivalent ES import).

| | [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. | | [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | | [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | diff --git a/docs/api/puppeteer.browser.md b/docs/api/puppeteer.browser.md index 49635992038e9..bfee6200652d7 100644 --- a/docs/api/puppeteer.browser.md +++ b/docs/api/puppeteer.browser.md @@ -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): ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { 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): ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.dialog.md b/docs/api/puppeteer.dialog.md index 5e502b741c5c0..4851c802268b1 100644 --- a/docs/api/puppeteer.dialog.md +++ b/docs/api/puppeteer.dialog.md @@ -19,7 +19,7 @@ The constructor for this class is marked as internal. Third-party code should no ## Example ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.elementhandle.md b/docs/api/puppeteer.elementhandle.md index da21732546a61..b1f6f25e50162 100644 --- a/docs/api/puppeteer.elementhandle.md +++ b/docs/api/puppeteer.elementhandle.md @@ -19,7 +19,7 @@ export declare class ElementHandle extends J ElementHandles can be created with the [Page.$()](./puppeteer.page._.md) method. ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.elementhandle.waitforselector.md b/docs/api/puppeteer.elementhandle.waitforselector.md index 0de94904c03fe..fe077b64ff290 100644 --- a/docs/api/puppeteer.elementhandle.waitforselector.md +++ b/docs/api/puppeteer.elementhandle.waitforselector.md @@ -39,7 +39,7 @@ Throws if an element matching the given selector doesn't appear. ## Example ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.elementhandle.waitforxpath.md b/docs/api/puppeteer.elementhandle.waitforxpath.md index bbcf387b34ee6..63307f8b95c0f 100644 --- a/docs/api/puppeteer.elementhandle.waitforxpath.md +++ b/docs/api/puppeteer.elementhandle.waitforxpath.md @@ -19,7 +19,7 @@ sidebar_label: ElementHandle.waitForXPath > This method works across navigation. > > ```ts -> const puppeteer = require('puppeteer'); +> import puppeteer from 'puppeteer'; > (async () => { > const browser = await puppeteer.launch(); > const page = await browser.newPage(); diff --git a/docs/api/puppeteer.frame.md b/docs/api/puppeteer.frame.md index f3a537a464c6c..ad1806f23fa1d 100644 --- a/docs/api/puppeteer.frame.md +++ b/docs/api/puppeteer.frame.md @@ -31,7 +31,7 @@ At any point in time, [pages](./puppeteer.page.md) expose their current frame tr An example of dumping frame tree: ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.frame.waitforfunction.md b/docs/api/puppeteer.frame.waitforfunction.md index 8ee6809d5eed1..7c9ec9c82101d 100644 --- a/docs/api/puppeteer.frame.waitforfunction.md +++ b/docs/api/puppeteer.frame.waitforfunction.md @@ -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: ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { . const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.frame.waitforselector.md b/docs/api/puppeteer.frame.waitforselector.md index 6c7a49892f2af..11836924916cf 100644 --- a/docs/api/puppeteer.frame.waitforselector.md +++ b/docs/api/puppeteer.frame.waitforselector.md @@ -39,7 +39,7 @@ Throws if an element matching the given selector doesn't appear. ## Example ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.page.emulatevisiondeficiency.md b/docs/api/puppeteer.page.emulatevisiondeficiency.md index e4d9c2c37c658..2d8ebc7aca619 100644 --- a/docs/api/puppeteer.page.emulatevisiondeficiency.md +++ b/docs/api/puppeteer.page.emulatevisiondeficiency.md @@ -29,7 +29,7 @@ Promise<void> ## Example ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.page.exposefunction.md b/docs/api/puppeteer.page.exposefunction.md index 62459eb7305cf..de6584e4fba26 100644 --- a/docs/api/puppeteer.page.exposefunction.md +++ b/docs/api/puppeteer.page.exposefunction.md @@ -45,8 +45,8 @@ Promise<void> An example of adding an `md5` function into the page: ```ts -const puppeteer = require('puppeteer'); -const crypto = require('crypto'); +import puppeteer from 'puppeteer'; +import crypto from 'crypto'; (async () => { const browser = await puppeteer.launch(); @@ -70,8 +70,8 @@ const crypto = require('crypto'); An example of adding a `window.readfile` function into the page: ```ts -const puppeteer = require('puppeteer'); -const fs = require('fs'); +import puppeteer from 'puppeteer'; +import fs from 'fs'; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md index 894611a3f3eea..63206340ddb58 100644 --- a/docs/api/puppeteer.page.md +++ b/docs/api/puppeteer.page.md @@ -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: ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); @@ -157,7 +157,7 @@ page.off('request', logRequest); | [waitForSelector(selector, options)](./puppeteer.page.waitforselector.md) | |

Wait for the selector to appear in page. If at the moment of calling the method the selector already exists, the method will return immediately. If the selector doesn't appear after the timeout milliseconds of waiting, the function will throw.

This method works across navigations:

| ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); @@ -181,7 +181,7 @@ const puppeteer = require('puppeteer'); | [waitForXPath(xpath, options)](./puppeteer.page.waitforxpath.md) | |

Wait for the xpath to appear in page. If at the moment of calling the method the xpath already exists, the method will return immediately. If the xpath doesn't appear after the timeout milliseconds of waiting, the function will throw.

This method works across navigation

```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); diff --git a/docs/api/puppeteer.page.setrequestinterception.md b/docs/api/puppeteer.page.setrequestinterception.md index cdc6b9e3b6251..77d9d392e254f 100644 --- a/docs/api/puppeteer.page.setrequestinterception.md +++ b/docs/api/puppeteer.page.setrequestinterception.md @@ -33,7 +33,7 @@ Promise<void> An example of a naïve request interceptor that aborts all image requests: ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); diff --git a/docs/api/puppeteer.page.waitforfunction.md b/docs/api/puppeteer.page.waitforfunction.md index e63bdce874e54..d1d644e5b8748 100644 --- a/docs/api/puppeteer.page.waitforfunction.md +++ b/docs/api/puppeteer.page.waitforfunction.md @@ -38,7 +38,7 @@ Promise<[HandleFor](./puppeteer.handlefor.md)<Awaited<ReturnType<Fun The [Page.waitForFunction()](./puppeteer.page.waitforfunction.md) can be used to observe viewport size change: ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); diff --git a/docs/api/puppeteer.page.waitforselector.md b/docs/api/puppeteer.page.waitforselector.md index 6c3f77b056949..c150c51a56913 100644 --- a/docs/api/puppeteer.page.waitforselector.md +++ b/docs/api/puppeteer.page.waitforselector.md @@ -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: ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); diff --git a/docs/api/puppeteer.page.waitforxpath.md b/docs/api/puppeteer.page.waitforxpath.md index cc9703ccb3b15..e018da2fac78b 100644 --- a/docs/api/puppeteer.page.waitforxpath.md +++ b/docs/api/puppeteer.page.waitforxpath.md @@ -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 ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); const page = await browser.newPage(); diff --git a/docs/api/puppeteer.puppeteernode.md b/docs/api/puppeteer.puppeteernode.md index 7e1c5efb24db2..e967a6956b3a9 100644 --- a/docs/api/puppeteer.puppeteernode.md +++ b/docs/api/puppeteer.puppeteernode.md @@ -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: ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/api/puppeteer.target.md b/docs/api/puppeteer.target.md index 4c27b17a63227..dfb7f2a2149bb 100644 --- a/docs/api/puppeteer.target.md +++ b/docs/api/puppeteer.target.md @@ -4,6 +4,8 @@ sidebar_label: Target # 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: ```typescript diff --git a/docs/guides/chrome-extensions.md b/docs/guides/chrome-extensions.md index 0bc8d71b0a53f..3fcabf9bc98fc 100644 --- a/docs/guides/chrome-extensions.md +++ b/docs/guides/chrome-extensions.md @@ -14,10 +14,11 @@ The following is code for getting a handle to the an extension whose source is located in `./my-extension`: ```ts -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; +import path from 'path'; (async () => { - const pathToExtension = require('path').join(__dirname, 'my-extension'); + const pathToExtension = path.join(process.cwd(), 'my-extension'); const browser = await puppeteer.launch({ headless: 'chrome', args: [ diff --git a/docs/guides/configuration.mdx b/docs/guides/configuration.mdx index a94e205869477..a9fd3885cffa0 100644 --- a/docs/guides/configuration.mdx +++ b/docs/guides/configuration.mdx @@ -17,6 +17,12 @@ as `HTTPS_PROXY`). ::: +:::caution + +Puppeteer's configuration files and environment variables are ignored by `puppeteer-core`. + +::: + ## Configuration files Configuration files are the **recommended** choice for configuring Puppeteer. diff --git a/docs/guides/evaluate-javascript.md b/docs/guides/evaluate-javascript.md new file mode 100644 index 0000000000000..03524ac66cc60 --- /dev/null +++ b/docs/guides/evaluate-javascript.md @@ -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. + +::: diff --git a/docs/guides/request-interception.md b/docs/guides/request-interception.md index b1591ec10f1d0..0b4a50a7f2439 100644 --- a/docs/guides/request-interception.md +++ b/docs/guides/request-interception.md @@ -6,7 +6,7 @@ continued, responded or aborted. An example of a naïve request interceptor that aborts all image requests: ```js -const puppeteer = require('puppeteer'); +import puppeteer from 'puppeteer'; (async () => { const browser = await puppeteer.launch(); diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 8bc91b8de06c7..2036da56059c9 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,5 +1,12 @@ # 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/...'` 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 fonts-liberation -libappindicator3-1 libasound2 libatk-bridge2.0-0 libatk1.0-0 @@ -275,6 +281,19 @@ script: - 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 smoothly on CircleCI requires the following steps: diff --git a/packages/puppeteer-core/src/api/Browser.ts b/packages/puppeteer-core/src/api/Browser.ts index 5d317fba84f0a..f7103f24ee8e2 100644 --- a/packages/puppeteer-core/src/api/Browser.ts +++ b/packages/puppeteer-core/src/api/Browser.ts @@ -182,7 +182,7 @@ export const enum BrowserEmittedEvents { * An example of using a {@link Browser} to create a {@link Page}: * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * const browser = await puppeteer.launch(); @@ -196,7 +196,7 @@ export const enum BrowserEmittedEvents { * An example of disconnecting from and reconnecting to a {@link Browser}: * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * const browser = await puppeteer.launch(); diff --git a/packages/puppeteer-core/src/api/Page.ts b/packages/puppeteer-core/src/api/Page.ts index 751520f0aa7eb..2fbeb388a38a1 100644 --- a/packages/puppeteer-core/src/api/Page.ts +++ b/packages/puppeteer-core/src/api/Page.ts @@ -390,7 +390,7 @@ export interface PageEventObject { * This example creates a page, navigates it to a URL, and then saves a screenshot: * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * 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: * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * (async () => { * const browser = await puppeteer.launch(); * const page = await browser.newPage(); @@ -1161,8 +1161,8 @@ export class Page extends EventEmitter { * An example of adding an `md5` function into the page: * * ```ts - * const puppeteer = require('puppeteer'); - * const crypto = require('crypto'); + * import puppeteer from 'puppeteer'; + * import crypto from 'crypto'; * * (async () => { * 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: * * ```ts - * const puppeteer = require('puppeteer'); - * const fs = require('fs'); + * import puppeteer from 'puppeteer'; + * import fs from 'fs'; * * (async () => { * const browser = await puppeteer.launch(); @@ -1865,7 +1865,7 @@ export class Page extends EventEmitter { * @example * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * const browser = await puppeteer.launch(); @@ -2371,7 +2371,7 @@ export class Page extends EventEmitter { * This method works across navigations: * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * (async () => { * const browser = await puppeteer.launch(); * const page = await browser.newPage(); @@ -2431,7 +2431,7 @@ export class Page extends EventEmitter { * This method works across navigation * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * (async () => { * const browser = await puppeteer.launch(); * 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: * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * (async () => { * const browser = await puppeteer.launch(); * const page = await browser.newPage(); diff --git a/packages/puppeteer-core/src/common/Dialog.ts b/packages/puppeteer-core/src/common/Dialog.ts index 6d84fd0d0b805..3fdad2d76e6d6 100644 --- a/packages/puppeteer-core/src/common/Dialog.ts +++ b/packages/puppeteer-core/src/common/Dialog.ts @@ -26,7 +26,7 @@ import {Protocol} from 'devtools-protocol'; * @example * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * const browser = await puppeteer.launch(); diff --git a/packages/puppeteer-core/src/common/ElementHandle.ts b/packages/puppeteer-core/src/common/ElementHandle.ts index dc329268338ef..a59daf92c70d1 100644 --- a/packages/puppeteer-core/src/common/ElementHandle.ts +++ b/packages/puppeteer-core/src/common/ElementHandle.ts @@ -53,7 +53,7 @@ const applyOffsetsToQuad = ( * ElementHandles can be created with the {@link Page.$} method. * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * const browser = await puppeteer.launch(); @@ -296,7 +296,7 @@ export class ElementHandle< * @example * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * const browser = await puppeteer.launch(); @@ -356,7 +356,7 @@ export class ElementHandle< * This method works across navigation. * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * (async () => { * const browser = await puppeteer.launch(); * const page = await browser.newPage(); diff --git a/packages/puppeteer-core/src/common/Frame.ts b/packages/puppeteer-core/src/common/Frame.ts index 89a31d5b16855..ae679f4e2323f 100644 --- a/packages/puppeteer-core/src/common/Frame.ts +++ b/packages/puppeteer-core/src/common/Frame.ts @@ -127,7 +127,7 @@ export interface FrameAddStyleTagOptions { * An example of dumping frame tree: * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * const browser = await puppeteer.launch(); @@ -569,7 +569,7 @@ export class Frame { * @example * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * const browser = await puppeteer.launch(); @@ -647,7 +647,7 @@ export class Frame { * The `waitForFunction` can be used to observe viewport size change: * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * . const browser = await puppeteer.launch(); diff --git a/packages/puppeteer-core/src/common/Target.ts b/packages/puppeteer-core/src/common/Target.ts index ceb0559681f4f..7f63666ea1969 100644 --- a/packages/puppeteer-core/src/common/Target.ts +++ b/packages/puppeteer-core/src/common/Target.ts @@ -26,6 +26,11 @@ import {TargetManager} from './TargetManager.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 */ export class Target { diff --git a/packages/puppeteer-core/src/node/PuppeteerNode.ts b/packages/puppeteer-core/src/node/PuppeteerNode.ts index 4ab74aca48879..81c8614b483cf 100644 --- a/packages/puppeteer-core/src/node/PuppeteerNode.ts +++ b/packages/puppeteer-core/src/node/PuppeteerNode.ts @@ -64,7 +64,7 @@ export interface PuppeteerLaunchOptions * The following is a typical example of using Puppeteer to drive automation: * * ```ts - * const puppeteer = require('puppeteer'); + * import puppeteer from 'puppeteer'; * * (async () => { * const browser = await puppeteer.launch(); diff --git a/test/README.md b/test/README.md index a0d6c839a9000..69254086f1e69 100644 --- a/test/README.md +++ b/test/README.md @@ -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. @@ -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 -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`. - -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-`, 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 +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. ## Running tests -- To run all tests: +- To run all tests applicable for your platform: ```bash npm test @@ -46,7 +38,7 @@ npm test - **Important**: don't forget to first build the code if you're testing local changes: ```bash -npm run build:test && npm test +npm run build && npm test ``` - 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 ... - // Using "xit" to skip specific test - xit('should work', async function({server, page}) { + it.skip('should work', async function({server, page}) { const {server, page} = getTestState(); const response = await page.goto(server.EMPTY_PAGE); expect(response.ok).toBe(true); @@ -83,3 +74,6 @@ npm run test:chrome:headful ```bash BINARY= npm run test:chrome:headless # Or npm run test:firefox ``` + +[mocha]: https://mochajs.org/ +[expect]: https://www.npmjs.com/package/expect diff --git a/website/sidebars.js b/website/sidebars.js index 348d95c83e0bf..fd9817f8344d9 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -14,6 +14,7 @@ module.exports = { items: [ 'guides/configuration', 'guides/query-selectors', + 'guides/evaluate-javascript', 'guides/docker', 'guides/request-interception', 'guides/chrome-extensions',