pestphp · nunomaduro · Jan 7, 2026 · Jan 7, 2026
diff --git a/src/Configuration.php b/src/Configuration.php
@@ -95,6 +95,16 @@ public function userAgent(string $userAgent): self
         return $this;
     }
 
+    /**
+     * Sets the host for the server.
+     */
+    public function withHost(string $host): self
+    {
+        Playwright::setHost($host);
+
+        return $this;
+    }
+
     /**
      * Enables debug mode for assertions.
      */

diff --git a/src/Playwright/Playwright.php b/src/Playwright/Playwright.php
@@ -54,6 +54,11 @@ final class Playwright
      */
     private static ?string $userAgent = null;
 
+    /**
+     * The default host.
+     */
+    private static ?string $host = null;
+
     /**
      * Get a browser factory for the given browser type.
      */
@@ -134,6 +139,22 @@ public static function setUserAgent(string $userAgent): void
         self::$userAgent = $userAgent;
     }
 
+    /**
+     * Set the default host.
+     */
+    public static function setHost(?string $host): void
+    {
+        self::$host = $host;
+    }
+
+    /**
+     * Get the default host.
+     */
+    public static function host(): ?string
+    {
+        return self::$host;
+    }
+
     /**
      * Get the default color scheme.
      */

diff --git a/src/ServerManager.php b/src/ServerManager.php
@@ -8,6 +8,7 @@
 use Pest\Browser\Contracts\PlaywrightServer;
 use Pest\Browser\Drivers\LaravelHttpServer;
 use Pest\Browser\Drivers\NullableHttpServer;
+use Pest\Browser\Playwright\Playwright;
 use Pest\Browser\Playwright\Servers\AlreadyStartedPlaywrightServer;
 use Pest\Browser\Playwright\Servers\PlaywrightNpmServer;
 use Pest\Browser\Support\PackageJsonDirectory;
@@ -59,17 +60,18 @@ public function playwright(): PlaywrightServer
         }
 
         $port = Port::find();
+        $host = Playwright::host() ?? self::DEFAULT_HOST;
 
         $this->playwright ??= PlaywrightNpmServer::create(
             PackageJsonDirectory::find(),
             '.'.DIRECTORY_SEPARATOR.'node_modules'.DIRECTORY_SEPARATOR.'.bin'.DIRECTORY_SEPARATOR.'playwright run-server --host %s --port %d --mode launchServer',
-            self::DEFAULT_HOST,
+            $host,
             $port,
             'Listening on',
         );
 
         AlreadyStartedPlaywrightServer::persist(
-            self::DEFAULT_HOST,
+            $host,
             $port,
         );
 
@@ -83,7 +85,7 @@ public function http(): HttpServer
     {
         return $this->http ??= match (function_exists('app_path')) {
             true => new LaravelHttpServer(
-                self::DEFAULT_HOST,
+                Playwright::host() ?? self::DEFAULT_HOST,
                 Port::find(),
             ),
             default => new NullableHttpServer(),

diff --git a/tests/Browser/Visit/SubdomainTest.php b/tests/Browser/Visit/SubdomainTest.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Support\Facades\Route;
+
+it('can visit subdomain routes with browser testing', function (): void {
+    Route::domain('app.localhost')->group(function (): void {
+        Route::get('/', fn (): string => '
+            <html>
+            <head><title>App Subdomain</title></head>
+            <body>
+                <h1>Welcome to App Subdomain</h1>
+                <div id="content">This is the app subdomain content</div>
+            </body>
+            </html>
+        ');
+    });
+
+    pest()->browser()->withHost('app.localhost');
+
+    visit('/')
+        ->assertSee('Welcome to App Subdomain')
+        ->assertSeeIn('#content', 'This is the app subdomain content')
+        ->assertTitle('App Subdomain');
+});
+
+it('works with Laravel Sail style subdomains', function (): void {
+    // Simulate Laravel Sail subdomain routing pattern
+    Route::domain('{subdomain}.localhost')->group(function (): void {
+        Route::get('/api/health', fn (): array => [
+            'status' => 'ok',
+            'subdomain' => request()->route('subdomain'),
+            'host' => request()->getHost(),
+        ]);
+    });
+
+    pest()->browser()->withHost('api.localhost');
+
+    visit('/api/health')
+        ->assertSee('"status":"ok"')
+        ->assertSee('"subdomain":"api"')
+        ->assertSee('"host":"api.localhost"');
+});
diff --git a/tests/Unit/Configuration/HostConfigurationTest.php b/tests/Unit/Configuration/HostConfigurationTest.php
@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+use Pest\Browser\Configuration;
+use Pest\Browser\Playwright\Playwright;
+
+beforeEach(function (): void {
+    // Reset Playwright state before each test
+    Playwright::setHost(null);
+});
+
+it('can set host via configuration', function (): void {
+    $config = new Configuration();
+
+    $result = $config->withHost('tenant.localhost');
+
+    expect($result)->toBeInstanceOf(Configuration::class);
+    expect(Playwright::host())->toBe('tenant.localhost');
+});
+
+it('follows fluent interface pattern', function (): void {
+    $config = new Configuration();
+
+    $result = $config
+        ->withHost('app.localhost')
+        ->userAgent('Test Agent')
+        ->timeout(10000);
+
+    expect($result)->toBeInstanceOf(Configuration::class);
+    expect(Playwright::host())->toBe('app.localhost');
+});
+
+it('stores host in Playwright global state', function (): void {
+    expect(Playwright::host())->toBeNull();
+
+    Playwright::setHost('custom.localhost');
+
+    expect(Playwright::host())->toBe('custom.localhost');
+});
+
+it('can override host multiple times', function (): void {
+    Playwright::setHost('first.localhost');
+    expect(Playwright::host())->toBe('first.localhost');
+
+    Playwright::setHost('second.localhost');
+    expect(Playwright::host())->toBe('second.localhost');
+
+    Playwright::setHost('final.localhost');
+    expect(Playwright::host())->toBe('final.localhost');
+});
+
+it('handles various host formats', function (): void {
+    $hosts = [
+        'localhost',
+        'app.localhost',
+        'subdomain.domain.tld',
+        '192.168.1.100',
+        'custom-host.test',
+    ];
+
+    foreach ($hosts as $host) {
+        Playwright::setHost($host);
+        expect(Playwright::host())->toBe($host);
+    }
+});