Add support for PLAYWRIGHT_BROWSERS_PATH

README.md

@@ -48,6 +48,9 @@ vendor/bin/playwright-install --with-deps
 vendor/bin/playwright-install --dry-run --with-deps
 ```
 
+For advanced install options (including browser cache location), see the
+[Getting Started guide](docs/guide/getting-started.md).
+
 
 ## Quick start
 

bin/playwright-install

@@ -407,6 +407,9 @@ if ($help) {
     echo "\n";
     echo "This script automatically detects and uses the fastest available package manager.\n";
     echo "Preference order: pnpm > yarn > npm\n";
+    echo "\n";
+    echo "Environment:\n";
+    echo "  PLAYWRIGHT_BROWSERS_PATH   Custom directory for Playwright browser binaries\n";
     exit(0);
 }
 

docs/guide/getting-started.md

@@ -43,6 +43,12 @@ vendor/bin/playwright-install --with-deps
 Both commands ensure the bundled Playwright server is up to date and then download the latest browser versions into the
 local Playwright cache.
 
+If you need a custom browsers cache location (for example in CI), set `PLAYWRIGHT_BROWSERS_PATH`:
+
+```bash
+PLAYWRIGHT_BROWSERS_PATH=/path/to/.playwright-browsers vendor/bin/playwright-install --browsers
+```
+
 ## Your First Script
 
 You're now ready to write your first script. Create a new file named `example.php` and add the following code:

src/Configuration/PlaywrightConfigBuilder.php

@@ -29,12 +29,17 @@
 final class PlaywrightConfigBuilder
 {
     private ?string $nodePath = null;
+
     private string $minNodeVersion = '20.0.0';
 
     private BrowserType $browser = BrowserType::CHROMIUM;
+
     private ?string $channel = null;
+
     private bool $headless = true;
+
     private int $timeoutMs = 30_000;
+
     private int $slowMoMs = 0;
 
     /** @var array<int, string> */
@@ -44,11 +49,15 @@ final class PlaywrightConfigBuilder
     private array $env = [];
 
     private ?string $downloadsDir = null;
+
     private ?string $videosDir = null;
 
     private bool $tracingEnabled = false;
+
     private ?string $traceDir = null;
+
     private bool $traceScreenshots = true;
+
     private bool $traceSnapshots = true;
 
     /** @var array{server?: string, username?: string, password?: string, bypass?: string}|null */
@@ -77,6 +86,9 @@ public static function fromEnv(): self
         if ($min = $get('PLAYWRIGHT_NODE_MIN_VERSION')) {
             $b->withMinNodeVersion($min);
         }
+        if ($browsersPath = $get('PLAYWRIGHT_BROWSERS_PATH')) {
+            $b->addEnv('PLAYWRIGHT_BROWSERS_PATH', $browsersPath);
+        }
 
         if ($browser = $get('PW_BROWSER')) {
             $browser = strtolower($browser);

tests/Unit/Configuration/PlaywrightConfigBuilderTest.php

@@ -29,6 +29,7 @@ private function clearEnvironment(): void
         $envVars = [
             'PLAYWRIGHT_NODE_PATH',
             'PLAYWRIGHT_NODE_MIN_VERSION',
+            'PLAYWRIGHT_BROWSERS_PATH',
             'PW_BROWSER',
             'PW_CHANNEL',
             'PW_HEADLESS',
@@ -234,6 +235,7 @@ public function itCreatesFromEnvironmentVariables(): void
     {
         putenv('PLAYWRIGHT_NODE_PATH=/env/node');
         putenv('PLAYWRIGHT_NODE_MIN_VERSION=19.0.0');
+        putenv('PLAYWRIGHT_BROWSERS_PATH=/env/ms-playwright');
         putenv('PW_BROWSER=firefox');
         putenv('PW_CHANNEL=nightly');
         putenv('PW_HEADLESS=false');
@@ -252,6 +254,7 @@ public function itCreatesFromEnvironmentVariables(): void
 
         $this->assertEquals('/env/node', $config->nodePath);
         $this->assertEquals('19.0.0', $config->minNodeVersion);
+        $this->assertEquals('/env/ms-playwright', $config->env['PLAYWRIGHT_BROWSERS_PATH'] ?? null);
         $this->assertEquals(BrowserType::FIREFOX, $config->browser);
         $this->assertEquals('nightly', $config->channel);
         $this->assertFalse($config->headless);