CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-puppeteer--browsers

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

launching.mddocs/

Browser Launching

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

Capabilities

Launch Function

Launches a browser process according to LaunchOptions, providing full control over browser startup configuration and process management.

/**
 * Launches a browser process according to LaunchOptions
 * @param opts - Launch configuration options
 * @returns Process instance for managing the browser process
 */
function launch(opts: LaunchOptions): Process;

interface LaunchOptions {
  /** Absolute path to the browser's executable */
  executablePath: string;
  /** Enable stdio pipes for automation (default: false) */
  pipe?: boolean;
  /** Forward browser stdout/stderr to Node process (default: false) */
  dumpio?: boolean;
  /** Additional arguments to pass to browser executable */
  args?: string[];
  /** Environment variables for browser process */
  env?: Record<string, string | undefined>;
  /** Handle SIGINT signals (default: true) */
  handleSIGINT?: boolean;
  /** Handle SIGTERM signals (default: true) */
  handleSIGTERM?: boolean;
  /** Handle SIGHUP signals (default: true) */
  handleSIGHUP?: boolean;
  /** Spawn in detached mode (default: true except Windows) */
  detached?: boolean;
  /** Callback for process exit events */
  onExit?: () => Promise<void>;
}

Usage Examples:

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

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

const browserProcess = launch({
  executablePath,
  args: ["--no-sandbox", "--disable-dev-shm-usage"]
});

console.log("Browser PID:", browserProcess.nodeProcess.pid);

// Advanced launch with custom configuration
const advancedProcess = launch({
  executablePath,
  args: ["--headless", "--disable-gpu", "--remote-debugging-port=9222"],
  env: {
    ...process.env,
    DISPLAY: ":99"
  },
  dumpio: true,
  onExit: async () => {
    console.log("Browser process exited");
  }
});

// Wait for DevTools endpoint
const wsEndpoint = await advancedProcess.waitForLineOutput(
  /DevTools listening on (ws:\/\/.*)/,
  10000
);
console.log("DevTools endpoint:", wsEndpoint);

Process Class

Represents a launched browser process with comprehensive lifecycle management capabilities.

/**
 * Browser process management class providing lifecycle control
 */
class Process {
  /** Access to underlying Node.js child process */
  get nodeProcess(): childProcess.ChildProcess;
  
  /** Gracefully close the browser process */
  close(): Promise<void>;
  
  /** Returns promise that resolves when process exits */
  hasClosed(): Promise<void>;
  
  /** Force kill the browser process */
  kill(): void;
  
  /** Wait for specific output line matching regex */
  waitForLineOutput(regex: RegExp, timeout?: number): Promise<string>;
}

Usage Examples:

import { launch } from "@puppeteer/browsers";

const process = launch({ executablePath: "/path/to/browser" });

// Monitor process lifecycle
process.hasClosed().then(() => {
  console.log("Browser process has exited");
});

// Wait for browser to start
try {
  const endpoint = await process.waitForLineOutput(
    /DevTools listening on (ws:\/\/.*)/,
    5000
  );
  console.log("Browser ready:", endpoint);
} catch (error) {
  console.error("Browser failed to start:", error);
}

// Graceful shutdown
await process.close();

Compute Executable Path

Computes the executable path for a cached browser installation.

/**
 * Computes executable path for cached browser
 * @param options - Path computation options
 * @returns Absolute path to browser executable
 */
function computeExecutablePath(options: ComputeExecutablePathOptions): string;

interface ComputeExecutablePathOptions {
  /** Root path to storage directory (null for relative paths) */
  cacheDir: string | null;
  /** Target platform (auto-detected if not provided) */
  platform?: BrowserPlatform;
  /** Browser type */
  browser: Browser;
  /** Build identifier */
  buildId: string;
}

Usage Examples:

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

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

// Compute relative path (for portable installations)
const relativePath = computeExecutablePath({
  cacheDir: null,
  browser: Browser.CHROME,
  buildId: "118.0.5993.70",
  platform: BrowserPlatform.LINUX
});

console.log("Cached browser path:", executablePath);
console.log("Relative path:", relativePath);

Compute System Executable Path

Returns path to system-wide Chrome installation by checking known installation locations.

/**
 * Returns path to system-wide Chrome installation
 * @param options - System browser options
 * @returns Absolute path to system browser executable
 * @throws Error if browser not found at expected path
 */
function computeSystemExecutablePath(options: SystemOptions): string;

interface SystemOptions {
  /** Target platform (auto-detected if not provided) */
  platform?: BrowserPlatform;
  /** Browser type (currently only Chrome supported) */
  browser: Browser;
  /** Chrome release channel to look for */
  channel: ChromeReleaseChannel;
}

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

Usage Examples:

import { 
  computeSystemExecutablePath, 
  launch,
  Browser, 
  ChromeReleaseChannel 
} from "@puppeteer/browsers";

// Use system Chrome installation
try {
  const systemChrome = computeSystemExecutablePath({
    browser: Browser.CHROME,
    channel: ChromeReleaseChannel.STABLE
  });
  
  const process = launch({
    executablePath: systemChrome,
    args: ["--no-first-run"]
  });
  
  console.log("Launched system Chrome");
} catch (error) {
  console.error("System Chrome not found:", error.message);
}

// Try different channels
const channels = [
  ChromeReleaseChannel.STABLE,
  ChromeReleaseChannel.BETA,
  ChromeReleaseChannel.DEV,
  ChromeReleaseChannel.CANARY
];

for (const channel of channels) {
  try {
    const path = computeSystemExecutablePath({
      browser: Browser.CHROME,
      channel
    });
    console.log(`Found ${channel} Chrome at:`, path);
    break;
  } catch {
    console.log(`${channel} Chrome not found`);
  }
}

WebSocket Endpoint Detection

Regular expressions for detecting browser WebSocket endpoints from process output.

/** Regular expression for Chrome DevTools WebSocket endpoint */
const CDP_WEBSOCKET_ENDPOINT_REGEX: RegExp;

/** Regular expression for WebDriver BiDi WebSocket endpoint */
const WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX: RegExp;

Usage Example:

import { 
  launch, 
  CDP_WEBSOCKET_ENDPOINT_REGEX,
  WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX 
} from "@puppeteer/browsers";

const process = launch({
  executablePath: "/path/to/chrome",
  args: ["--remote-debugging-port=0"]
});

// Wait for CDP endpoint
const cdpEndpoint = await process.waitForLineOutput(
  CDP_WEBSOCKET_ENDPOINT_REGEX,
  10000
);

// Wait for BiDi endpoint
const bidiEndpoint = await process.waitForLineOutput(
  WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX,
  10000
);

console.log("CDP:", cdpEndpoint);
console.log("BiDi:", bidiEndpoint);

Error Handling

TimeoutError

Specialized error class for timeout operations.

/**
 * Error thrown when operations timeout
 */
class TimeoutError extends Error {
  constructor(message?: string);
}

Usage Example:

import { launch, TimeoutError } from "@puppeteer/browsers";

const process = launch({ executablePath: "/path/to/browser" });

try {
  const endpoint = await process.waitForLineOutput(
    /DevTools listening on (ws:\/\/.*)/,
    5000
  );
  console.log("Browser ready:", endpoint);
} catch (error) {
  if (error instanceof TimeoutError) {
    console.error("Browser startup timed out");
  } else {
    console.error("Browser launch failed:", error);
  }
}

Process Management Features

Signal Handling

The Process class automatically handles system signals for graceful shutdown:

  • SIGINT: Kills browser process and exits with code 130
  • SIGTERM/SIGHUP: Attempts graceful browser closure
  • Process Exit: Automatically cleans up browser process

Cross-Platform Support

Process management adapts to platform differences:

  • Linux/macOS: Uses process groups for complete process tree cleanup
  • Windows: Uses taskkill command for reliable process termination
  • Detached Mode: Automatically disabled on Windows for compatibility

Stdio Configuration

Flexible stdio configuration for different use cases:

  • Default: Captures stderr for endpoint detection, ignores stdout
  • Dumpio: Forwards browser output to Node.js process
  • Pipe Mode: Creates additional pipes for automation protocols

Common Launch Patterns

Headless Automation

const process = launch({
  executablePath,
  args: [
    "--headless",
    "--disable-gpu",
    "--no-sandbox",
    "--disable-dev-shm-usage",
    "--remote-debugging-port=9222"
  ]
});

Visual Testing

const process = launch({
  executablePath,
  args: [
    "--disable-web-security",
    "--allow-running-insecure-content",
    "--window-size=1920,1080"
  ],
  env: { DISPLAY: ":99" }
});

Performance Testing

const process = launch({
  executablePath,
  args: [
    "--disable-extensions",
    "--disable-plugins",
    "--disable-images",
    "--disable-javascript"
  ]
});

Install with Tessl CLI

npx tessl i tessl/npm-puppeteer--browsers

docs

browser-data.md

cache.md

cli.md

index.md

installation.md

launching.md

tile.json