Puppeteer

https://pptr.dev/
Admin
Puppeteer is a JavaScript library that provides a high-level API to control Chrome or Firefox over...
Tokens:43,358
Snippets:603
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install browsers via CLI

Source: https://pptr.dev/guides/configuration

Run these commands to install browsers after modifying download configuration options.

```bash
npx puppeteer browsers install
```

```bash
yarn dlx puppeteer browsers install
```

```bash
pnpm dlx puppeteer browsers install
```

```bash
bun x puppeteer browsers install
```

--------------------------------

### Install dependencies

Source: https://pptr.dev/contributing

Commands to install project dependencies, with an optional flag to download Firefox.

```bash
npm install  

# Or to download Firefox by default  

PUPPETEER_BROWSER=firefox npm install  
```

--------------------------------

### install(options)

Source: https://pptr.dev/browsers-api

Downloads and unpacks the browser archive according to the InstallOptions.

```APIDOC
## install(options)

### Description
Downloads and unpacks the browser archive according to the InstallOptions.
```

--------------------------------

### Listing Installed Browsers

Source: https://pptr.dev/browsers-api

Lists all currently installed browser binaries.

```bash
npx @puppeteer/browsers list
```

--------------------------------

### Load extensions at runtime

Source: https://pptr.dev/guides/chrome-extensions

Install an extension dynamically after the browser has launched using installExtension.

```javascript
import puppeteer from 'puppeteer';  

import path from 'path';  

  

const pathToExtension = path.join(process.cwd(), 'my-extension');  

const browser = await puppeteer.launch({  

  enableExtensions: true,  

});  

  

const extensionId = await browser.installExtension(pathToExtension);  
```

--------------------------------

### Manually install browsers

Source: https://pptr.dev/

Commands to download required browsers if automatic installation scripts are blocked by the package manager.

```bash
npx puppeteer browsers install  
```

```bash
yarn dlx puppeteer browsers install  
```

```bash
pnpm dlx puppeteer browsers install  
```

```bash
bun x puppeteer browsers install  
```

--------------------------------

### Install Puppeteer

Source: https://pptr.dev/guides/installation

Commands to install the Puppeteer package using different package managers.

```bash
npm i puppeteer
```

```bash
yarn add puppeteer
```

```bash
pnpm add puppeteer
```

```bash
bun add puppeteer
```

--------------------------------

### ElementHandle.touchStart()

Source: https://pptr.dev/api/puppeteer.elementhandle.touchstart

Scrolls the element into view if needed, and then starts a touch in the center of the element.

```APIDOC
## ElementHandle.touchStart()

### Description
Scrolls the element into view if needed, and then starts a touch in the center of the element.

### Signature
`touchStart(): Promise<TouchHandle>`

### Returns
- **Promise<TouchHandle>** - A TouchHandle representing the touch that was started.
```

--------------------------------

### Configure allowScripts for npm

Source: https://pptr.dev/guides/installation

Example configuration for package.json to allow postinstall scripts for Puppeteer.

```json
{
  "allowScripts": {
    "puppeteer": true
  }
}
```

--------------------------------

### Implementing getExecutablePath

Source: https://pptr.dev/browsers-api/browsers.browserprovider.getexecutablepath

Examples showing both static path returns and dynamic paths based on browser and platform options.

```javascript
// Electron uses simple structure  

getExecutablePath() {  

  return 'chromedriver/chromedriver';  

}  

  

// Custom provider with platform-specific paths  

getExecutablePath(options) {  

  return `binaries/${options.browser}-${options.platform}`;  

}  
```

--------------------------------

### Use custom provider with install API

Source: https://pptr.dev/browsers-api

Pass the custom provider instance to the install function to utilize it during browser installation.

```typescript
import {install} from '@puppeteer/browsers';

const customProvider = new SimpleMirrorProvider('https://internal.company.com');

await install({
  browser: Browser.CHROME,
  buildId: '120.0.6099.109',
  platform: BrowserPlatform.LINUX,
  cacheDir: '/tmp/puppeteer-cache',
  providers: [customProvider],
});
```

--------------------------------

### Installing Browsers and Drivers

Source: https://pptr.dev/browsers-api

Commands for downloading specific browser or driver versions, including system dependency installation for Chrome on Linux.

```bash
# Download the latest available Chrome for Testing binary corresponding to the Stable channel.  
npx @puppeteer/browsers install chrome@stable  
  
# Download a specific Chrome for Testing version.  
npx @puppeteer/browsers install chrome@116.0.5793.0  
  
# Download the latest Chrome for Testing version for the given milestone.  
npx @puppeteer/browsers install chrome@117  
  
# Download the latest available ChromeDriver version corresponding to the Canary channel.  
npx @puppeteer/browsers install chromedriver@canary  
  
# Download a specific ChromeDriver version.  
npx @puppeteer/browsers install chromedriver@116.0.5793.0  
  
# On Ubuntu/Debian and only for Chrome, install the browser and required system dependencies.  
# If the browser version has already been installed, the command  
# will still attempt to install system dependencies.  
# Requires root privileges.  
npx puppeteer browsers install chrome --install-deps
```

--------------------------------

### Start dbus service

Source: https://pptr.dev/guides/docker

Command to start the dbus service if required to suppress browser console warnings.

```bash
sudo service dbus start  
```

--------------------------------

### Tracing.start() signature

Source: https://pptr.dev/api/puppeteer.tracing.start

The method signature for starting a trace.

```typescript
class Tracing {  

  start(options?: TracingOptions): Promise<void>;  

}  
```

--------------------------------

### Install proxy-agent package

Source: https://pptr.dev/browsers-api

Required dependency for proxy support in the library and CLI.

```bash
npm install proxy-agent
```

--------------------------------

### Run E2E Tests

Source: https://pptr.dev/guides/ng-schematics

Execute this command to run the configured E2E tests after installation.

```bash
ng e2e
```

--------------------------------

### computeSystemExecutablePath(options, validatePath)

Source: https://pptr.dev/browsers-api

Returns a path to a system-wide Chrome installation given a release channel name by checking known installation locations. If Chrome instance is not found at the expected path, an error is thrown.

```APIDOC
## computeSystemExecutablePath(options, validatePath)

### Description
Returns a path to a system-wide Chrome installation given a release channel name by checking known installation locations. If Chrome instance is not found at the expected path, an error is thrown.

### Parameters
- **options** (object) - Required - Configuration options for locating the executable.
- **validatePath** (boolean) - Optional - Whether to validate the path existence.
```

--------------------------------

### InstalledBrowser.writeMetadata(metadata)

Source: https://pptr.dev/browsers-api/browsers.installedbrowser.writemetadata

Writes metadata to the installed browser instance.

```APIDOC
## InstalledBrowser.writeMetadata()

### Description
Writes the provided metadata to the installed browser instance.

### Signature
`writeMetadata(metadata: Metadata): void;`

### Parameters
- **metadata** (Metadata) - Required - The metadata object to be written.

### Returns
- **void**
```

--------------------------------

### Tracing.start(options?: TracingOptions)

Source: https://pptr.dev/api/puppeteer.tracing.start

Starts a trace for the current page. Only one trace can be active at a time per browser.

```APIDOC
## Tracing.start(options?: TracingOptions)

### Description
Starts a trace for the current page. Only one trace can be active at a time per browser.

### Signature
`start(options?: TracingOptions): Promise<void>`

### Parameters
- **options** (TracingOptions) - Optional - Optional configuration for the trace.

### Returns
- **Promise<void>** - A promise that resolves when the trace has started.
```

--------------------------------

### Install Chromium on Amazon Linux

Source: https://pptr.dev/troubleshooting

Installs the Chromium browser package via yum after enabling the EPEL repository.

```bash
sudo yum install -y chromium
```

--------------------------------

### Install Puppeteer dependencies on WSL

Source: https://pptr.dev/troubleshooting

Command to install necessary system libraries for Puppeteer on WSL environments.

```bash
sudo apt install libgtk-3-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2
```

--------------------------------

### Wait for navigation example

Source: https://pptr.dev/api/puppeteer.frame.waitfornavigation

Demonstrates using Promise.all to wait for a navigation event triggered by a click action.

```javascript
const [response] = await Promise.all([  

  // The navigation promise resolves after navigation has finished  

  frame.waitForNavigation(),  

  // Clicking the link will indirectly cause a navigation  

  frame.click('a.my-link'),  

]);  
```

--------------------------------

### Configure Travis CI for Puppeteer

Source: https://pptr.dev/troubleshooting

Example configuration for a .travis.yml file to support Puppeteer testing.

```yaml
language: node_js  

node_js: node  

services: xvfb  

script:  

  - npm test  
```

--------------------------------

### Clearing Installed Browsers

Source: https://pptr.dev/browsers-api

Removes all installed browser binaries.

```bash
npx @puppeteer/browsers clear
```

--------------------------------

### getInstalledBrowsers(options)

Source: https://pptr.dev/browsers-api

Returns metadata about browsers installed in the cache directory.

```APIDOC
## getInstalledBrowsers(options)

### Description
Returns metadata about browsers installed in the cache directory.

### Parameters
- **options** (object) - Optional - Configuration options for filtering or locating installed browsers.
```

--------------------------------

### Install EPEL on Amazon Linux

Source: https://pptr.dev/troubleshooting

Enables the extra packages repository required to install Chromium dependencies on Amazon Linux EC2 instances.

```bash
sudo amazon-linux-extras install epel -y
```

--------------------------------

### Configure GitlabCI dependencies

Source: https://pptr.dev/troubleshooting

Required system packages to install in the Docker environment before launching headless Chrome.

```yaml

before_script:  

  - apt-get update  

  - apt-get install -yq gconf-service libasound2 libatk1.0-0 libc6 libcairo2  

    libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libgconf-2-4  

    libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0  

    libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1  

    libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1  

    libxss1 libxtst6 ca-certificates fonts-liberation libnss3 lsb-release  

    xdg-utils wget  


```

--------------------------------

### Identify Chrome launch errors

Source: https://pptr.dev/troubleshooting

Example of the error message encountered when dependencies are missing in a CI environment.

```text

Error: Failed to launch chrome! spawn /usr/bin/chromium-browser ENOENT  


```

--------------------------------

### InstalledBrowser.writeMetadata() signature

Source: https://pptr.dev/browsers-api/browsers.installedbrowser.writemetadata

Defines the method signature for writing metadata to an installed browser.

```typescript
class InstalledBrowser {  

  writeMetadata(metadata: Metadata): void;  

}  
```

--------------------------------

### Enable verbose debugging

Source: https://pptr.dev/browsers-api

Use the NODE_DEBUG environment variable to inspect browser installation and launching operations.

```bash
env NODE_DEBUG="puppeteer:browsers:*" npx @puppeteer/browsers install chrome@stable
```

--------------------------------

### Coverage.startJSCoverage() signature

Source: https://pptr.dev/api/puppeteer.coverage.startjscoverage

Defines the method signature for starting JavaScript coverage collection.

```typescript
class Coverage {  

  startJSCoverage(options?: JSCoverageOptions): Promise<void>;  

}
```

--------------------------------

### Coverage.startJSCoverage()

Source: https://pptr.dev/api/puppeteer.coverage.startjscoverage

Starts the collection of JavaScript coverage information. This method returns a promise that resolves once coverage collection has successfully begun.

```APIDOC
## Coverage.startJSCoverage()

### Description
Starts JavaScript code coverage collection. Anonymous scripts can be included by configuring the options.

### Signature
`startJSCoverage(options?: JSCoverageOptions): Promise<void>`

### Parameters
- **options** (JSCoverageOptions) - Optional - Set of configurable options for coverage. Defaults to `resetOnNavigation: true`, `reportAnonymousScripts: false`, `includeRawScriptCoverage: false`, and `useBlockCoverage: true`.

### Returns
- **Promise<void>** - A promise that resolves when coverage is started.

### Remarks
Anonymous scripts (created via `eval` or `new Function`) will have URLs starting with `debugger://VM` if `reportAnonymousScripts` is enabled, unless a `//# sourceURL` comment is present.
```

--------------------------------

### Install Puppeteer Schematic

Source: https://pptr.dev/guides/ng-schematics

Run this command in an Angular CLI project directory to add the schematic as a dependency.

```bash
ng add @puppeteer/ng-schematics
```

--------------------------------

### Run Sandbox Smoke Tests

Source: https://pptr.dev/guides/ng-schematics

Executes a fresh Angular installation and verifies schematics integration with initial e2e tests.

```bash
node tools/smoke.mjs
```

--------------------------------

### Configure Rollup for Puppeteer extension builds

Source: https://pptr.dev/guides/running-puppeteer-in-extensions

Example Rollup configuration to bundle Puppeteer for a browser environment, ensuring only puppeteer-core is resolved.

```javascript
import {nodeResolve} from '@rollup/plugin-node-resolve';  

  

export default {  

  input: 'main.mjs',  

  output: {  

    format: 'esm',  

    dir: 'out',  

  },  

  // If you do not need to use WebDriver BiDi protocol,  

  // exclude chromium-bidi/lib/bidiMapper/BidiMapper.js to minimize the bundle size.  

  external: ['chromium-bidi/lib/bidiMapper/BidiMapper.js'],  

  plugins: [  

    nodeResolve({  

      // Indicate that we target a browser environment.  

      browser: true,  

      // Exclude any dependencies except for puppeteer-core.  

      // `npm install puppeteer-core` # To install puppeteer-core if needed.  

      resolveOnly: ['puppeteer-core'],  

    }),  

  ],  

};  
```

--------------------------------

### Using legacy prefixed selector syntax

Source: https://pptr.dev/guides/locators

Shows examples of using legacy selector prefixes for text, xpath, aria, and pierce selectors.

```javascript
// Same as ::-p-text("My text").  

await page.locator('text/My text').click();  

// Same as ::-p-xpath(//h2).  

await page.locator('xpath///h2').click();  

// Same as ::-p-aria(My label).  

await page.locator('aria/My label').click();  

  

await page.locator('pierce/div').click();  
```

--------------------------------

### Protractor and Puppeteer Test Comparison

Source: https://pptr.dev/guides/ng-schematics

Examples showing a full test case migration from Protractor to Puppeteer.

```javascript
describe('Protractor Demo', function () {  
  it('should add one and two', function () {  
    browser.get('https://juliemr.github.io/protractor-demo/');  
    element(by.model('first')).sendKeys(1);  
    element(by.model('second')).sendKeys(2);  
  
    element(by.id('gobutton')).click();  
  
    expect(element(by.binding('latest')).getText()).toEqual('3');  
  });  
});
```

```typescript
import {setupBrowserHooks, getBrowserState} from './utils';  
  
describe('Puppeteer Demo', function () {  
  setupBrowserHooks();  
  it('should add one and two', function () {  
    const {page} = getBrowserState();  
    await page.goto('https://juliemr.github.io/protractor-demo/');  
  
    await page.locator('.form-inline > input:nth-child(1)').fill('1');  
    await page.locator('.form-inline > input:nth-child(2)').fill('2');  
    await page.locator('#gobutton').fill('2');  
  
    const result = await page  
      .locator('.table tbody td:last-of-type')  
      .map(header => header.innerText)  
      .wait();  
  
    expect(result).toEqual('3');  
  });  
});
```

--------------------------------

### Update NSS library on CentOS

Source: https://pptr.dev/troubleshooting

Command to update the NSS library after installing dependencies.

```bash
yum update nss -y
```

--------------------------------

### Configure Dockerfile for Puppeteer

Source: https://pptr.dev/troubleshooting

Installs required Chrome dependencies, fonts, and sets up a non-privileged user to avoid sandbox issues.

```dockerfile
FROM node:14-slim  

  

# Install latest chrome dev package and fonts to support major charsets (Chinese, Japanese, Arabic, Hebrew, Thai and a few others)  

# Note: this installs the necessary libs to make the bundled version of Chrome for Testing that Puppeteer  

# installs, work.  

RUN apt-get update \

    && apt-get install -y wget gnupg \

    && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \

    && sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \

    && apt-get update \

    && apt-get install -y google-chrome-stable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf libxss1 \

      --no-install-recommends \

    && rm -rf /var/lib/apt/lists/*  

  

# If running Docker >= 1.13.0 use docker run's --init arg to reap zombie processes, otherwise  

# uncomment the following lines to have `dumb-init` as PID 1  

# ADD https://github.com/Yelp/dumb-init/releases/download/v1.2.2/dumb-init_1.2.2_x86_64 /usr/local/bin/dumb-init  

# RUN chmod +x /usr/local/bin/dumb-init  

# ENTRYPOINT ["dumb-init", "--"]  

  

# Uncomment to skip the Chrome for Testing download when installing puppeteer. If you do,  

# you'll need to launch puppeteer with:  

#     browser.launch({executablePath: 'google-chrome-stable'})  

# ENV PUPPETEER_SKIP_DOWNLOAD true  

  

# Install puppeteer so it's available in the container.  

RUN npm init -y &&  \

    npm i puppeteer \

    # Add user so we don't need --no-sandbox.  

    # same layer as npm install to keep re-chowned files from using up several hundred MBs more space  

    && groupadd -r pptruser && useradd -r -g pptruser -G audio,video pptruser \

    && mkdir -p /home/pptruser/Downloads \

    && chown -R pptruser:pptruser /home/pptruser \

    && chown -R pptruser:pptruser /node_modules \

    && chown -R pptruser:pptruser /package.json \

    && chown -R pptruser:pptruser /package-lock.json  

  

# Run everything after as non-privileged user.  

USER pptruser  

  

CMD ["google-chrome-stable"]
```

--------------------------------

### BrowserLauncher.launch(options)

Source: https://pptr.dev/api/puppeteer.browserlauncher.launch

Launches a browser instance with optional configuration settings.

```APIDOC
## BrowserLauncher.launch()

### Description
Launches a new browser instance. Returns a Promise that resolves to a Browser object.

### Signature
`launch(options?: LaunchOptions): Promise<Browser>`

### Parameters
- **options** (LaunchOptions) - Optional - Configuration options for launching the browser.
```

--------------------------------

### Configure Dockerfile for Puppeteer on Alpine

Source: https://pptr.dev/troubleshooting

Installs required system dependencies and configures the environment to use the system-installed Chromium browser instead of downloading a separate binary.

```dockerfile
FROM alpine  

  

# Installs Chromium (100) package.  

RUN apk add --no-cache \

      chromium \

      nss \

      freetype \

      harfbuzz \

      ca-certificates \

      ttf-freefont \

      nodejs \

      yarn  

  

...  

  

# Tell Puppeteer to skip installing Chrome. We'll be using the installed package.  

ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser  

  

# Puppeteer v13.5.0 works with Chromium 100.  

RUN yarn add puppeteer@13.5.0  

  

# Add user so we don't need --no-sandbox.  

RUN addgroup -S pptruser && adduser -S -G pptruser pptruser \

    && mkdir -p /home/pptruser/Downloads /app \

    && chown -R pptruser:pptruser /home/pptruser \

    && chown -R pptruser:pptruser /app  

  

# Run everything after as non-privileged user.  

USER pptruser  

  

...  
```

--------------------------------

### Launch a browser

Source: https://pptr.dev/guides/browser-management

Initializes a new browser instance and opens a page.

```javascript
import puppeteer from 'puppeteer';  

  

const browser = await puppeteer.launch();  

  

const page = await browser.newPage();  

  

// ...  
```

--------------------------------

### Implement slow background Puppeteer launch

Source: https://pptr.dev/troubleshooting

Example of an Express route that triggers CPU throttling on Google Cloud Run by launching after the response.

```javascript

import express from 'express';  

  

const app = express();  

  

app.post('/test-puppeteer', (req, res) => {  

  res.json({  

    jobId: 123,  

    acknowledged: true,  

  });  

  

  puppeteer.launch().then(browser => {  

    // 2 minutes later...  

  });  

});  

  

app.listen(3000);  


```

--------------------------------

### Conventional Commit message example

Source: https://pptr.dev/contributing

Follow this format for commit messages, ensuring breaking changes are explicitly noted in the footer.

```text
fix(page): fix page.pizza method  
  
This patch fixes page.pizza so that it works with iframes.  
  
Issues: #123, #234  
  
BREAKING CHANGE: page.pizza now delivers pizza at home by default.  
To deliver to a different location, use the "deliver" option:  
  `page.pizza({deliver: 'work'})`.
```

--------------------------------

### Identify sandbox access errors

Source: https://pptr.dev/troubleshooting

Example of the error message indicating that the Chrome sandbox cannot access the executable due to filesystem permissions.

```text
[24452:59820:0508/113713.058:ERROR:sandbox_win.cc(913)] Sandbox cannot access executable. Check filesystem permissions are valid. See https://bit.ly/31yqMJR.: Access is denied. (0x5)  
```

--------------------------------

### Build all packages

Source: https://pptr.dev/contributing

Command to build all packages in the repository.

```bash
npm run build  
```

--------------------------------

### Configure Puppeteer Cache Directory with Bun

Source: https://pptr.dev/troubleshooting

Set the cache directory to the current working directory for Bun installations and script execution.

```bash
PUPPETEER_CACHE_DIR=$(pwd) bun add puppeteer  

PUPPETEER_CACHE_DIR=$(pwd) node <script-path>  
```

--------------------------------

### Configure Puppeteer Cache Directory with pnpm

Source: https://pptr.dev/troubleshooting

Set the cache directory to the current working directory for pnpm installations and script execution.

```bash
PUPPETEER_CACHE_DIR=$(pwd) pnpm add puppeteer  

PUPPETEER_CACHE_DIR=$(pwd) node <script-path>  
```

--------------------------------

### Jest ENOMEM error output

Source: https://pptr.dev/troubleshooting

Example of the error output encountered when Jest incorrectly detects available system resources in a container.

```text
[00:00.0]  jest args: --e2e --spec --max-workers=36  

Error: spawn ENOMEM  

   at ChildProcess.spawn (internal/child_process.js:394:11)  
```

--------------------------------

### Configure Puppeteer Cache Directory with npm

Source: https://pptr.dev/troubleshooting

Set the cache directory to the current working directory for npm installations and script execution.

```bash
PUPPETEER_CACHE_DIR=$(pwd) npm install puppeteer  

PUPPETEER_CACHE_DIR=$(pwd) node <script-path>  
```

--------------------------------

### Configure Puppeteer Cache Directory with Yarn

Source: https://pptr.dev/troubleshooting

Set the cache directory to the current working directory for Yarn installations and script execution.

```bash
PUPPETEER_CACHE_DIR=$(pwd) yarn add puppeteer  

PUPPETEER_CACHE_DIR=$(pwd) node <script-path>  
```

--------------------------------

### Specifying CLI Versions

Source: https://pptr.dev/browsers-api

Demonstrates how to run specific versions of the CLI tool using npx.

```bash
# Always install and use the latest version from the registry.  
npx @puppeteer/browsers@latest --help  

# Always use a specific version.  
npx @puppeteer/browsers@2.4.1 --help  

# Always install the latest version and automatically confirm the installation.  
npx --yes @puppeteer/browsers@latest --help
```

--------------------------------

### launch(opts)

Source: https://pptr.dev/browsers-api

Launches a browser process according to LaunchOptions.

```APIDOC
## launch(opts)

### Description
Launches a browser process according to LaunchOptions.
```

--------------------------------

### Command-Specific Help

Source: https://pptr.dev/browsers-api

Provides detailed help documentation for individual CLI commands.

```bash
npx @puppeteer/browsers --help # help for all commands  
npx @puppeteer/browsers install --help # help for the install command  
npx @puppeteer/browsers launch --help # help for the launch command  
npx @puppeteer/browsers clear --help # help for the clear command  
npx @puppeteer/browsers list --help # help for the list command
```

--------------------------------

### Launch browsers with WebDriver BiDi

Source: https://pptr.dev/webdriver-bidi

Demonstrates how to launch Firefox and Chrome using the WebDriver BiDi protocol.

```javascript
import puppeteer from 'puppeteer';  

  

const firefoxBrowser = await puppeteer.launch({  

  browser: 'firefox', // WebDriver BiDi is used by default.  

});  

const page = await firefoxBrowser.newPage();  

...  

await firefoxBrowser.close();  

  

const chromeBrowser = await puppeteer.launch({  

  browser: 'chrome',  

  protocol: 'webDriverBiDi', // CDP would be used by default for Chrome.  

});  

const page = await chromeBrowser.newPage();  

...  

await chromeBrowser.close();
```

--------------------------------

### ElementHandle.touchStart() signature

Source: https://pptr.dev/api/puppeteer.elementhandle.touchstart

The method signature for touchStart within the ElementHandle class.

```typescript
class ElementHandle {  

  touchStart(this: ElementHandle<Element>): Promise<TouchHandle>;  

}  
```

--------------------------------

### Run all tests

Source: https://pptr.dev/contributing

Command to execute the full test suite.

```bash
npm test  
```

--------------------------------

### DefaultProvider.supports()

Source: https://pptr.dev/browsers-api/browsers.defaultprovider.supports

Checks if the provided download options are supported by the DefaultProvider.

```APIDOC
## DefaultProvider.supports()

### Description
Determines whether the DefaultProvider supports the specified download options.

### Signature
`supports(_options: DownloadOptions): boolean`

### Parameters
- **_options** (DownloadOptions) - Required - The download options to evaluate.

### Returns
- **boolean** - Returns true if the options are supported, otherwise false.
```

--------------------------------

### Accessing CLI Help

Source: https://pptr.dev/browsers-api

Displays the help menu for the @puppeteer/browsers package.

```bash
npx @puppeteer/browsers --help
```

--------------------------------

### Get cookies with Puppeteer

Source: https://pptr.dev/guides/cookies

Retrieves cookies available in the default BrowserContext after navigating to a page.

```javascript
import puppeteer from 'puppeteer';  

  

const browser = await puppeteer.launch();  

  

const page = await browser.newPage();  

  

await page.goto('https://example.com');  

  

// In this example, we set a cookie using script evaluation.  

// Cookies can be set by the page/server in various ways.  

await page.evaluate(() => {  

  document.cookie = 'myCookie = MyCookieValue';  

});  

  

console.log(await browser.cookies()); // print available cookies.
```

--------------------------------

### BrowserLauncher.launch() signature

Source: https://pptr.dev/api/puppeteer.browserlauncher.launch

Defines the method signature for launching a browser instance.

```typescript
class BrowserLauncher {  

  launch(options?: LaunchOptions): Promise<Browser>;  

}
```

--------------------------------

### Wait for element existence

Source: https://pptr.dev/api/puppeteer.realm.waitforfunction

Example usage of waitForFunction to wait until a specific selector exists in the document.

```javascript
const selector = '.foo';  

await realm.waitForFunction(  

  selector => !!document.querySelector(selector),  

  {},  

  selector,  

);  
```

--------------------------------

### Launch browser with DevTools

Source: https://pptr.dev/guides/debugging

Enable the browser's developer tools by setting devtools to true during launch.

```javascript
const browser = await puppeteer.launch({devtools: true});
```

--------------------------------

### Discover and Monitor Tools

Source: https://pptr.dev/guides/webmcp

Retrieve registered tools and listen for addition or removal events.

```javascript
// Get currently registered tools  

const tools = page.webmcp.tools();  

for (const tool of tools) {  

  console.log(`Tool found: ${tool.name} - ${tool.description}`);  

}  

  

// Listen for new tools  

page.webmcp.on('toolsadded', event => {  

  for (const tool of event.tools) {  

    console.log(`New tool added: ${tool.name}`);  

  }  

});  

  

// Listen for removed tools  

page.webmcp.on('toolsremoved', event => {  

  for (const tool of event.tools) {  

    console.log(`Tool removed: ${tool.name}`);  

  }  

});  
```

--------------------------------

### Launch browser in default headless mode

Source: https://pptr.dev/guides/headless-modes

The default launch behavior is equivalent to explicitly setting headless to true.

```javascript
const browser = await puppeteer.launch();  

// Equivalent to  

const browser = await puppeteer.launch({headless: true});  
```

--------------------------------

### Launch browser using chrome-headless-shell

Source: https://pptr.dev/guides/headless-modes

Use the shell binary for improved performance in automation tasks where the full Chrome feature set is not required.

```javascript
const browser = await puppeteer.launch({headless: 'shell'});  
```

--------------------------------

### Load extensions using LaunchOptions

Source: https://pptr.dev/guides/chrome-extensions

Use the enableExtensions option in puppeteer.launch to load an extension from a local path.

```javascript
import puppeteer from 'puppeteer';  

import path from 'path';  

  

const pathToExtension = path.join(process.cwd(), 'my-extension');  

const browser = await puppeteer.launch({  

  enableExtensions: [pathToExtension],  

});  
```

--------------------------------

### Access MV2 background page

Source: https://pptr.dev/guides/chrome-extensions

Get a handle to an extension's background page by waiting for the background_page target type.

```javascript
import puppeteer from 'puppeteer';  

import path from 'path';  

  

const pathToExtension = path.join(process.cwd(), 'my-extension');  

const browser = await puppeteer.launch({  

  enableExtensions: [pathToExtension],  

});  

const backgroundPageTarget = await browser.waitForTarget(  

  target => target.type() === 'background_page',  

);  

const backgroundPage = await backgroundPageTarget.page();  

  

// Test the background page as you would any other page.  

  

await browser.close();  
```

--------------------------------

### Run linting and formatting commands

Source: https://pptr.dev/contributing

Use these commands to check code style and automatically apply formatting fixes according to project configurations.

```bash
npm run lint
```

```bash
npm run format
```

--------------------------------

### Connect to a remote browser in the browser environment

Source: https://pptr.dev/guides/running-puppeteer-in-the-browser

Use the browser-specific entrypoint to connect to a remote browser instance via a WebSocket URL.

```javascript
import puppeteer from 'puppeteer-core/lib/puppeteer/puppeteer-core-browser.js';  

  

const browser = await puppeteer.connect({  

  browserWSEndpoint: wsUrl,  

});  

  

alert('Browser has ' + (await browser.pages()).length + ' pages');  

  

browser.disconnect();
```

--------------------------------

### Build a single package

Source: https://pptr.dev/contributing

Command to build a specific package using workspaces, which automatically handles dependencies.

```bash
npm run build --workspace <package> # e.g. puppeteer  
```

--------------------------------

### Touchscreen.tap(x, y)

Source: https://pptr.dev/api/puppeteer.touchscreen.tap

Dispatches a touchstart and touchend event at the specified coordinates.

```APIDOC
## Touchscreen.tap(x, y)

### Description
Dispatches a `touchstart` and `touchend` event at the specified horizontal and vertical coordinates.

### Signature
`tap(x: number, y: number): Promise<void>`

### Parameters
- **x** (number) - Required - Horizontal position of the tap.
- **y** (number) - Required - Vertical position of the tap.

### Returns
- **Promise<void>** - A promise that resolves when the tap events have been dispatched.
```

--------------------------------

### Configure dual-screen headless mode

Source: https://pptr.dev/guides/screen-configuration

Uses the --screen-info command line argument to define multiple screens in headless Chrome. This switch is only available in headless mode.

```javascript
import puppeteer from 'puppeteer-core';  

  

const browser = await puppeteer.launch({  

  args: ['--screen-info={800x600 label=1st}{600x800 label=2nd}'],  

});  

  

const screens = await browser.screens();  

const screenInfos = screens.map(  

  s =>  

    `Screen [${s.id}]` +  

    ` ${s.left},${s.top} ${s.width}x${s.height}` +  

    ` label='${s.label}'` +  

    ` isPrimary=${s.isPrimary}` +  

    ` isExtended=${s.isExtended}` +  

    ` isInternal=${s.isInternal}` +  

    ` colorDepth=${s.colorDepth}` +  

    ` devicePixelRatio=${s.devicePixelRatio}` +  

    ` avail=${s.availLeft},${s.availTop} ${s.availWidth}x${s.availHeight}` +  

    ` orientation.type=${s.orientation.type}` +  

    ` orientation.angle=${s.orientation.angle}`,  

);  

  

console.log(`Number of screens: ${screens.length}\n` + screenInfos.join('\n'));  

  

await browser.close();
```

--------------------------------

### Launch browser in headful mode

Source: https://pptr.dev/guides/headless-modes

Set headless to false to launch a visible browser instance.

```javascript
const browser = await puppeteer.launch({headless: false});  
```

--------------------------------

### Enable GPU in Headless Shell

Source: https://pptr.dev/troubleshooting

Use the --enable-gpu argument when launching the headless shell to enable GPU acceleration.

```javascript
const browser = await puppeteer.launch({  

  headless: 'shell',  

  args: ['--enable-gpu'],  

});  
```

--------------------------------

### Manage screens dynamically

Source: https://pptr.dev/guides/screen-configuration

Demonstrates adding and removing screens at runtime using Browser.addScreen and Browser.removeScreen. These methods are restricted to headless mode.

```javascript
import puppeteer from 'puppeteer-core';  

  

const browser = await puppeteer.launch({  

  args: ['--screen-info={800x600 label=1st}'],  

});  

  

function getScreenInfo(s) {  

  return (  

    `Screen [${s.id}]` +  

    ` ${s.left},${s.top} ${s.width}x${s.height}` +  

    ` label='${s.label}'` +  

    ` isPrimary=${s.isPrimary}` +  

    ` isExtended=${s.isExtended}`  

  );  

}  

  

async function logScreenConfig(text) {  

  if (text !== undefined) {  

    console.log(text);  

  }  

  const screens = await browser.screens();  

  const screenInfos = screens.map(s => getScreenInfo(s));  

  

  console.log(  

    `Number of screens: ${screens.length}\n` + screenInfos.join('\n'),  

  );  

}  

  

await logScreenConfig('---- Initial:');  

  

// Add a screen.  

const addedScreenInfo = await browser.addScreen({  

  left: 800,  

  top: 0,  

  width: 800,  

  height: 600,  

  label: '2nd',  

});  

  

console.log('Added screen: ' + getScreenInfo(addedScreenInfo));  

await logScreenConfig('---- With the screen added:');  

  

// Remove the added screen.  

await browser.removeScreen(addedScreenInfo.id);  

await logScreenConfig('---- With added screen removed:');  

  

await browser.close();
```

--------------------------------

### WebMCPTool.execute()

Source: https://pptr.dev/api/puppeteer.webmcptool.execute

Executes a tool with provided input parameters, validating against the tool's inputSchema.

```APIDOC
## WebMCPTool.execute()

### Description
Executes a tool with input parameters, matching the tool's inputSchema.

### Signature
`execute(input?: object): Promise<WebMCPToolCallResult>`

### Parameters
- **input** (object) - Optional - The input parameters for the tool execution.

### Returns
- **Promise<WebMCPToolCallResult>** - A promise that resolves with the result of the tool execution.
```

--------------------------------

### Generate Test File

Source: https://pptr.dev/guides/ng-schematics

Use this command to create a single E2E test file with a specified name.

```bash
ng generate @puppeteer/ng-schematics:e2e "<TestName>"
```

--------------------------------

### Implement a custom browser provider

Source: https://pptr.dev/browsers-api

Create a class implementing BrowserProvider to define custom download URLs and executable paths for alternative browser sources.

```typescript
import {
  BrowserProvider,
  DownloadOptions,
  Browser,
  BrowserPlatform,
} from '@puppeteer/browsers';

class SimpleMirrorProvider implements BrowserProvider {
  constructor(private mirrorUrl: string) {}

  supports(options: DownloadOptions): boolean {
    return options.browser === Browser.CHROME;
  }

  getDownloadUrl(options: DownloadOptions): URL | null {
    const {buildId, platform} = options;
    const filenameMap = {
      [BrowserPlatform.LINUX]: 'chrome-linux64.zip',
      [BrowserPlatform.MAC]: 'chrome-mac-x64.zip',
      [BrowserPlatform.MAC_ARM]: 'chrome-mac-arm64.zip',
      [BrowserPlatform.WIN32]: 'chrome-win32.zip',
      [BrowserPlatform.WIN64]: 'chrome-win64.zip',
    };
    const filename = filenameMap[platform];
    if (!filename) return null;
    return new URL(`${this.mirrorUrl}/chrome/${buildId}/${filename}`);
  }

  getExecutablePath(options: DownloadOptions): string {
    const {platform} = options;
    if (
      platform === BrowserPlatform.MAC ||
      platform === BrowserPlatform.MAC_ARM
    ) {
      return 'chrome-mac/Chromium.app/Contents/MacOS/Chromium';
    } else if (platform === BrowserPlatform.LINUX) {
      return 'chrome-linux64/chrome';
    } else if (platform.includes('win')) {
      return 'chrome-win64/chrome.exe';
    }
    throw new Error(`Unsupported platform: ${platform}`);
  }
}
```

--------------------------------

### WebMCPTool.execute(input)

Source: https://pptr.dev/guides/webmcp

Executes a specific tool and returns the result.

```APIDOC
## WebMCPTool.execute(input)

### Description
Invokes the tool with the provided input parameters.

### Parameters
- **input** (Object) - The input arguments required by the tool's schema.

### Returns
- **Promise<Object>** - Resolves with an object containing `status` ('Completed' or error), `output` (result data), or `errorText`.
```

--------------------------------

### DeviceRequestPrompt.waitForDevice(filter, options)

Source: https://pptr.dev/api/puppeteer.devicerequestprompt.waitfordevice

Resolves to the first device in the prompt matching a filter.

```APIDOC
## DeviceRequestPrompt.waitForDevice()

### Description
Resolves to the first device in the prompt matching a filter.

### Signature
`waitForDevice(filter: (device: DeviceRequestPromptDevice) => boolean, options?: WaitTimeoutOptions): Promise<DeviceRequestPromptDevice>`

### Parameters
- **filter** ((device: DeviceRequestPromptDevice) => boolean) - Required - A function to filter devices.
- **options** (WaitTimeoutOptions) - Optional - Configuration options for the wait operation.

### Returns
- **Promise<DeviceRequestPromptDevice>** - A promise that resolves to the matching device.
```

--------------------------------

### Automate browser tasks

Source: https://pptr.dev/

A basic script demonstrating how to launch a browser, navigate to a URL, interact with elements, and extract text content.

```javascript
import puppeteer from 'puppeteer';  

// Or import puppeteer from 'puppeteer-core';  

  

// 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/');  

  

// Set the screen size.  

await page.setViewport({width: 1080, height: 1024});  

  

// Open the search menu using the keyboard.  

await page.keyboard.press('/');  

  

// Type into search box using accessible input name.  

await page.locator('::-p-aria(Search)').fill('automate beyond recorder');  

  

// Wait and click on first result.  

await page.locator('.devsite-result-item-link').click();  

  

// Locate the full title with a unique string.  

const textSelector = await page  

  .locator('::-p-text(Customize and automate)')  

  .waitHandle();  

const fullTitle = await textSelector?.evaluate(el => el.textContent);  

  

// Print the full title.  

console.log('The title of this blog post is "%s".', fullTitle);  

  

await browser.close();  
```

--------------------------------

### Configure Linux SUID Sandbox

Source: https://pptr.dev/troubleshooting

Commands to set up the SUID sandbox executable for Chrome on Linux environments.

```bash
# cd to Puppeteer cache directory (adjust the path if using a different cache directory).  

cd ~/.cache/puppeteer/chrome/linux-<version>/chrome-linux64/  

sudo chown root:root chrome_sandbox  

sudo chmod 4755 chrome_sandbox  

# copy sandbox executable to a shared location  

sudo cp -p chrome_sandbox /usr/local/sbin/chrome-devel-sandbox  

# export CHROME_DEVEL_SANDBOX env variable  

export CHROME_DEVEL_SANDBOX=/usr/local/sbin/chrome-devel-sandbox  
```

--------------------------------

### Interact with DOM elements using ElementHandle

Source: https://pptr.dev/api

Demonstrates launching a browser, navigating to a page, and clicking an element retrieved via a selector.

```javascript
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
const hrefElement = await page.$('a');
await hrefElement.click();
// ...
```

--------------------------------

### Execute Unit Tests

Source: https://pptr.dev/guides/ng-schematics

Runs the test suite for schematics using the preferred package manager.

```bash
npm run test
```

```bash
yarn run test
```

```bash
pnpm run test
```

```bash
bun run test
```

--------------------------------

### Zooming into an element with Mouse.wheel()

Source: https://pptr.dev/api/puppeteer.mouse.wheel

Demonstrates how to move the mouse to the center of an element and trigger a wheel event to zoom.

```javascript
await page.goto(  

  'https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366',  

);  

  

const elem = await page.$('div');  

const boundingBox = await elem.boundingBox();  

await page.mouse.move(  

  boundingBox.x + boundingBox.width / 2,  

  boundingBox.y + boundingBox.height / 2,  

);  

  

await page.mouse.wheel({deltaY: -100});  
```

--------------------------------

### Manage window position and state with Puppeteer

Source: https://pptr.dev/guides/window-management

Demonstrates opening a window, moving it to a secondary screen, maximizing, and restoring its state.

```javascript
import puppeteer from 'puppeteer-core';  

  

const browser = await puppeteer.launch({  

  args: ['--screen-info={800x600}'],  

});  

  

async function logWindowBounds() {  

  const bounds = await browser.getWindowBounds(windowId);  

  console.log(  

    `${bounds.left},${bounds.top}` +  

      ` ${bounds.width}x${bounds.height}` +  

      ` ${bounds.windowState}`,  

  );  

}  

  

// Create new page.  

const page = await browser.newPage({type: 'window'});  

const windowId = await page.windowId();  

await logWindowBounds();  

  

// Add a screen to the right of the primary screen.  

const screenInfo = await browser.addScreen({  

  left: 800,  

  top: 0,  

  width: 1600,  

  height: 1200,  

});  

  

// Move the window to the newly created secondary screen.  

await browser.setWindowBounds(windowId, {  

  left: screenInfo.left + 50,  

  top: screenInfo.top + 50,  

  width: screenInfo.width - 100,  

  height: screenInfo.height - 100,  

});  

await logWindowBounds();  

  

// Maximize the window.  

await browser.setWindowBounds(windowId, {windowState: 'maximized'});  

await logWindowBounds();  

  

// Restore the window.  

await browser.setWindowBounds(windowId, {windowState: 'normal'});  

await logWindowBounds();  

  

await browser.close();
```

--------------------------------

### Enable browser process logging

Source: https://pptr.dev/guides/debugging

Set the dumpio attribute to true to forward browser logs to the Node.js process stdio.

```javascript
const browser = await puppeteer.launch({  

  dumpio: true,  

});  
```

--------------------------------

### Generate a PDF from a webpage

Source: https://pptr.dev/guides/pdf-generation

Use this snippet to launch a browser, navigate to a URL, and save the rendered page as a PDF file.

```javascript
const browser = await puppeteer.launch();  

const page = await browser.newPage();  

await page.goto('https://news.ycombinator.com', {  

  waitUntil: 'networkidle2',  

});  

// Saves the PDF to hn.pdf.  

await page.pdf({  

  path: 'hn.pdf',  

});  

  

await browser.close();
```

--------------------------------

### List and uninstall extensions

Source: https://pptr.dev/guides/chrome-extensions

Retrieve extension details and remove them using browser.extensions() and browser.uninstallExtension().

```javascript
const extensions = await browser.extensions();  

const extension = extensions.get(extensionId);  

  

console.log(extension?.name);  

console.log(extension?.version);  

  

await browser.uninstallExtension(extensionId);  
```

--------------------------------

### Build and Run Docker Container

Source: https://pptr.dev/troubleshooting

Commands to build the image and execute a Puppeteer script within the container.

```bash
docker build -t puppeteer-chrome-linux .
```

```bash
 docker run -i --init --rm --cap-add=SYS_ADMIN \

   --name puppeteer-chrome puppeteer-chrome-linux \

   node -e "`cat yourscript.js`"
```

--------------------------------

### Debian/Ubuntu system dependencies

Source: https://pptr.dev/troubleshooting

List of required packages for Debian-based distributions.

```text
ca-certificates  

fonts-liberation  

libasound2  

libatk-bridge2.0-0  

libatk1.0-0  

libc6  

libcairo2  

libcups2  

libdbus-1-3  

libexpat1  

libfontconfig1  

libgbm1  

libgcc1  

libglib2.0-0  

libgtk-3-0  

libnspr4  

libnss3  

libpango-1.0-0  

libpangocairo-1.0-0  

libstdc++6  

libx11-6  

libx11-xcb1  

libxcb1  

libxcomposite1  

libxcursor1  

libxdamage1  

libxext6  

libxfixes3  

libxi6  

libxrandr2  

libxrender1  

libxss1  

libxtst6  

lsb-release  

wget  

xdg-utils
```

--------------------------------

### Wait for a response using URL or predicate

Source: https://pptr.dev/api/puppeteer.page.waitforresponse

Demonstrates waiting for a response by URL string, a simple predicate, or an asynchronous predicate.

```javascript
const firstResponse = await page.waitForResponse(  
  'https://example.com/resource',  
);

const finalResponse = await page.waitForResponse(  
  response =>  
    response.url() === 'https://example.com' && response.status() === 200,  
);

const finalResponse = await page.waitForResponse(async response => {  
  return (await response.text()).includes('<html>');  
});

return finalResponse.ok();
```

--------------------------------

### CLI constructor

Source: https://pptr.dev/browsers-api/browsers.cli._constructor_

Constructs a new instance of the CLI class.

```APIDOC
## CLI constructor

### Description
Constructs a new instance of the `CLI` class.

### Signature
`new CLI(opts?: string | { cachePath?: string; scriptName?: string; version?: string; prefixCommand?: { cmd: string; description: string; }; allowCachePathOverride?: boolean; pinnedBrowsers?: Partial<Record<Browser, { buildId: string; skipDownload: boolean; }>>; }, rl?: readline.Interface)`

### Parameters
- **opts** (string | object) - Optional - Configuration options for the CLI instance.
- **rl** (readline.Interface) - Optional - The readline interface to use.
```
Tokens:
Raw