diff --git a/CHANGELOG.md b/CHANGELOG.md index 9df8944..f23b2ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ - `Page::screenshotAuto()` accepts `ScreenshotOptions`, like `Page::screenshot()` (#210) - `PageEventHandlerInterface::onDownload()` receives each `Download` a page starts (#211) - `PageInterface::waitForDownload()` runs an action and returns the `Download` it starts, with `path()`, `saveAs()`, `failure()`, `cancel()`, `delete()` and `createReadStream()` working end to end (#211) +- `--no-shell` and `--only-shell` installer options choose between full Chromium and Chromium headless shell (#203) ### Changed - `ScreenshotHelper::cleanupOldScreenshots()` and `getDirectoryInfo()` include `.jpeg`, `.jpg` and `.webp` files along with `.png`; cleanup now deletes old files of these formats (#208) diff --git a/bin/playwright-install b/bin/playwright-install index 21d4b7d..75b01e7 100755 --- a/bin/playwright-install +++ b/bin/playwright-install @@ -50,6 +50,10 @@ final class PlaywrightServerInstaller private bool $withDeps; + private bool $noShell; + + private bool $onlyShell; + /** * @var list */ @@ -65,7 +69,7 @@ final class PlaywrightServerInstaller /** * @param list $browserTargets */ - public function __construct(bool $verbose, bool $dryRun, bool $installBrowsers, bool $withDeps, array $browserTargets, private ?string $packageManagerBinary = null) + public function __construct(bool $verbose, bool $dryRun, bool $installBrowsers, bool $withDeps, bool $noShell, bool $onlyShell, array $browserTargets, private ?string $packageManagerBinary = null) { $this->serverDir = __DIR__; $this->output = new ConsoleOutput(); @@ -73,6 +77,8 @@ final class PlaywrightServerInstaller $this->dryRun = $dryRun; $this->shouldInstallBrowsers = $installBrowsers; $this->withDeps = $withDeps; + $this->noShell = $noShell; + $this->onlyShell = $onlyShell; $this->browserTargets = $browserTargets; if ($this->verbose) { @@ -345,6 +351,14 @@ final class PlaywrightServerInstaller $args[] = '--with-deps'; } + if ($this->noShell) { + $args[] = '--no-shell'; + } + + if ($this->onlyShell) { + $args[] = '--only-shell'; + } + array_push($args, ...$this->browserTargets); return match ($packageManager) { @@ -441,6 +455,8 @@ $verbose = false; $dryRun = false; $installBrowsers = false; $withDeps = false; +$noShell = false; +$onlyShell = false; $help = false; $browserTargets = []; $defaultBrowsersRequested = false; @@ -488,6 +504,14 @@ for ($index = 0; $index < count($args); ++$index) { $installBrowsers = true; $withDeps = true; break; + case '--no-shell': + $installBrowsers = true; + $noShell = true; + break; + case '--only-shell': + $installBrowsers = true; + $onlyShell = true; + break; default: if (str_starts_with($arg, '-')) { throw new \InvalidArgumentException(sprintf('Unknown option: %s', $arg)); @@ -510,6 +534,12 @@ for ($index = 0; $index < count($args); ++$index) { } } +if ($noShell && $onlyShell) { + fwrite(STDERR, "The --no-shell and --only-shell options cannot be used together.\n"); + + exit(2); +} + if ($defaultBrowsersRequested && [] !== $browserTargets) { fwrite(STDERR, "The --browsers option cannot be combined with explicit browser targets.\n"); @@ -527,6 +557,8 @@ if ($help) { echo " --dry-run Print commands without executing install steps\n"; echo " --browsers Install Playwright's default browsers\n"; echo " --with-deps Install selected browsers and system dependencies\n"; + echo " --no-shell Skip Chromium's headless shell when installing browsers\n"; + echo " --only-shell Install Chromium's headless shell without full Chromium\n"; echo " --package-manager-bin=PATH Use a specific npm, yarn, or pnpm executable\n"; echo "\n"; echo "Managed browser targets:\n"; @@ -557,6 +589,8 @@ if ($help) { echo "\n"; echo "Examples:\n"; echo " playwright-install --browsers\n"; + echo " playwright-install --no-shell\n"; + echo " playwright-install chromium --only-shell\n"; echo " playwright-install firefox\n"; echo " playwright-install chromium webkit\n"; echo " playwright-install chrome\n"; @@ -564,5 +598,5 @@ if ($help) { exit(0); } -$installer = new PlaywrightServerInstaller($verbose, $dryRun, $installBrowsers, $withDeps, $browserTargets, $packageManagerBinary); +$installer = new PlaywrightServerInstaller($verbose, $dryRun, $installBrowsers, $withDeps, $noShell, $onlyShell, $browserTargets, $packageManagerBinary); exit($installer->install()); diff --git a/docs/guide/browsers.md b/docs/guide/browsers.md index 8047226..0a18958 100644 --- a/docs/guide/browsers.md +++ b/docs/guide/browsers.md @@ -42,6 +42,32 @@ installs Google Chrome and does not install Playwright-managed Chromium. There is no `safari` target because Playwright uses a patched WebKit build, not the installed Safari application. +## Install Chromium with or without the headless shell + +The `chromium` target, and the default set, install two Chromium builds: the +full browser and Chromium headless shell. Playwright picks one at launch: + +| Launch | Build used | +| --- | --- | +| Headless, the default | Chromium headless shell | +| Headed (`headless: false`) | Full Chromium | +| `channel: 'chromium'` | Full Chromium, in headless or headed mode | + +Skip the build your project does not launch to save download time and disk +space: + +```bash +# Headless runs only, for example in CI +vendor/bin/playwright-install chromium --only-shell + +# Headed runs, or the 'chromium' channel +vendor/bin/playwright-install chromium --no-shell +``` + +Both options also apply without a target, to the default set. They cannot be +used together. With `--no-shell`, a default headless launch fails because the +headless shell is missing: launch headed or with the `chromium` channel. + ## Understand branded browser installation Google Chrome and Microsoft Edge are installed in the operating system's global diff --git a/tests/Integration/Installer/PlaywrightInstallCliTest.php b/tests/Integration/Installer/PlaywrightInstallCliTest.php index 0149dfd..1beea04 100644 --- a/tests/Integration/Installer/PlaywrightInstallCliTest.php +++ b/tests/Integration/Installer/PlaywrightInstallCliTest.php @@ -48,6 +48,38 @@ public function itForwardsBrowserTargetsAfterTheSystemDependenciesOption(): void $this->assertStringContainsString("'playwright' 'install' '--with-deps' 'chromium' 'firefox'", $process->getOutput()); } + /** + * @param list $options + */ + #[Test] + #[DataProvider('chromiumShellOptions')] + public function itForwardsTheChromiumShellOptionsToPlaywright(array $options, string $expectedCommand): void + { + $process = $this->runInstaller(['--dry-run', '--verbose', ...$options]); + + $this->assertSame(0, $process->getExitCode(), $process->getErrorOutput()); + $this->assertStringContainsString($expectedCommand, $process->getOutput()); + } + + public static function chromiumShellOptions(): iterable + { + yield 'no shell alone installs the default browsers' => [['--no-shell'], "'playwright' 'install' '--no-shell'\n"]; + yield 'only shell alone installs the default browsers' => [['--only-shell'], "'playwright' 'install' '--only-shell'\n"]; + yield 'no shell with the default shortcut' => [['--browsers', '--no-shell'], "'playwright' 'install' '--no-shell'\n"]; + yield 'only shell with a browser target' => [['chromium', '--only-shell'], "'playwright' 'install' '--only-shell' 'chromium'"]; + yield 'no shell with system dependencies' => [['--with-deps', '--no-shell', 'chromium'], "'playwright' 'install' '--with-deps' '--no-shell' 'chromium'"]; + } + + #[Test] + public function itRejectsBothChromiumShellOptionsTogether(): void + { + $process = $this->runInstaller(['--no-shell', '--only-shell']); + + $this->assertSame(2, $process->getExitCode()); + $this->assertSame('', $process->getOutput()); + $this->assertSame("The --no-shell and --only-shell options cannot be used together.\n", $process->getErrorOutput()); + } + #[Test] public function itKeepsTheDefaultBrowserInstallShortcut(): void { @@ -110,6 +142,8 @@ public function itListsTheSupportedBrowserTargetsInHelp(): void $this->assertStringContainsString('Branded browser targets:', $process->getOutput()); $this->assertStringContainsString('chrome Google Chrome stable', $process->getOutput()); $this->assertStringContainsString('msedge-beta Microsoft Edge Beta', $process->getOutput()); + $this->assertStringContainsString("--no-shell Skip Chromium's headless shell", $process->getOutput()); + $this->assertStringContainsString("--only-shell Install Chromium's headless shell", $process->getOutput()); } #[Test]