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

browser-data.mddocs/

Browser Data and Platform Support

Browser-specific configuration, version resolution, and platform detection utilities. Provides comprehensive support for Chrome, Chromium, Firefox, Chrome Headless Shell, and ChromeDriver across multiple platforms with automatic version resolution and platform detection.

Capabilities

Platform Detection

Automatic detection of the current operating system and architecture combination for browser compatibility.

/**
 * Detects current browser platform based on OS and architecture
 * @returns BrowserPlatform enum value or undefined for unsupported platforms
 */
function detectBrowserPlatform(): BrowserPlatform | undefined;

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

Usage Examples:

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

// Detect current platform
const platform = detectBrowserPlatform();

if (platform) {
  console.log("Detected platform:", platform);
  
  switch (platform) {
    case BrowserPlatform.LINUX:
      console.log("Running on Linux x64");
      break;
    case BrowserPlatform.LINUX_ARM:
      console.log("Running on Linux ARM64");
      break;
    case BrowserPlatform.MAC:
      console.log("Running on macOS Intel");
      break;
    case BrowserPlatform.MAC_ARM:
      console.log("Running on macOS Apple Silicon");
      break;
    case BrowserPlatform.WIN32:
      console.log("Running on Windows 32-bit");
      break;
    case BrowserPlatform.WIN64:
      console.log("Running on Windows 64-bit");
      break;
  }
} else {
  console.error("Unsupported platform");
}

Browser Support

Comprehensive support for multiple browser types with specialized handling for each browser's unique characteristics.

/**
 * Supported browser types
 */
enum Browser {
  CHROME = 'chrome',
  CHROMEHEADLESSSHELL = 'chrome-headless-shell',
  CHROMIUM = 'chromium',
  FIREFOX = 'firefox',
  CHROMEDRIVER = 'chromedriver'
}

Browser Characteristics:

  • Chrome: Chrome for Testing binaries with stable/dev/canary/beta channels
  • Chromium: Snapshot builds from Chromium tip-of-tree
  • Firefox: Mozilla Firefox with stable/nightly/beta/devedition/esr channels
  • Chrome Headless Shell: Headless Chrome optimized for automation
  • ChromeDriver: WebDriver implementation for Chrome automation

Version Resolution

Resolve browser build IDs from release channels, tags, or version specifications.

/**
 * Resolves build ID for browser based on platform and tag/channel
 * @param browser - Target browser type
 * @param platform - Target platform
 * @param tag - Release tag, channel, or specific version
 * @returns Promise resolving to build ID string
 */
function resolveBuildId(
  browser: Browser, 
  platform: BrowserPlatform, 
  tag: string | BrowserTag
): Promise<string>;

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

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

Usage Examples:

import { 
  resolveBuildId, 
  Browser, 
  BrowserPlatform, 
  BrowserTag,
  ChromeReleaseChannel 
} from "@puppeteer/browsers";

// Resolve Chrome stable version
const chromeStable = await resolveBuildId(
  Browser.CHROME,
  BrowserPlatform.LINUX,
  BrowserTag.STABLE
);
console.log("Chrome stable build ID:", chromeStable);

// Resolve specific Chrome channel
const chromeBeta = await resolveBuildId(
  Browser.CHROME,
  BrowserPlatform.MAC,
  ChromeReleaseChannel.BETA
);
console.log("Chrome beta build ID:", chromeBeta);

// Resolve Firefox nightly
const firefoxNightly = await resolveBuildId(
  Browser.FIREFOX,
  BrowserPlatform.WIN64,
  BrowserTag.NIGHTLY
);
console.log("Firefox nightly build ID:", firefoxNightly);

// Resolve Chromium snapshot
const chromiumBuild = await resolveBuildId(
  Browser.CHROMIUM,
  BrowserPlatform.LINUX,
  "latest"
);
console.log("Chromium build ID:", chromiumBuild);

Version Comparison

Get version comparator functions for sorting browser versions according to each browser's versioning scheme.

/**
 * Returns version comparator for browser that can sort versions
 * @param browser - Browser type
 * @returns Comparison function (-1, 0, 1) for sorting
 */
function getVersionComparator(browser: Browser): (a: string, b: string) => number;

Usage Examples:

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

// Sort Chrome versions
const chromeVersions = ["118.0.5993.70", "119.0.6045.105", "117.0.5938.149"];
const chromeComparator = getVersionComparator(Browser.CHROME);

chromeVersions.sort(chromeComparator);
console.log("Sorted Chrome versions:", chromeVersions);

// Sort Firefox versions
const firefoxVersions = ["119.0", "118.0.1", "119.0.1"];
const firefoxComparator = getVersionComparator(Browser.FIREFOX);

firefoxVersions.sort(firefoxComparator);
console.log("Sorted Firefox versions:", firefoxVersions);

// Find latest version
const versions = ["118.0.5993.70", "119.0.6045.105", "117.0.5938.149"];
const comparator = getVersionComparator(Browser.CHROME);
const latest = versions.sort(comparator).pop();
console.log("Latest version:", latest);

Profile Management

Create and configure browser profiles for customized browser behavior.

/**
 * Creates browser profile with specified options
 * @param browser - Target browser type
 * @param opts - Profile configuration options
 * @returns Promise resolving when profile is created
 */
function createProfile(browser: Browser, opts: ProfileOptions): Promise<void>;

interface ProfileOptions {
  /** Browser preferences and settings */
  preferences: Record<string, unknown>;
  /** Path to profile directory */
  path: string;
}

Usage Examples:

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

// Create Firefox profile with custom preferences
await createProfile(Browser.FIREFOX, {
  path: "./custom-firefox-profile",
  preferences: {
    "browser.startup.homepage": "https://example.com",
    "dom.webnotifications.enabled": false,
    "media.autoplay.default": 5,
    "network.cookie.cookieBehavior": 1
  }
});

// Create Chrome profile (uses Chrome preferences format)
await createProfile(Browser.CHROME, {
  path: "./custom-chrome-profile", 
  preferences: {
    "profile.default_content_setting_values.notifications": 2,
    "profile.default_content_settings.popups": 0,
    "profile.password_manager_enabled": false
  }
});

console.log("Browser profiles created successfully");

Platform-Specific Considerations

Linux Platform

Chrome/Chromium Dependencies:

  • libnss3, libatk-bridge2.0-0, libxcomposite1, libxdamage1
  • libxrandr2, libgbm1, libxss1, libasound2

Firefox Dependencies:

  • libgtk-3-0, libdbus-glib-1-2, libxt6

Archive Formats:

  • Chrome/Chromium: .zip files
  • Firefox: .tar.bz2 files (requires bzip2 utility)

macOS Platform

Archive Formats:

  • Chrome/Chromium: .zip files
  • Firefox: .dmg files (requires hdiutil utility)

Architecture Support:

  • Intel Macs: BrowserPlatform.MAC
  • Apple Silicon: BrowserPlatform.MAC_ARM

Windows Platform

Archive Formats:

  • Chrome/Chromium: .zip files
  • Firefox: .zip files

Architecture Support:

  • 32-bit: BrowserPlatform.WIN32
  • 64-bit: BrowserPlatform.WIN64

Browser-Specific Features

Chrome for Testing

Chrome for Testing provides stable, versioned Chrome binaries specifically designed for testing and automation.

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

// Get Chrome for Testing versions
const stableChrome = await resolveBuildId(
  Browser.CHROME,
  BrowserPlatform.LINUX,
  ChromeReleaseChannel.STABLE
);

const canaryChrome = await resolveBuildId(
  Browser.CHROME,
  BrowserPlatform.LINUX,
  ChromeReleaseChannel.CANARY
);

console.log("Stable Chrome:", stableChrome);
console.log("Canary Chrome:", canaryChrome);

Firefox Release Channels

Firefox supports multiple release channels with different update frequencies and feature sets.

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

// Firefox release channels
const channels = ['stable', 'beta', 'nightly', 'devedition', 'esr'];

for (const channel of channels) {
  try {
    const buildId = await resolveBuildId(
      Browser.FIREFOX,
      BrowserPlatform.LINUX,
      channel
    );
    console.log(`Firefox ${channel}:`, buildId);
  } catch (error) {
    console.error(`${channel} not available:`, error.message);
  }
}

Chromium Snapshots

Chromium provides snapshot builds from the tip-of-tree development branch.

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

// Get latest Chromium snapshot
const chromiumSnapshot = await resolveBuildId(
  Browser.CHROMIUM,
  BrowserPlatform.LINUX,
  "latest"
);

console.log("Latest Chromium snapshot:", chromiumSnapshot);

ChromeDriver Compatibility

ChromeDriver versions correspond to Chrome versions for compatibility.

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

// Get matching ChromeDriver for Chrome version
const chromeVersion = "118.0.5993.70";
const chromedriverVersion = await resolveBuildId(
  Browser.CHROMEDRIVER,
  BrowserPlatform.LINUX,
  chromeVersion
);

console.log("Chrome version:", chromeVersion);
console.log("ChromeDriver version:", chromedriverVersion);

Advanced Usage Patterns

Multi-Platform Support

Handle different platforms gracefully in cross-platform applications.

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

async function getBrowserForCurrentPlatform() {
  const platform = detectBrowserPlatform();
  
  if (!platform) {
    throw new Error("Unsupported platform");
  }
  
  // Get appropriate browser version for platform
  const buildId = await resolveBuildId(
    Browser.CHROME,
    platform,
    "stable"
  );
  
  return { browser: Browser.CHROME, platform, buildId };
}

const browserSpec = await getBrowserForCurrentPlatform();
console.log("Browser specification:", browserSpec);

Version Range Resolution

Find compatible browser versions within specified ranges.

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

function findVersionsInRange(
  versions: string[],
  browser: Browser,
  minVersion: string,
  maxVersion: string
): string[] {
  const comparator = getVersionComparator(browser);
  
  return versions.filter(version => {
    return comparator(version, minVersion) >= 0 && 
           comparator(version, maxVersion) <= 0;
  }).sort(comparator);
}

const chromeVersions = [
  "117.0.5938.149",
  "118.0.5993.70", 
  "119.0.6045.105",
  "120.0.6099.0"
];

const compatibleVersions = findVersionsInRange(
  chromeVersions,
  Browser.CHROME,
  "118.0.0.0",
  "119.999.999.999"
);

console.log("Compatible versions:", compatibleVersions);

Fallback Browser Selection

Implement fallback logic for browser availability.

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

async function getAvailableBrowser(platform: BrowserPlatform) {
  const browsers = [
    { browser: Browser.CHROME, channel: ChromeReleaseChannel.STABLE },
    { browser: Browser.CHROME, channel: ChromeReleaseChannel.BETA },
    { browser: Browser.CHROMIUM, channel: "latest" },
    { browser: Browser.FIREFOX, channel: "stable" }
  ];
  
  for (const spec of browsers) {
    try {
      const buildId = await resolveBuildId(
        spec.browser,
        platform,
        spec.channel
      );
      
      return { 
        browser: spec.browser, 
        buildId, 
        channel: spec.channel 
      };
    } catch (error) {
      console.log(`${spec.browser}@${spec.channel} not available`);
    }
  }
  
  throw new Error("No browsers available for platform");
}

const platform = detectBrowserPlatform();
if (platform) {
  const availableBrowser = await getAvailableBrowser(platform);
  console.log("Selected browser:", availableBrowser);
}

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