diff --git a/packages/browsers/README.md b/packages/browsers/README.md index 76f21437..64a68c2f 100644 --- a/packages/browsers/README.md +++ b/packages/browsers/README.md @@ -1,3 +1,42 @@ # @puppeteer/browsers -Manage and launch browsers for Puppeteer. Documentation TODO. +Manage and launch browsers/drivers from a CLI or programmatically. + +## CLI + +Use `npx` to run the CLI without installing: + +```sh +npx @puppeteer/browsers --help +``` + +or install the package as a dependency and run it from your `package.json` script: + +```sh +npm i @puppeteer/browsers +``` + +```json +{ + "scripts": { + "browsers": "@puppeteer/browsers --help" + } +} +``` + +CLI help will provide all documentation you need to use the CLI. + +```sh +npx @puppeteer/browsers --help # help for all commands +npx @puppeteer/browsers install --help # help for the install command +npx @puppeteer/browsers launch --help # help for the launch command +``` + +Known limitations: + +1. We support installing and running Firefox and Chrome/Chromium. The `latest` keyword only works during the installation. For the `launch` command you need to specify an exact build ID. The build ID is provided by the `install` command. +2. Launching the system browsers is only possible for Chrome/Chromium. + +## API + +The programmatic API allows installing and launching browsers from your code. See the `test` folder for examples on how to use the `install`, `canInstall`, `launch`, `computeExecutablePath`, `computeSystemExecutablePath` and other methods. diff --git a/packages/browsers/src/CLI.ts b/packages/browsers/src/CLI.ts index 06b3ca3a..01353f64 100644 --- a/packages/browsers/src/CLI.ts +++ b/packages/browsers/src/CLI.ts @@ -61,7 +61,8 @@ export class CLI { #defineBrowserParameter(yargs: yargs.Argv): void { yargs.positional('browser', { - description: 'The browser version', + description: + 'Which browser to install [@]. `latest` will try to find the latest available build. `buildId` is a browser-specific identifier such as a version or a revision.', type: 'string', coerce: (opt): InstallArgs['browser'] => { return { @@ -77,27 +78,53 @@ export class CLI { type: 'string', desc: 'Platform that the binary needs to be compatible with.', choices: Object.values(BrowserPlatform), - defaultDescription: 'Auto-detected by default.', + defaultDescription: 'Auto-detected', }); } #definePathParameter(yargs: yargs.Argv): void { yargs.option('path', { type: 'string', - desc: 'Path to the root folder for the browser downloads and installation', + desc: 'Path to the root folder for the browser downloads and installation. The installation folder structure is compatible with the cache structure used by Puppeteer.', default: process.cwd(), + defaultDescription: 'Current working directory', }); } async run(argv: string[]): Promise { await yargs(hideBin(argv)) + .scriptName('@puppeteer/browsers') .command( 'install ', - 'Download and install the specified browser', + 'Download and install the specified browser. If successful, the command outputs the actual browser buildId that was installed and the absolute path to the browser executable (format: @ ).', yargs => { this.#defineBrowserParameter(yargs); this.#definePlatformParameter(yargs); this.#definePathParameter(yargs); + yargs.example( + '$0 install chrome', + 'Install the latest available build of the Chrome browser.' + ); + yargs.example( + '$0 install chrome@latest', + 'Install the latest available build for the Chrome browser.' + ); + yargs.example( + '$0 install chromium@1083080', + 'Install the revision 1083080 of the Chromium browser.' + ); + yargs.example( + '$0 install firefox', + 'Install the latest available build of the Firefox browser.' + ); + yargs.example( + '$0 install firefox --platform mac', + 'Install the latest Mac (Intel) build of the Firefox browser.' + ); + yargs.example( + '$0 install firefox --path /tmp/my-browser-cache', + 'Install to the specified cache directory.' + ); }, async argv => { const args = argv as unknown as InstallArgs; @@ -149,6 +176,22 @@ export class CLI { desc: 'Search for a browser installed on the system instead of the cache folder.', default: false, }); + yargs.example( + '$0 launch chrome@1083080', + 'Launch the Chrome browser identified by the revision 1083080.' + ); + yargs.example( + '$0 launch firefox@112.0a1', + 'Launch the Firefox browser identified by the milestone 112.0a1.' + ); + yargs.example( + '$0 launch chrome@1083080 --detached', + 'Launch the browser but detach the sub-processes.' + ); + yargs.example( + '$0 launch chrome@canary --system', + 'Try to locate the Canary build of Chrome installed on the system and launch it.' + ); }, async argv => { const args = argv as unknown as LaunchArgs; @@ -173,6 +216,7 @@ export class CLI { ) .demandCommand(1) .help() + .wrap(Math.min(120, yargs.terminalWidth())) .parse(); }