CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-chromedriver

NPM wrapper for Selenium ChromeDriver that manages binary downloads and provides cross-platform browser automation support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

installation-config.mddocs/

Installation Configuration

Comprehensive configuration system for customizing ChromeDriver installation behavior, including version selection, download sources, proxy settings, and platform-specific options.

Configuration Methods

ChromeDriver supports multiple configuration methods with the following precedence order:

  1. Environment variables (uppercase, e.g., CHROMEDRIVER_VERSION)
  2. package.json config section (lowercase)
  3. .npmrc entries (lowercase, deprecated in NPM 12+)

Capabilities

Version Management

Control which version of ChromeDriver to download and install.

/**
 * Specify ChromeDriver version to install
 * @type {string}
 * @default "140.0.0" (package default)
 * @example "LATEST" | "120.0.6099.109" | "140.0.0"
 */
const CHROMEDRIVER_VERSION;

/**
 * Auto-detect ChromeDriver version based on installed Chrome
 * @type {string}
 * @default "false"
 * @example "true" | "false"
 */
const DETECT_CHROMEDRIVER_VERSION;

/**
 * Include Chromium in version detection process
 * @type {string}
 * @default "false"
 * @example "true" | "false"
 */
const INCLUDE_CHROMIUM;

Usage Examples:

# Environment variable configuration
CHROMEDRIVER_VERSION=LATEST npm install chromedriver
DETECT_CHROMEDRIVER_VERSION=true npm install chromedriver
INCLUDE_CHROMIUM=true DETECT_CHROMEDRIVER_VERSION=true npm install chromedriver
{
  "config": {
    "chromedriver_version": "120.0.6099.109",
    "detect_chromedriver_version": "true",
    "include_chromium": "true"
  }
}
# .npmrc configuration (NPM <= 11)
chromedriver_version=LATEST
detect_chromedriver_version=true

Download Control

Control whether and how ChromeDriver binaries are downloaded.

/**
 * Skip downloading ChromeDriver binary entirely
 * @type {string}
 * @default "false"
 * @example "true" | "false"
 */
const CHROMEDRIVER_SKIP_DOWNLOAD;

/**
 * Force re-download even if binary already exists
 * @type {string}
 * @default "false"
 * @example "true" | "false"
 */
const CHROMEDRIVER_FORCE_DOWNLOAD;

/**
 * Use local file instead of downloading
 * @type {string}
 * @example "/path/to/chromedriver_mac64.zip" | "/bin/chromedriver"
 */
const CHROMEDRIVER_FILEPATH;

Usage Examples:

# Skip download (use system ChromeDriver)
CHROMEDRIVER_SKIP_DOWNLOAD=true npm install chromedriver

# Force fresh download
CHROMEDRIVER_FORCE_DOWNLOAD=true npm install chromedriver

# Use local file
CHROMEDRIVER_FILEPATH=/usr/local/bin/chromedriver npm install chromedriver
CHROMEDRIVER_FILEPATH=/downloads/chromedriver_mac64.zip npm install chromedriver
{
  "config": {
    "chromedriver_skip_download": "true",
    "chromedriver_force_download": "true",
    "chromedriver_filepath": "/path/to/chromedriver_linux64.zip"
  }
}

Custom Download Sources

Configure custom endpoints for metadata and binary downloads, useful for air-gapped environments or mirrors.

/**
 * Custom metadata endpoint URL
 * @type {string}
 * @default "https://googlechromelabs.github.io"
 * @example "https://npmmirror.com/metadata"
 */
const CHROMEDRIVER_CDNURL;

/**
 * Custom binaries download URL
 * @type {string}
 * @default undefined (derived from metadata)
 * @example "https://npmmirror.com/binaries"
 */
const CHROMEDRIVER_CDNBINARIESURL;

/**
 * Legacy CDN URL for older ChromeDriver versions
 * @type {string}
 * @default "https://chromedriver.storage.googleapis.com"
 * @example "https://legacy-mirror.example.com"
 */
const CHROMEDRIVER_LEGACY_CDNURL;

Usage Examples:

# Custom mirror configuration
CHROMEDRIVER_CDNURL=https://npmmirror.com/metadata \
CHROMEDRIVER_CDNBINARIESURL=https://npmmirror.com/binaries \
npm install chromedriver

# Enterprise proxy configuration
CHROMEDRIVER_CDNURL=https://internal-proxy.company.com/chrome-metadata \
npm install chromedriver
{
  "config": {
    "chromedriver_cdnurl": "https://internal-mirror.company.com/metadata",
    "chromedriver_cdnbinariesurl": "https://internal-mirror.company.com/binaries",
    "chromedriver_legacy_cdnurl": "https://legacy.internal-mirror.company.com"
  }  
}

Proxy Configuration

Configure HTTP/HTTPS proxies for ChromeDriver downloads.

/**
 * HTTP proxy configuration
 * Standard NPM proxy configuration
 */
// npm config set proxy http://[user:pwd]@domain.tld:port
// npm config set https-proxy http://[user:pwd]@domain.tld:port

/**
 * Custom User-Agent for downloads
 * Standard NPM user-agent configuration  
 */
// npm config set user-agent "Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Firefox/52.0"

Usage Examples:

# Proxy configuration
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy https://proxy.company.com:8080
npm install chromedriver

# Custom User-Agent
npm config set user-agent "Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Firefox/52.0"
npm install chromedriver

# Authenticated proxy
npm config set proxy http://username:password@proxy.company.com:8080
npm install chromedriver

Installation Process

Configuration Resolution

The installer resolves configuration using this priority order:

Resolution Order:

  1. process.env[NAME.toUpperCase()] (e.g., CHROMEDRIVER_VERSION)
  2. process.env[npm_package_config_${name}] (from package.json config)
  3. process.env[npm_config_${name}] (from .npmrc or npm arguments)

Platform Detection

The installer automatically detects the appropriate binary variant based on the current platform and architecture:

Supported Platform Mappings:

OSArchitectureVersion RangePlatform ID
Windowsx64120.0.0+win64
Windowsx64/x86< 120.0.0win32
Windowsx86114.0.0+win32
macOSx64116.0.0+mac-x64
macOSx64< 116.0.0mac64
macOSarm64116.0.0+mac-arm64
macOSarm64114.0.0+mac_arm64
macOSarm64< 114.0.0mac64_m1
Linuxx64Anylinux64
Linuxarm64114.0.0+linux64

Version Detection Logic

When DETECT_CHROMEDRIVER_VERSION=true:

// Automatic Chrome version detection
const chromeVersion = await getChromeVersion(includeChromium);
console.log("Your Chrome version is " + chromeVersion);

// Extract major version (e.g., "120.0.6099.129" → "120")
const versionMatch = /^(.*?)\.\d+$/.exec(chromeVersion);
if (versionMatch) {
  const majorVersion = parseInt(versionMatch[1]);
  const chromedriverVersion = await getChromeDriverVersion(cdnUrl, legacyCdnUrl, majorVersion);
  console.log("Compatible ChromeDriver version is " + chromedriverVersion);
}

Error Handling

Unsupported Platforms

For unsupported platform/architecture combinations:

console.error(`Unsupported platform: ${process.platform}-${process.arch}`);
process.exit(1);

Network Errors

Download failures are logged with detailed error information:

// Automatic retry logic and fallback handling
try {
  await downloadFromPrimary();
} catch (error) {
  console.error('Primary download failed:', error.message);
  await downloadFromFallback();
}

RISC-V Architecture

RISC-V systems require manual binary provision:

# RISC-V installation requires custom binary
npm install chromedriver --chromedriver_filepath=/path/to/riscv-chromedriver

Air-Gapped Environments

For environments without internet access:

{
  "config": {
    "chromedriver_skip_download": "true"
  }
}

Or provide a local binary:

{
  "config": {
    "chromedriver_filepath": "/opt/chromedriver/chromedriver-linux64"
  }
}

Install with Tessl CLI

npx tessl i tessl/npm-chromedriver

docs

binary-info.md

cli.md

index.md

installation-config.md

process-management.md

tile.json