or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-data.mdcache.mdcli.mdindex.mdinstallation.mdlaunching.md
tile.json

tessl/npm-puppeteer--browsers

Download, manage, and launch browsers (Chrome, Chromium, Firefox) and drivers (ChromeDriver) for testing and automation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@puppeteer/browsers@2.10.x

To install, run

npx @tessl/cli install tessl/npm-puppeteer--browsers@2.10.0

index.mddocs/

@puppeteer/browsers

@puppeteer/browsers is a comprehensive CLI tool and programmatic API for downloading, managing, and launching web browsers (Chrome, Chromium, Firefox) and browser drivers (ChromeDriver) for testing and automation purposes. It provides cross-platform support with built-in progress tracking, automatic extraction, and intelligent caching of browser installations.

Package Information

  • Package Name: @puppeteer/browsers
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @puppeteer/browsers
  • CLI Usage: npx @puppeteer/browsers --help

Core Imports

import { 
  install, 
  launch, 
  computeExecutablePath,
  Browser,
  BrowserPlatform,
  CLI
} from "@puppeteer/browsers";

For CommonJS:

const { 
  install, 
  launch, 
  computeExecutablePath,
  Browser,
  BrowserPlatform 
} = require("@puppeteer/browsers");

Basic Usage

import { 
  install, 
  launch, 
  computeExecutablePath,
  Browser, 
  BrowserPlatform 
} from "@puppeteer/browsers";

// Install a browser
const installedBrowser = await install({
  cacheDir: "./browsers-cache",
  browser: Browser.CHROME,
  buildId: "118.0.5993.70"
});

// Compute executable path
const executablePath = computeExecutablePath({
  cacheDir: "./browsers-cache",
  browser: Browser.CHROME,
  buildId: "118.0.5993.70"
});

// Launch browser
const browserProcess = launch({
  executablePath,
  args: ["--no-sandbox"]
});

// Use the browser process
console.log("Browser launched with PID:", browserProcess.nodeProcess.pid);

// Clean up
await browserProcess.close();

Architecture

@puppeteer/browsers is built around several key components:

  • Installation System: Downloads and manages browser binaries with caching and version management
  • Launch System: Advanced browser process management with signal handling and lifecycle control
  • Cache Management: Intelligent storage and retrieval of browser installations with metadata support
  • Platform Detection: Automatic detection of OS and architecture for cross-platform compatibility
  • CLI Interface: Complete command-line tool for installation, launching, and management operations
  • Browser Data: Comprehensive browser-specific configuration and version resolution

Capabilities

Browser Installation

Comprehensive browser download and installation management with support for multiple browsers, platforms, and version resolution. Handles progress tracking, archive extraction, and dependency installation.

function install(options: InstallOptions): Promise<InstalledBrowser>;
function install(options: InstallOptions & {unpack: false}): Promise<string>;

interface InstallOptions {
  cacheDir: string;
  platform?: BrowserPlatform;
  browser: Browser;
  buildId: string;
  buildIdAlias?: string;
  downloadProgressCallback?: 'default' | ((downloadedBytes: number, totalBytes: number) => void);
  baseUrl?: string;
  unpack?: boolean;
  installDeps?: boolean;
}

Browser Installation

Browser Launching

Advanced browser process management with customizable launch options, signal handling, and process lifecycle control. Supports both cached and system-installed browsers.

function launch(opts: LaunchOptions): Process;
function computeExecutablePath(options: ComputeExecutablePathOptions): string;
function computeSystemExecutablePath(options: SystemOptions): string;

interface LaunchOptions {
  executablePath: string;
  pipe?: boolean;
  dumpio?: boolean;
  args?: string[];
  env?: Record<string, string | undefined>;
  handleSIGINT?: boolean;
  handleSIGTERM?: boolean;
  handleSIGHUP?: boolean;
  detached?: boolean;
  onExit?: () => Promise<void>;
}

Browser Launching

Cache Management

Browser cache directory management with metadata handling, alias resolution, and installation tracking. Provides comprehensive control over browser storage and cleanup.

class Cache {
  constructor(rootDir: string);
  get rootDir(): string;
  getInstalledBrowsers(): InstalledBrowser[];
  uninstall(browser: Browser, platform: BrowserPlatform, buildId: string): void;
  clear(): void;
  resolveAlias(browser: Browser, alias: string): string | undefined;
  computeExecutablePath(options: ComputeExecutablePathOptions): string;
}

class InstalledBrowser {
  browser: Browser;
  buildId: string;
  platform: BrowserPlatform;
  readonly executablePath: string;
  get path(): string;
}

Cache Management

Command Line Interface

Full-featured CLI for browser management operations including installation, launching, listing, and cleanup. Supports all programmatic features through command-line interface.

class CLI {
  constructor(opts?: string | CLIOptions, rl?: readline.Interface);
  run(argv: string[]): Promise<void>;
}

Available Commands:

  • install [browser] - Download and install browsers
  • launch <browser> - Launch installed browsers
  • clear - Remove all installed browsers
  • list - List all installed browsers

Command Line Interface

Browser Data and Platform Support

Browser-specific configuration, version resolution, and platform detection utilities. Supports Chrome, Chromium, Firefox, Chrome Headless Shell, and ChromeDriver across multiple platforms.

function detectBrowserPlatform(): BrowserPlatform | undefined;
function resolveBuildId(browser: Browser, platform: BrowserPlatform, tag: string | BrowserTag): Promise<string>;
function getVersionComparator(browser: Browser): (a: string, b: string) => number;
function createProfile(browser: Browser, opts: ProfileOptions): Promise<void>;

enum Browser {
  CHROME = 'chrome',
  CHROMEHEADLESSSHELL = 'chrome-headless-shell',
  CHROMIUM = 'chromium',
  FIREFOX = 'firefox',
  CHROMEDRIVER = 'chromedriver'
}

enum BrowserPlatform {
  LINUX = 'linux',
  LINUX_ARM = 'linux_arm',
  MAC = 'mac',
  MAC_ARM = 'mac_arm',
  WIN32 = 'win32',
  WIN64 = 'win64'
}

Browser Data

Core Types

interface ComputeExecutablePathOptions {
  cacheDir: string | null;
  platform?: BrowserPlatform;
  browser: Browser;
  buildId: string;
}

interface SystemOptions {
  platform?: BrowserPlatform;
  browser: Browser;
  channel: ChromeReleaseChannel;
}

interface UninstallOptions {
  platform?: BrowserPlatform;
  cacheDir: string;
  browser: Browser;
  buildId: string;
}

interface GetInstalledBrowsersOptions {
  cacheDir: string;
}

interface ProfileOptions {
  preferences: Record<string, unknown>;
  path: string;
}

enum ChromeReleaseChannel {
  STABLE = 'stable',
  DEV = 'dev',
  CANARY = 'canary',
  BETA = 'beta'
}

enum BrowserTag {
  CANARY = 'canary',
  NIGHTLY = 'nightly',
  BETA = 'beta',
  DEV = 'dev',
  DEVEDITION = 'devedition',
  STABLE = 'stable',
  ESR = 'esr',
  LATEST = 'latest'
}

class Process {
  get nodeProcess(): childProcess.ChildProcess;
  close(): Promise<void>;
  hasClosed(): Promise<void>;
  kill(): void;
  waitForLineOutput(regex: RegExp, timeout?: number): Promise<string>;
}

class TimeoutError extends Error {
  constructor(message?: string);
}

const CDP_WEBSOCKET_ENDPOINT_REGEX: RegExp;
const WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX: RegExp;

Utility Functions

function canDownload(options: InstallOptions): Promise<boolean>;
function uninstall(options: UninstallOptions): Promise<void>;
function getInstalledBrowsers(options: GetInstalledBrowsersOptions): Promise<InstalledBrowser[]>;
function getDownloadUrl(browser: Browser, platform: BrowserPlatform, buildId: string, baseUrl?: string): URL;
function makeProgressCallback(browser: Browser, buildId: string): (downloadedBytes: number, totalBytes: number) => void;