/** * @license * Copyright 2017 Google Inc. * SPDX-License-Identifier: Apache-2.0 */ import assert from 'node:assert'; import {spawnSync} from 'node:child_process'; import {existsSync, readFileSync} from 'node:fs'; import {mkdir, unlink} from 'node:fs/promises'; import os from 'node:os'; import path from 'node:path'; import type * as ProgressBar from 'progress'; import ProgressBarClass from 'progress'; import { Browser, BrowserPlatform, downloadUrls, } from './browser-data/browser-data.js'; import {Cache, InstalledBrowser} from './Cache.js'; import {debug} from './debug.js'; import {DefaultProvider} from './DefaultProvider.js'; import {detectBrowserPlatform} from './detectPlatform.js'; import {unpackArchive} from './fileUtil.js'; import {downloadFile, headHttpRequest} from './httpUtil.js'; import type {BrowserProvider} from './provider.js'; const debugInstall = debug('puppeteer:browsers:install'); const times = new Map(); function debugTime(label: string) { times.set(label, process.hrtime()); } function debugTimeEnd(label: string) { const end = process.hrtime(); const start = times.get(label); if (!start) { return; } const duration = end[0] * 1000 + end[1] / 1e6 - (start[0] * 1000 + start[1] / 1e6); // calculate duration in milliseconds debugInstall(`Duration for ${label}: ${duration}ms`); } /** * @public */ export interface InstallOptions { /** * Determines the path to download browsers to. */ cacheDir: string; /** * Determines which platform the browser will be suited for. * * @defaultValue **Auto-detected.** */ platform?: BrowserPlatform; /** * Determines which browser to install. */ browser: Browser; /** * Determines which buildId to download. BuildId should uniquely identify * binaries and they are used for caching. */ buildId: string; /** * An alias for the provided `buildId`. It will be used to maintain local * metadata to support aliases in the `launch` command. * * @example 'canary' */ buildIdAlias?: string; /** * Provides information about the progress of the download. If set to * 'default', the default callback implementing a progress bar will be * used. */ downloadProgressCallback?: | 'default' | ((downloadedBytes: number, totalBytes: number) => void); /** * Determines the host that will be used for downloading. * * @defaultValue Either * * - https://storage.googleapis.com/chrome-for-testing-public or * - https://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central * */ baseUrl?: string; /** * Whether to unpack and install browser archives. * * @defaultValue `true` */ unpack?: boolean; /** * @internal * @defaultValue `false` */ forceFallbackForTesting?: boolean; /** * Whether to attempt to install system-level dependencies required * for the browser. * * Only supported for Chrome on Debian or Ubuntu. * Requires system-level privileges to run `apt-get`. * * @defaultValue `false` */ installDeps?: boolean; /** * Custom provider implementation for alternative download sources. * * If not provided, uses the default provider. * Multiple providers can be chained - they will be tried in order. * The default provider is automatically added as the final fallback. * * ⚠️ **IMPORTANT**: Custom providers are NOT officially supported by * Puppeteer. * * By using custom providers, you accept full responsibility for: * * - **Version compatibility**: Different platforms may receive different * binary versions * - **Archive compatibility**: Binary structure must match Puppeteer's expectations * - **Feature integration**: Browser launch and other Puppeteer features may not work * - **Testing**: You must validate that downloaded binaries work with Puppeteer * * **Puppeteer only tests and guarantees compatibility with default binaries.** * * @example * * ```typescript * import {ElectronProvider} from './puppeteer-browser-provider-electron.js'; * * await install({ * browser: Browser.CHROMEDRIVER, * buildId: '142.0.7444.175', * cacheDir: './cache', * providers: [ * new ElectronProvider(), // Try Electron releases first * // Falls back to Chrome for Testing automatically * ], * }); * ``` */ providers?: BrowserProvider[]; } /** * Install using custom provider plugins. * Tries each provider in order until one succeeds. * Falls back to default provider if all custom providers fail. * * @internal */ async function installWithProviders( options: InstallOptions, ): Promise { if (!options.platform) { throw new Error('Platform must be defined'); } const cache = new Cache(options.cacheDir); const browserRoot = cache.browserRoot(options.browser); // Build provider list with proper fallback behavior const providers = [...(options.providers || [])]; // If custom baseUrl is provided, add it as a provider if (options.baseUrl) { providers.push(new DefaultProvider(options.baseUrl)); } // Always add default provider as final fallback // (unless custom baseUrl is provided and forceFallbackForTesting is false) if (!options.baseUrl || options.forceFallbackForTesting) { providers.push(new DefaultProvider()); } const downloadOptions = { browser: options.browser, platform: options.platform, buildId: options.buildId, progressCallback: options.downloadProgressCallback === 'default' ? await makeProgressCallback( options.browser, options.buildIdAlias ?? options.buildId, ) : options.downloadProgressCallback, }; interface ProviderError { providerName: string; error: Error; } const errors: ProviderError[] = []; for (const provider of providers) { try { // Check: does this provider support this browser/platform? if (!(await provider.supports(downloadOptions))) { debugInstall( `Provider ${provider.getName()} does not support ${options.browser} on ${options.platform}`, ); continue; } // Warn if using non-default provider if (!(provider instanceof DefaultProvider)) { debugInstall(`⚠️ Using custom downloader: ${provider.getName()}`); debugInstall( `⚠️ Puppeteer does not guarantee compatibility with non-default providers`, ); } debugInstall( `Trying provider: ${provider.getName()} for ${options.browser} ${options.buildId}`, ); // Get download URL from provider const url = await provider.getDownloadUrl(downloadOptions); if (!url) { debugInstall( `Provider ${provider.getName()} returned no URL for ${options.browser} ${options.buildId}`, ); continue; } debugInstall(`Successfully got URL from ${provider.getName()}: ${url}`); if (!existsSync(browserRoot)) { await mkdir(browserRoot, {recursive: true}); } // Download and install using the URL from the provider return await installUrl(url, options, provider); } catch (err) { debugInstall( `Provider ${provider.getName()} failed: ${(err as Error).message}`, ); errors.push({ providerName: provider.getName(), error: err as Error, }); // Continue to next provider } } // All providers failed const errorDetails = errors .map(e => { return ` - ${e.providerName}: ${e.error.message}`; }) .join('\n'); throw new Error( `All providers failed for ${options.browser} ${options.buildId}:\n${errorDetails}`, ); } /** * Downloads and unpacks the browser archive according to the * {@link InstallOptions}. * * @returns a {@link InstalledBrowser} instance. * * @public */ export function install( options: InstallOptions & {unpack?: true}, ): Promise; /** * Downloads the browser archive according to the {@link InstallOptions} without * unpacking. * * @returns the absolute path to the archive. * * @public */ export function install( options: InstallOptions & {unpack: false}, ): Promise; export async function install( options: InstallOptions, ): Promise { options.platform ??= detectBrowserPlatform(); options.unpack ??= true; if (!options.platform) { throw new Error( `Cannot download a binary for the provided platform: ${os.platform()} (${os.arch()})`, ); } // Always use plugin architecture (uses default provider if none specified) options.providers ??= []; return await installWithProviders(options); } async function installDeps(installedBrowser: InstalledBrowser) { if ( process.platform !== 'linux' || installedBrowser.platform !== BrowserPlatform.LINUX ) { return; } // Currently, only Debian-like deps are supported. const depsPath = path.join( path.dirname(installedBrowser.executablePath), 'deb.deps', ); if (!existsSync(depsPath)) { debugInstall(`deb.deps file was not found at ${depsPath}`); return; } const data = readFileSync(depsPath, 'utf-8').split('\n').join(','); if (process.getuid?.() !== 0) { throw new Error('Installing system dependencies requires root privileges'); } let result = spawnSync('apt-get', ['-v']); if (result.status !== 0) { throw new Error( 'Failed to install system dependencies: apt-get does not seem to be available', ); } debugInstall(`Trying to install dependencies: ${data}`); result = spawnSync('apt-get', [ 'satisfy', '-y', data, '--no-install-recommends', ]); if (result.status !== 0) { throw new Error( `Failed to install system dependencies: status=${result.status},error=${result.error},stdout=${result.stdout.toString('utf8')},stderr=${result.stderr.toString('utf8')}`, ); } debugInstall(`Installed system dependencies ${data}`); } async function installUrl( url: URL, options: InstallOptions, provider: BrowserProvider, ): Promise { if (!provider) { throw new Error('Provider is required for installation'); } options.platform ??= detectBrowserPlatform(); if (!options.platform) { throw new Error( `Cannot download a binary for the provided platform: ${os.platform()} (${os.arch()})`, ); } let downloadProgressCallback = options.downloadProgressCallback; if (downloadProgressCallback === 'default') { downloadProgressCallback = await makeProgressCallback( options.browser, options.buildIdAlias ?? options.buildId, ); } const fileName = decodeURIComponent(url.toString()).split('/').pop(); assert(fileName, `A malformed download URL was found: ${url}.`); const cache = new Cache(options.cacheDir); const browserRoot = cache.browserRoot(options.browser); const archivePath = path.join(browserRoot, `${options.buildId}-${fileName}`); if (!existsSync(browserRoot)) { await mkdir(browserRoot, {recursive: true}); } if (!options.unpack) { if (existsSync(archivePath)) { return archivePath; } debugInstall(`Downloading binary from ${url}`); debugTime('download'); await downloadFile(url, archivePath, downloadProgressCallback); debugTimeEnd('download'); return archivePath; } const outputPath = cache.installationDir( options.browser, options.platform, options.buildId, ); // Get executable path from provider once (used for both cached and new installations) const relativeExecutablePath = await provider.getExecutablePath({ browser: options.browser, buildId: options.buildId, platform: options.platform, }); debugInstall( `Using executable path from provider: ${relativeExecutablePath}`, ); const installedBrowser = new InstalledBrowser( cache, options.browser, options.buildId, options.platform, ); // Write metadata for the installation (only for non-default providers) if (!(provider instanceof DefaultProvider)) { cache.writeExecutablePath( options.browser, options.platform, options.buildId, relativeExecutablePath, ); } try { if (existsSync(outputPath)) { if (!existsSync(installedBrowser.executablePath)) { throw new Error( `The browser folder (${outputPath}) exists but the executable (${installedBrowser.executablePath}) is missing`, ); } await runSetup(installedBrowser); if (options.installDeps) { await installDeps(installedBrowser); } return installedBrowser; } // Check if archive already exists (e.g., from a custom provider) if (!existsSync(archivePath)) { debugInstall(`Downloading binary from ${url}`); try { debugTime('download'); await downloadFile(url, archivePath, downloadProgressCallback); } finally { debugTimeEnd('download'); } } else { debugInstall(`Using existing archive at ${archivePath}`); } debugInstall(`Installing ${archivePath} to ${outputPath}`); try { debugTime('extract'); await unpackArchive(archivePath, outputPath); } finally { debugTimeEnd('extract'); } if (options.buildIdAlias) { const metadata = installedBrowser.readMetadata(); metadata.aliases[options.buildIdAlias] = options.buildId; installedBrowser.writeMetadata(metadata); } await runSetup(installedBrowser); if (options.installDeps) { await installDeps(installedBrowser); } return installedBrowser; } finally { if (existsSync(archivePath)) { await unlink(archivePath); } } } async function runSetup(installedBrowser: InstalledBrowser): Promise { // On Windows for Chrome invoke setup.exe to configure sandboxes. if ( (installedBrowser.platform === BrowserPlatform.WIN32 || installedBrowser.platform === BrowserPlatform.WIN64) && installedBrowser.browser === Browser.CHROME && installedBrowser.platform === detectBrowserPlatform() ) { try { debugTime('permissions'); const browserDir = path.dirname(installedBrowser.executablePath); const setupExePath = path.join(browserDir, 'setup.exe'); if (!existsSync(setupExePath)) { return; } spawnSync( path.join(browserDir, 'setup.exe'), [`--configure-browser-in-directory=` + browserDir], { shell: true, }, ); // TODO: Handle error here. Currently the setup.exe sometimes // errors although it sets the permissions correctly. } finally { debugTimeEnd('permissions'); } } } /** * @public */ export interface UninstallOptions { /** * Determines the platform for the browser binary. * * @defaultValue **Auto-detected.** */ platform?: BrowserPlatform; /** * The path to the root of the cache directory. */ cacheDir: string; /** * Determines which browser to uninstall. */ browser: Browser; /** * The browser build to uninstall */ buildId: string; } /** * * @public */ export async function uninstall(options: UninstallOptions): Promise { options.platform ??= detectBrowserPlatform(); if (!options.platform) { throw new Error( `Cannot detect the browser platform for: ${os.platform()} (${os.arch()})`, ); } new Cache(options.cacheDir).uninstall( options.browser, options.platform, options.buildId, ); } /** * @public */ export interface GetInstalledBrowsersOptions { /** * The path to the root of the cache directory. */ cacheDir: string; } /** * Returns metadata about browsers installed in the cache directory. * * @public */ export async function getInstalledBrowsers( options: GetInstalledBrowsersOptions, ): Promise { return new Cache(options.cacheDir).getInstalledBrowsers(); } /** * @public */ export async function canDownload(options: InstallOptions): Promise { options.platform ??= detectBrowserPlatform(); if (!options.platform) { throw new Error( `Cannot download a binary for the provided platform: ${os.platform()} (${os.arch()})`, ); } // Always use plugin architecture (uses default provider if none specified) const providers = [ ...(options.providers || []), new DefaultProvider(options.baseUrl), ]; const downloadOptions = { browser: options.browser, platform: options.platform, buildId: options.buildId, }; // Check if any provider can provide a valid, downloadable URL for (const provider of providers) { if (!(await provider.supports(downloadOptions))) { continue; } const url = await provider.getDownloadUrl(downloadOptions); if (url && (await headHttpRequest(url))) { return true; } } return false; } /** * Retrieves a URL for downloading the binary archive of a given browser. * * The archive is bound to the specific platform and build ID specified. * * @public */ export function getDownloadUrl( browser: Browser, platform: BrowserPlatform, buildId: string, baseUrl?: string, ): URL { return new URL(downloadUrls[browser](platform, buildId, baseUrl)); } /** * @public */ export function makeProgressCallback( browser: Browser, buildId: string, ): (downloadedBytes: number, totalBytes: number) => void { let progressBar: ProgressBar; let lastDownloadedBytes = 0; return (downloadedBytes: number, totalBytes: number) => { if (!progressBar) { progressBar = new ProgressBarClass( `Downloading ${browser} ${buildId} - ${toMegabytes(totalBytes)} [:bar] :percent :etas `, { complete: '=', incomplete: ' ', width: 20, total: totalBytes, }, ); } const delta = downloadedBytes - lastDownloadedBytes; lastDownloadedBytes = downloadedBytes; progressBar.tick(delta); }; } function toMegabytes(bytes: number) { const mb = bytes / 1000 / 1000; return `${Math.round(mb * 10) / 10} MB`; }