diff --git a/docs/api/index.md b/docs/api/index.md index 1831c8af3c9..09fa283fa55 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 49635992038..bfee6200652 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 5e502b741c5..4851c802268 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 da21732546a..b1f6f25e501 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 0de94904c03..fe077b64ff2 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 bbcf387b34e..63307f8b95c 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 f3a537a464c..ad1806f23fa 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 8ee6809d5ee..7c9ec9c8210 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 6c7a49892f2..11836924916 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 e4d9c2c37c6..2d8ebc7aca6 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 62459eb7305..de6584e4fba 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 894611a3f3e..63206340ddb 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 cdc6b9e3b62..77d9d392e25 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 e63bdce874e..d1d644e5b87 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 6c3f77b0569..c150c51a569 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 cc9703ccb3b..e018da2fac7 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 7e1c5efb24d..e967a6956b3 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 4c27b17a632..dfb7f2a2149 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 0bc8d71b0a5..3fcabf9bc98 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 a94e2058694..a9fd3885cff 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 00000000000..03524ac66cc --- /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 b1591ec10f1..0b4a50a7f24 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 8bc91b8de06..2036da56059 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 5d317fba84f..f7103f24ee8 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 751520f0aa7..2fbeb388a38 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 6d84fd0d0b8..3fdad2d76e6 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 dc329268338..a59daf92c70 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 89a31d5b168..ae679f4e232 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 ceb0559681f..7f63666ea19 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 4ab74aca488..81c8614b483 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 a0d6c839a90..69254086f1e 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 348d95c83e0..fd9817f8344 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',