Add Browser bind and unbind

bin/lib/handlers.js

@@ -22,6 +22,13 @@ const evaluateHandleOnTarget = async (target, { expression, arg }) => {
 
 class ContextHandler extends BaseHandler {
   async handle(command, method) {
+    // Closing a context drops it from the registry, and closing its browser drops it
+    // too, so an id we no longer know about belongs to a context that is closed.
+    if (method === 'isClosed') {
+      const known = this.contexts.get(command.contextId)?.context;
+      return this.wrapResult({ value: known ? known.isClosed() : true });
+    }
+
     const context = this.validateResource(this.contexts, command.contextId, 'Context')?.context;
     if (!context._initScriptPromise) context._initScriptPromise = Promise.resolve();
 

bin/playwright-server.js

@@ -105,6 +105,8 @@ class PlaywrightServer extends BaseHandler {
       connect: () => this.connect(command),
       connectOverCDP: () => this.connectOverCDP(command),
       newContext: () => this.newContext(command),
+      bind: () => this.bindBrowser(command),
+      unbind: () => this.unbindBrowser(command),
       close: () => this.closeBrowser(command),
       exit: () => this.exit(),
       launchServer: () => this.launchServer(command)
@@ -277,6 +279,17 @@ class PlaywrightServer extends BaseHandler {
     return { contextId };
   }
 
+  async bindBrowser(command) {
+    const browser = this.validateResource(this.browsers, command.browserId, 'Browser');
+    const { endpoint } = await browser.bind(command.title, command.options || {});
+    return { endpoint };
+  }
+
+  async unbindBrowser(command) {
+    const browser = this.validateResource(this.browsers, command.browserId, 'Browser');
+    await browser.unbind();
+  }
+
   async closeBrowser(command) {
     const browser = this.browsers.get(command.browserId);
     if (!browser) return;

src/Browser/Browser.php

@@ -102,4 +102,32 @@ public function version(): string
     {
         return $this->version;
     }
+
+    /**
+     * @param array{host?: string, port?: int, workspaceDir?: string, metadata?: array<string, mixed>} $options
+     */
+    public function bind(string $title, array $options = []): string
+    {
+        $response = $this->transport->send([
+            'action' => 'bind',
+            'browserId' => $this->browserId,
+            'title' => $title,
+            'options' => $options,
+        ]);
+
+        $endpoint = $response['endpoint'] ?? null;
+        if (!is_string($endpoint)) {
+            throw new ProtocolErrorException('Invalid endpoint returned from transport', 0);
+        }
+
+        return $endpoint;
+    }
+
+    public function unbind(): void
+    {
+        $this->transport->send([
+            'action' => 'unbind',
+            'browserId' => $this->browserId,
+        ]);
+    }
 }

src/Browser/BrowserContext.php

@@ -241,6 +241,21 @@ public function close(): void
         ]);
     }
 
+    public function isClosed(): bool
+    {
+        $response = $this->transport->send([
+            'action' => 'context.isClosed',
+            'contextId' => $this->contextId,
+        ]);
+
+        $value = $response['value'] ?? null;
+        if (!is_bool($value)) {
+            throw new ProtocolErrorException('Invalid isClosed response', 0);
+        }
+
+        return $value;
+    }
+
     private function saveAutoTrace(): void
     {
         $dir = $this->config->traceDir ?? getcwd().'/traces';

src/Browser/BrowserContextInterface.php

@@ -71,6 +71,11 @@ public function clearPermissions(): void;
 
     public function close(): void;
 
+    /**
+     * Whether the context is closed, including when its browser was closed instead.
+     */
+    public function isClosed(): bool;
+
     /**
      * @param array<string>|null $urls
      *

src/Browser/BrowserInterface.php

@@ -45,4 +45,20 @@ public function browserType(): BrowserType;
     public function isConnected(): bool;
 
     public function version(): string;
+
+    /**
+     * Exposes this browser so other Playwright clients can connect to it and drive it.
+     *
+     * Binding twice without an intervening unbind() is an error.
+     *
+     * @param array{host?: string, port?: int, workspaceDir?: string, metadata?: array<string, mixed>} $options
+     *
+     * @return string the endpoint to connect to: a local socket path, or a ws:// URL when host or port is given
+     */
+    public function bind(string $title, array $options = []): string;
+
+    /**
+     * Tears down the server started by bind(); does nothing when the browser is not bound.
+     */
+    public function unbind(): void;
 }

tests/Integration/Browser/BrowserContextTest.php

@@ -60,6 +60,18 @@ public function itCreatesANewPageInContext(): void
         $page->close();
     }
 
+    #[Test]
+    public function itReportsWhetherItIsClosed(): void
+    {
+        $context = $this->browser->newContext();
+
+        $this->assertFalse($context->isClosed());
+
+        $context->close();
+
+        $this->assertTrue($context->isClosed());
+    }
+
     #[Test]
     public function itManagesCookies(): void
     {

tests/Integration/Browser/BrowserTest.php

@@ -100,4 +100,50 @@ public function itsContextsPointBackToIt(): void
 
         $context->close();
     }
+
+    #[Test]
+    public function itBindsTheBrowserToALocalSocket(): void
+    {
+        $endpoint = $this->browser->bind('playwright-php-socket');
+
+        try {
+            $this->assertNotEmpty($endpoint);
+        } finally {
+            $this->browser->unbind();
+        }
+    }
+
+    #[Test]
+    public function itBindsTheBrowserToAWebSocketWhenAPortIsGiven(): void
+    {
+        $endpoint = $this->browser->bind('playwright-php-ws', ['host' => '127.0.0.1', 'port' => 0]);
+
+        try {
+            $this->assertStringStartsWith('ws://127.0.0.1:', $endpoint);
+        } finally {
+            $this->browser->unbind();
+        }
+    }
+
+    #[Test]
+    public function itUnbindsABrowserThatWasNeverBound(): void
+    {
+        $this->browser->unbind();
+
+        $this->assertTrue($this->browser->isConnected());
+    }
+
+    #[Test]
+    public function itReportsItsContextsAsClosedOnceTheBrowserIsClosed(): void
+    {
+        // A browser of its own: closing the shared one would force every later test to relaunch it.
+        $browser = $this->playwright->chromium()->launch();
+        $context = $browser->newContext();
+
+        $this->assertFalse($context->isClosed());
+
+        $browser->close();
+
+        $this->assertTrue($context->isClosed());
+    }
 }

tests/Unit/Browser/BrowserContextTest.php

@@ -21,6 +21,7 @@
 use Playwright\Browser\StorageState;
 use Playwright\Configuration\PlaywrightConfig;
 use Playwright\Credentials\CredentialsInterface;
+use Playwright\Exception\ProtocolErrorException;
 use Playwright\Network\NetworkThrottling;
 use Playwright\Page\PageInterface;
 use Playwright\Tracing\TracingInterface;
@@ -111,6 +112,41 @@ public function testClose(): void
         $this->context->close();
     }
 
+    public function testIsClosed(): void
+    {
+        $this->mockTransport
+            ->expects($this->once())
+            ->method('send')
+            ->with([
+                'action' => 'context.isClosed',
+                'contextId' => 'context_1',
+            ])
+            ->willReturn(['value' => true]);
+
+        $this->assertTrue($this->context->isClosed());
+    }
+
+    public function testIsClosedReturnsFalseForAnOpenContext(): void
+    {
+        $this->mockTransport
+            ->method('send')
+            ->willReturn(['value' => false]);
+
+        $this->assertFalse($this->context->isClosed());
+    }
+
+    public function testIsClosedThrowsOnANonBooleanResponse(): void
+    {
+        $this->mockTransport
+            ->method('send')
+            ->willReturn(['success' => true]);
+
+        $this->expectException(ProtocolErrorException::class);
+        $this->expectExceptionMessage('Invalid isClosed response');
+
+        $this->context->isClosed();
+    }
+
     public function testAddCookies(): void
     {
         $cookies = [

tests/Unit/Browser/BrowserTest.php

@@ -19,6 +19,7 @@
 use Playwright\Browser\Browser;
 use Playwright\Browser\BrowserType;
 use Playwright\Configuration\PlaywrightConfig;
+use Playwright\Exception\ProtocolErrorException;
 use Playwright\Transport\TransportInterface;
 
 #[CoversClass(Browser::class)]
@@ -38,6 +39,55 @@ public function testBrowserTypeDefaultsToChromium(): void
         $this->assertSame(BrowserType::CHROMIUM, $browser->browserType());
     }
 
+    public function testBindSendsTheTitleAndReturnsTheEndpoint(): void
+    {
+        $transport = $this->createMock(TransportInterface::class);
+        $transport
+            ->expects($this->once())
+            ->method('send')
+            ->with([
+                'action' => 'bind',
+                'browserId' => 'b',
+                'title' => 'my-browser',
+                'options' => ['port' => 0],
+            ])
+            ->willReturn(['endpoint' => 'ws://127.0.0.1:4242/abc']);
+
+        $browser = new Browser($transport, 'b', 'ctx_default', '1.0', new PlaywrightConfig());
+
+        $this->assertSame('ws://127.0.0.1:4242/abc', $browser->bind('my-browser', ['port' => 0]));
+    }
+
+    public function testBindThrowsWhenNoEndpointComesBack(): void
+    {
+        $transport = $this->createMock(TransportInterface::class);
+        $transport->method('send')->willReturn(['success' => true]);
+
+        $browser = new Browser($transport, 'b', 'ctx_default', '1.0', new PlaywrightConfig());
+
+        $this->expectException(ProtocolErrorException::class);
+        $this->expectExceptionMessage('Invalid endpoint returned from transport');
+
+        $browser->bind('my-browser');
+    }
+
+    public function testUnbindSendsTheBrowserId(): void
+    {
+        $transport = $this->createMock(TransportInterface::class);
+        $transport
+            ->expects($this->once())
+            ->method('send')
+            ->with([
+                'action' => 'unbind',
+                'browserId' => 'b',
+            ])
+            ->willReturn([]);
+
+        $browser = new Browser($transport, 'b', 'ctx_default', '1.0', new PlaywrightConfig());
+
+        $browser->unbind();
+    }
+
     private function browser(BrowserType $type): Browser
     {
         return new Browser($this->transport(), 'b', 'ctx_default', '1.0', new PlaywrightConfig(), $type);