Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
38 changes: 36 additions & 2 deletions bin/playwright-install
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,10 @@ final class PlaywrightServerInstaller

private bool $withDeps;

private bool $noShell;

private bool $onlyShell;

/**
* @var list<string>
*/
Expand All @@ -65,14 +69,16 @@ final class PlaywrightServerInstaller
/**
* @param list<string> $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();
$this->verbose = $verbose;
$this->dryRun = $dryRun;
$this->shouldInstallBrowsers = $installBrowsers;
$this->withDeps = $withDeps;
$this->noShell = $noShell;
$this->onlyShell = $onlyShell;
$this->browserTargets = $browserTargets;

if ($this->verbose) {
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -441,6 +455,8 @@ $verbose = false;
$dryRun = false;
$installBrowsers = false;
$withDeps = false;
$noShell = false;
$onlyShell = false;
$help = false;
$browserTargets = [];
$defaultBrowsersRequested = false;
Expand Down Expand Up @@ -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));
Expand All @@ -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");

Expand All @@ -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";
Expand Down Expand Up @@ -557,12 +589,14 @@ 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";
echo " playwright-install --package-manager-bin=/path/to/npm --browsers\n";
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());
26 changes: 26 additions & 0 deletions docs/guide/browsers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
34 changes: 34 additions & 0 deletions tests/Integration/Installer/PlaywrightInstallCliTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,38 @@ public function itForwardsBrowserTargetsAfterTheSystemDependenciesOption(): void
$this->assertStringContainsString("'playwright' 'install' '--with-deps' 'chromium' 'firefox'", $process->getOutput());
}

/**
* @param list<string> $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
{
Expand Down Expand Up @@ -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]
Expand Down
Loading