feat: support system-installed browsers via channel and executable path

src/Configuration.php

@@ -45,6 +45,27 @@ public function inSafari(): self
         return $this;
     }
 
+    /**
+     * Uses a system-installed branded browser via its Playwright channel,
+     * e.g. "chrome", "chrome-beta", "msedge" or "msedge-dev".
+     */
+    public function usingChannel(string $channel): self
+    {
+        Playwright::setChannel($channel);
+
+        return $this;
+    }
+
+    /**
+     * Uses the browser executable at the given path, e.g. "/usr/bin/firefox".
+     */
+    public function usingExecutablePath(string $executablePath): self
+    {
+        Playwright::setExecutablePath($executablePath);
+
+        return $this;
+    }
+
     /**
      * Sets the theme to light mode.
      */

src/Playwright/Client.php

@@ -51,11 +51,13 @@ public function connectTo(string $url): void
         if (! $this->websocketConnection instanceof WebsocketConnection) {
             $browser = Playwright::defaultBrowserType()->toPlaywrightName();
 
-            $launchOptions = json_encode([
+            $launchOptions = json_encode(array_filter([
                 'headless' => Playwright::isHeadless(),
                 'ignoreHTTPSErrors' => true,
                 'bypassCSP' => true,
-            ]);
+                'channel' => Playwright::channel(),
+                'executablePath' => Playwright::executablePath(),
+            ], fn (mixed $value): bool => $value !== null));
 
             $this->websocketConnection = connect(
                 "ws://$url?browser=$browser&launch-options=$launchOptions",

src/Playwright/Playwright.php

@@ -59,6 +59,16 @@ final class Playwright
      */
     private static ?string $host = null;
 
+    /**
+     * The browser channel to use, e.g. "chrome" or "msedge".
+     */
+    private static ?string $channel = null;
+
+    /**
+     * The path to a browser executable to use.
+     */
+    private static ?string $executablePath = null;
+
     /**
      * Get a browser factory for the given browser type.
      */
@@ -155,6 +165,38 @@ public static function host(): ?string
         return self::$host;
     }
 
+    /**
+     * Set the browser channel to use.
+     */
+    public static function setChannel(?string $channel): void
+    {
+        self::$channel = $channel;
+    }
+
+    /**
+     * Get the browser channel to use.
+     */
+    public static function channel(): ?string
+    {
+        return self::$channel;
+    }
+
+    /**
+     * Set the browser executable path to use.
+     */
+    public static function setExecutablePath(?string $executablePath): void
+    {
+        self::$executablePath = $executablePath;
+    }
+
+    /**
+     * Get the browser executable path to use.
+     */
+    public static function executablePath(): ?string
+    {
+        return self::$executablePath;
+    }
+
     /**
      * Get the default color scheme.
      */

src/ServerManager.php

@@ -62,9 +62,15 @@ public function playwright(): PlaywrightServer
         $port = Port::find();
         $host = Playwright::host() ?? self::DEFAULT_HOST;
 
+        $command = '.'.DIRECTORY_SEPARATOR.'node_modules'.DIRECTORY_SEPARATOR.'.bin'.DIRECTORY_SEPARATOR.'playwright run-server --host %s --port %d --mode launchServer';
+
+        if (Playwright::executablePath() !== null) {
+            $command .= ' --unsafe';
+        }
+
         $this->playwright ??= PlaywrightNpmServer::create(
             PackageJsonDirectory::find(),
-            '.'.DIRECTORY_SEPARATOR.'node_modules'.DIRECTORY_SEPARATOR.'.bin'.DIRECTORY_SEPARATOR.'playwright run-server --host %s --port %d --mode launchServer',
+            $command,
             $host,
             $port,
             'Listening on',

tests/Unit/Configuration/SystemBrowserConfigurationTest.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+use Pest\Browser\Configuration;
+use Pest\Browser\Playwright\Playwright;
+
+beforeEach(function (): void {
+    // Reset Playwright state before each test
+    Playwright::setChannel(null);
+    Playwright::setExecutablePath(null);
+});
+
+it('can set a system browser channel via configuration', function (): void {
+    $config = new Configuration();
+
+    $result = $config->usingChannel('chrome');
+
+    expect($result)->toBeInstanceOf(Configuration::class);
+    expect(Playwright::channel())->toBe('chrome');
+});
+
+it('can set a browser executable path via configuration', function (): void {
+    $config = new Configuration();
+
+    $result = $config->usingExecutablePath('/usr/bin/firefox');
+
+    expect($result)->toBeInstanceOf(Configuration::class);
+    expect(Playwright::executablePath())->toBe('/usr/bin/firefox');
+});
+
+it('defaults channel and executable path to null', function (): void {
+    expect(Playwright::channel())->toBeNull();
+    expect(Playwright::executablePath())->toBeNull();
+});
+
+it('supports fluent chaining with other configuration options', function (): void {
+    $config = new Configuration();
+
+    $result = $config
+        ->usingChannel('msedge')
+        ->usingExecutablePath('/usr/bin/msedge')
+        ->headed()
+        ->timeout(10000);
+
+    expect($result)->toBeInstanceOf(Configuration::class);
+    expect(Playwright::channel())->toBe('msedge');
+    expect(Playwright::executablePath())->toBe('/usr/bin/msedge');
+});
+
+it('can override channel and executable path multiple times', function (): void {
+    Playwright::setChannel('chrome');
+    expect(Playwright::channel())->toBe('chrome');
+
+    Playwright::setChannel('msedge');
+    expect(Playwright::channel())->toBe('msedge');
+
+    Playwright::setExecutablePath('/usr/bin/firefox');
+    expect(Playwright::executablePath())->toBe('/usr/bin/firefox');
+
+    Playwright::setExecutablePath(null);
+    expect(Playwright::executablePath())->toBeNull();
+});