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

cache.mddocs/

Cache Management

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

Capabilities

Cache Class

Main cache management class providing directory structure management and browser installation tracking.

/**
 * Browser cache directory management class
 */
class Cache {
  /** Create cache instance with specified root directory */
  constructor(rootDir: string);
  
  /** Get the root cache directory path */
  get rootDir(): string;
  
  /** Get browser-specific cache directory */
  browserRoot(browser: Browser): string;
  
  /** Get metadata file path for browser */
  metadataFile(browser: Browser): string;
  
  /** Read browser metadata from cache */
  readMetadata(browser: Browser): Metadata;
  
  /** Write browser metadata to cache */
  writeMetadata(browser: Browser, metadata: Metadata): void;
  
  /** Resolve alias to build ID */
  resolveAlias(browser: Browser, alias: string): string | undefined;
  
  /** Get installation directory for specific browser/platform/build */
  installationDir(browser: Browser, platform: BrowserPlatform, buildId: string): string;
  
  /** Remove entire cache directory */
  clear(): void;
  
  /** Uninstall specific browser installation */
  uninstall(browser: Browser, platform: BrowserPlatform, buildId: string): void;
  
  /** List all installed browsers in cache */
  getInstalledBrowsers(): InstalledBrowser[];
  
  /** Compute executable path for browser installation */
  computeExecutablePath(options: ComputeExecutablePathOptions): string;
}

Usage Examples:

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

// Create cache instance
const cache = new Cache("./browsers-cache");

// Get browser-specific information
const chromeRoot = cache.browserRoot(Browser.CHROME);
const metadataFile = cache.metadataFile(Browser.CHROME);

console.log("Chrome cache root:", chromeRoot);
console.log("Metadata file:", metadataFile);

// List all installed browsers
const installed = cache.getInstalledBrowsers();
installed.forEach(browser => {
  console.log(`${browser.browser}@${browser.buildId} (${browser.platform})`);
});

// Clean up cache
cache.clear();
console.log("Cache cleared");

InstalledBrowser Class

Represents an installed browser instance with metadata and path information.

/**
 * Represents an installed browser instance
 */
class InstalledBrowser {
  /** Browser type */
  browser: Browser;
  
  /** Build identifier */
  buildId: string;
  
  /** Target platform */
  platform: BrowserPlatform;
  
  /** Path to browser executable (readonly) */
  readonly executablePath: string;
  
  /** Path to installation directory */
  get path(): string;
  
  /** Read browser metadata from cache */
  readMetadata(): Metadata;
  
  /** Write browser metadata to cache */
  writeMetadata(metadata: Metadata): void;
}

Usage Examples:

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

// Install browser and work with InstalledBrowser instance
const installedBrowser = await install({
  cacheDir: "./browsers-cache",
  browser: Browser.CHROME,
  buildId: "118.0.5993.70",
  buildIdAlias: "stable"
});

console.log("Browser:", installedBrowser.browser);
console.log("Build ID:", installedBrowser.buildId);
console.log("Platform:", installedBrowser.platform);
console.log("Installation path:", installedBrowser.path);
console.log("Executable path:", installedBrowser.executablePath);

// Work with metadata
const metadata = installedBrowser.readMetadata();
console.log("Current aliases:", metadata.aliases);

// Add new alias
metadata.aliases["latest"] = installedBrowser.buildId;
installedBrowser.writeMetadata(metadata);

Metadata Management

Browser metadata structure containing alias mappings and installation information.

/**
 * Browser metadata structure
 */
interface Metadata {
  /** Maps aliases to build IDs (e.g., 'stable' -> '118.0.5993.70') */
  aliases: Record<string, string>;
}

Usage Examples:

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

const cache = new Cache("./browsers-cache");

// Read existing metadata
const metadata = cache.readMetadata(Browser.CHROME);
console.log("Current aliases:", metadata.aliases);

// Add alias mapping
metadata.aliases["my-stable"] = "118.0.5993.70";
metadata.aliases["latest"] = "119.0.6045.105";

// Save updated metadata
cache.writeMetadata(Browser.CHROME, metadata);

// Resolve aliases
const stableVersion = cache.resolveAlias(Browser.CHROME, "my-stable");
const latestVersion = cache.resolveAlias(Browser.CHROME, "latest");

console.log("Stable version:", stableVersion);
console.log("Latest version:", latestVersion);

Cache Directory Structure

The cache uses a structured directory layout for organizing browser installations:

cache-root/
├── chrome/
│   ├── metadata.json
│   ├── linux-118.0.5993.70/
│   │   └── chrome-linux64/
│   │       └── chrome
│   └── linux-119.0.6045.105/
│       └── chrome-linux64/
│           └── chrome
├── firefox/
│   ├── metadata.json
│   └── linux-119.0/
│       └── firefox/
│           └── firefox
└── chromium/
    ├── metadata.json
    └── linux-1097615/
        └── chrome-linux/
            └── chrome

Directory Methods

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

const cache = new Cache("./browsers-cache");

// Get specific directories
const installDir = cache.installationDir(
  Browser.CHROME,
  BrowserPlatform.LINUX,
  "118.0.5993.70"
);

const browserRoot = cache.browserRoot(Browser.CHROME);
const metadataFile = cache.metadataFile(Browser.CHROME);

console.log("Installation directory:", installDir);
console.log("Browser root:", browserRoot);
console.log("Metadata file:", metadataFile);

Alias Management

Aliases provide human-readable names for browser versions, making it easier to reference commonly used builds.

Common Alias Patterns

  • Release Channels: stable, beta, dev, canary
  • Version Tags: latest, lts, current
  • Custom Names: testing, production, fallback
import { Cache, Browser } from "@puppeteer/browsers";

const cache = new Cache("./browsers-cache");

// Set up aliases for different Chrome channels
const metadata = cache.readMetadata(Browser.CHROME);
metadata.aliases = {
  "stable": "118.0.5993.70",
  "beta": "119.0.6045.105",
  "dev": "120.0.6099.0",
  "canary": "121.0.6120.0",
  "testing": "118.0.5993.70",
  "latest": "119.0.6045.105"
};

cache.writeMetadata(Browser.CHROME, metadata);

// Use aliases to resolve versions
const testingVersion = cache.resolveAlias(Browser.CHROME, "testing");
const latestVersion = cache.resolveAlias(Browser.CHROME, "latest");

console.log("Testing version:", testingVersion);
console.log("Latest version:", latestVersion);

Cache Operations

Installation Tracking

The cache automatically tracks all browser installations and maintains metadata about each installation.

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

const cache = new Cache("./browsers-cache");

// Install multiple browser versions
await install({
  cacheDir: cache.rootDir,
  browser: Browser.CHROME,
  buildId: "118.0.5993.70",
  buildIdAlias: "stable"
});

await install({
  cacheDir: cache.rootDir,
  browser: Browser.CHROME,
  buildId: "119.0.6045.105",
  buildIdAlias: "beta"
});

// List all installations
const browsers = cache.getInstalledBrowsers();
console.log(`Found ${browsers.length} browser installations:`);

browsers.forEach(browser => {
  console.log(`  ${browser.browser}@${browser.buildId}`);
  console.log(`    Platform: ${browser.platform}`);
  console.log(`    Path: ${browser.path}`);
  console.log(`    Executable: ${browser.executablePath}`);
});

Selective Uninstallation

Remove specific browser installations while preserving others.

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

const cache = new Cache("./browsers-cache");

// List installations before cleanup
console.log("Before cleanup:");
cache.getInstalledBrowsers().forEach(browser => {
  console.log(`  ${browser.browser}@${browser.buildId}`);
});

// Remove specific installation
cache.uninstall(Browser.CHROME, BrowserPlatform.LINUX, "118.0.5993.70");

// List installations after cleanup
console.log("After cleanup:");
cache.getInstalledBrowsers().forEach(browser => {
  console.log(`  ${browser.browser}@${browser.buildId}`);
});

Complete Cache Cleanup

Remove all browser installations and metadata.

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

const cache = new Cache("./browsers-cache");

console.log("Installed browsers:", cache.getInstalledBrowsers().length);

// Clear entire cache
cache.clear();

console.log("Cache cleared. Installed browsers:", cache.getInstalledBrowsers().length);

Integration with Installation Functions

The Cache class integrates seamlessly with installation functions, providing automatic metadata management.

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

const cacheDir = "./browsers-cache";

// Install with automatic cache management
const browser = await install({
  cacheDir,
  browser: Browser.CHROME,
  buildId: "118.0.5993.70",
  buildIdAlias: "stable"
});

// Query installations using high-level functions
const installed = await getInstalledBrowsers({ cacheDir });

// Or use Cache class directly for advanced operations
import { Cache } from "@puppeteer/browsers";
const cache = new Cache(cacheDir);

const metadata = cache.readMetadata(Browser.CHROME);
console.log("Available aliases:", Object.keys(metadata.aliases));

Error Handling

Cache operations may encounter various error conditions:

  • File System Errors: Permission issues, disk space, path access
  • Metadata Corruption: Invalid JSON, missing files
  • Directory Issues: Non-existent paths, invalid structure
import { Cache, Browser } from "@puppeteer/browsers";

const cache = new Cache("./browsers-cache");

try {
  const metadata = cache.readMetadata(Browser.CHROME);
  console.log("Metadata loaded successfully");
} catch (error) {
  console.error("Failed to read metadata:", error.message);
  
  // Initialize empty metadata
  cache.writeMetadata(Browser.CHROME, { aliases: {} });
}

try {
  cache.uninstall(Browser.CHROME, BrowserPlatform.LINUX, "nonexistent");
} catch (error) {
  console.error("Uninstall failed:", error.message);
}

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