stable-chromium/CLAUDE.md

A library to install stable Chromium for testing via Gauge and Taiko

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**stable-chromium** is an npm library for automated Chrome browser installation in testing environments. The package copies a pre-tested stable Chrome build from a network share and extracts it locally during `postinstall`.

**Purpose**: Provides a controlled, stable Chrome version for automated testing frameworks (Gauge/Taiko), avoiding issues from frequent Chrome auto-updates.

**Critical Context**: This is **not** a standard Chrome downloader. It copies a **specific pre-validated build** from a corporate network share (configured in `config.json`), ensuring all testing environments use an identical, manually tested Chrome version.

**Multi-Platform Support**: The library automatically detects the platform (Windows/Linux) and uses the appropriate archive format and extraction method.

## Architecture

### Core Components

- **index.js**: Main entry point with three functions:
  - `downloadChrome()`: Downloads Chrome ZIP archive (via HTTP) or copies from network share
  - `extractChrome()`: Unpacks downloaded ZIP archive and cleans up
  - `installChrome()`: Orchestrates download → extract flow

- **config.json**: Configuration file with platform-specific paths:
  - `platforms.win32`: Windows configuration
    - `Chrome_URL`: Source UNC path to Chrome zip on network share (e.g., `\\server\share\chrome.zip`)
    - `DOWNLOAD_PATH`: Temporary local path for downloaded zip
    - `EXTRACT_PATH`: Target directory for extracted Chrome files
  - `platforms.linux`: Linux configuration
    - `Chrome_URL`: HTTP(S) URL to Chrome zip for download (e.g., Google Cloud Storage URL)
    - `DOWNLOAD_PATH`: Temporary local path for downloaded zip
    - `EXTRACT_PATH`: Target directory for extracted Chrome files

- **package.json**:
  - `postinstall` hook automatically runs `index.js` after npm install
  - `version` field indicates Chrome major version (e.g., "126.0.0")

### Workflow

1. User runs `npm install stable-chromium`
2. `postinstall` hook triggers → executes `index.js`
3. Script detects platform using `os.platform()` (win32/linux)
4. Loads platform-specific configuration from `config.json`
5. Downloads/copies Chrome ZIP archive:
   - **Windows**: Copies from network share (UNC path)
   - **Linux**: Downloads from HTTP(S) URL (Google Cloud Storage)
6. Extracts ZIP archive to `EXTRACT_PATH`
7. Deletes temporary ZIP file

### Key Implementation Details

- **Platform Detection**: Uses `os.platform()` to determine OS and select appropriate config
- **Dual Download Mode**:
  - **HTTP(S) URLs**: Downloads via `axios` with progress tracking
  - **Local/Network Paths**: Copies files using `fs.createReadStream`
  - Automatically detects mode based on URL format (http/https prefix)
- **UNC Path Handling**: Normalizes Windows UNC paths (ensures `\\` prefix for network shares)
- **ZIP Extraction**: Uses `extract-zip` for all platforms (both Windows and Linux use .zip format)
- **Progress Tracking**: Shows download progress percentage for HTTP downloads
- **Error Handling**: Each stage (download/extract) logs errors and stops installation on failure
- **Automatic Cleanup**: Downloaded archive is deleted after successful extraction
- **Directory Creation**: Auto-creates directories if they don't exist (`ensureDirExists`)

## Development Commands

### Testing the Installation
```bash
node index.js
```
Runs the Chrome installation process manually (useful for testing changes).

### Publishing Updates
When updating Chrome version:
1. Update `package.json` version to match new Chrome major version
2. Update `Chrome_URL` in both `platforms.win32` and `platforms.linux` sections in `config.json`
3. Ensure both Windows and Linux builds are tested and validated
4. Update README.md with new version info (if documented)

### Dependencies
```bash
npm install
```
Installs required packages:
- `axios`: Handles HTTP(S) downloads for Linux platform
- `extract-zip`: Handles ZIP extraction for all platforms
- `tar`: Legacy dependency (can be removed)

## Important Notes

- **Multi-Platform Support**: Works on Windows (win32) and Linux platforms
- **Archive Format**: Both platforms use .zip format
- **Download Methods**:
  - **Windows**: Copies from corporate network share (UNC path)
  - **Linux**: Downloads from internet (Google Cloud Storage)
- **Network Requirements**:
  - **Windows**: Requires access to corporate network share
  - **Linux**: Requires internet connection
- **Manual Validation**: Chrome builds are manually tested by library author before distribution
- **Configuration Required**: Users must configure `config.json` paths/URLs for their environment

## Common Modification Scenarios

### Changing Chrome Source Location
Edit `config.json` → `platforms.win32.Chrome_URL` or `platforms.linux.Chrome_URL` with new network path.

### Changing Extraction Target
Edit `config.json` → `platforms.{platform}.EXTRACT_PATH` field (default: current directory `./`).

### Adding Support for Other Platforms
1. Add new platform entry in `config.json` under `platforms` (e.g., `darwin` for macOS)
2. Provide Chrome ZIP archive path for the new platform
3. Script will automatically detect and use the configuration (uses .zip extraction)

### Switching Between HTTP and Network Share
The `Chrome_URL` field supports both HTTP(S) URLs and local/network paths:
- **HTTP(S) URL**: `"https://example.com/chrome.zip"` → Downloads via axios
- **Network Path**: `"\\\\server\\share\\chrome.zip"` or `/mnt/share/chrome.zip` → Copies via fs
- Script automatically detects mode based on URL format