Normalize Playwright exceptions

src/Browser/Browser.php

@@ -11,6 +11,8 @@
 namespace PlaywrightPHP\Browser;
 
 use PlaywrightPHP\Configuration\PlaywrightConfig;
+use PlaywrightPHP\Exception\ProtocolErrorException;
+use PlaywrightPHP\Exception\RuntimeException;
 use PlaywrightPHP\Page\PageInterface;
 use PlaywrightPHP\Transport\TransportInterface;
 
@@ -42,7 +44,7 @@ public function __construct(
     public function context(): BrowserContextInterface
     {
         if (null === $this->defaultContext) {
-            throw new \RuntimeException('Default context is not available');
+            throw new RuntimeException('Default context is not available');
         }
 
         return $this->defaultContext;
@@ -60,7 +62,7 @@ public function newContext(array $options = []): BrowserContextInterface
         ]);
 
         if (!is_string($response['contextId'])) {
-            throw new \RuntimeException('Invalid contextId returned from transport');
+            throw new ProtocolErrorException('Invalid contextId returned from transport', 0);
         }
 
         $context = new BrowserContext($this->transport, $response['contextId'], $this->config);

src/Browser/BrowserBuilder.php

@@ -18,7 +18,7 @@
 /**
  * @author Simon André <smn.andre@gmail.com>
  */
-class BrowserBuilder
+final class BrowserBuilder
 {
     /**
      * @var array<string, mixed>

src/Browser/BrowserContext.php

@@ -12,6 +12,8 @@
 
 use PlaywrightPHP\Configuration\PlaywrightConfig;
 use PlaywrightPHP\Event\EventDispatcherInterface;
+use PlaywrightPHP\Exception\ProtocolErrorException;
+use PlaywrightPHP\Exception\TransportException;
 use PlaywrightPHP\Network\NetworkThrottling;
 use PlaywrightPHP\Network\Route;
 use PlaywrightPHP\Page\Page;
@@ -60,10 +62,10 @@ public function dispatchEvent(string $eventName, array $params): void
     {
         if ('route' === $eventName) {
             if (!is_string($params['routeId'])) {
-                throw new \RuntimeException('Invalid routeId in route event');
+                throw new ProtocolErrorException('Invalid routeId in route event', 0);
             }
             if (!is_array($params['request'])) {
-                throw new \RuntimeException('Invalid request data in route event');
+                throw new ProtocolErrorException('Invalid request data in route event', 0);
             }
             $route = new Route(
                 $this->transport,
@@ -126,11 +128,11 @@ public function newPage(array $options = []): PageInterface
 
         if (isset($response['error'])) {
             $errorMsg = is_string($response['error']) ? $response['error'] : 'Unknown transport error';
-            throw new \RuntimeException('Transport error in newPage: '.$errorMsg);
+            throw new TransportException('Transport error in newPage: '.$errorMsg);
         }
 
         if (!isset($response['pageId']) || !is_string($response['pageId'])) {
-            throw new \RuntimeException('No valid pageId returned from transport in newPage');
+            throw new ProtocolErrorException('No valid pageId returned from transport in newPage', 0);
         }
 
         $page = new Page($this->transport, $this, $response['pageId'], $this->config);
@@ -147,7 +149,7 @@ public function clipboardText(): string
         ]);
 
         if (!is_string($response['value'])) {
-            throw new \RuntimeException('Invalid clipboard text response');
+            throw new ProtocolErrorException('Invalid clipboard text response', 0);
         }
 
         return $response['value'];
@@ -210,7 +212,7 @@ public function cookies(?array $urls = null): array
         ]);
 
         if (!is_array($response['cookies'])) {
-            throw new \RuntimeException('Invalid cookies response');
+            throw new ProtocolErrorException('Invalid cookies response', 0);
         }
 
         /** @phpstan-var array<array<string, mixed>> $cookies */
@@ -271,7 +273,7 @@ public function storageState(?string $path = null): array
         ]);
 
         if (!is_array($response['storageState'])) {
-            throw new \RuntimeException('Invalid storageState response');
+            throw new ProtocolErrorException('Invalid storageState response', 0);
         }
 
         /** @phpstan-var array<string, mixed> $storageState */
@@ -420,13 +422,13 @@ public function disableNetworkThrottling(): void
     private function validateTransportArray(mixed $data, string $context = ''): array
     {
         if (!is_array($data)) {
-            throw new \RuntimeException("Invalid {$context} data in transport response");
+            throw new ProtocolErrorException("Invalid {$context} data in transport response", 0);
         }
 
         $result = [];
         foreach ($data as $key => $value) {
             if (!is_string($key)) {
-                throw new \RuntimeException("Invalid {$context} payload: non-string key in transport response");
+                throw new ProtocolErrorException("Invalid {$context} payload: non-string key in transport response", 0);
             }
             $result[$key] = $value;
         }

src/Browser/StorageState.php

@@ -10,6 +10,8 @@
 
 namespace PlaywrightPHP\Browser;
 
+use PlaywrightPHP\Exception\RuntimeException;
+
 /**
  * Storage state container for cookies and localStorage data.
  *
@@ -64,7 +66,7 @@ public static function fromFile(string $filePath): self
 
         $content = \file_get_contents($filePath);
         if (false === $content) {
-            throw new \RuntimeException(\sprintf('Failed to read storage state file: %s', $filePath));
+            throw new RuntimeException(\sprintf('Failed to read storage state file: %s', $filePath));
         }
 
         return self::fromJson($content);
@@ -111,12 +113,12 @@ public function saveToFile(string $filePath): void
     {
         $directory = \dirname($filePath);
         if (!\is_dir($directory) && !\mkdir($directory, 0755, true) && !\is_dir($directory)) {
-            throw new \RuntimeException(\sprintf('Failed to create directory: %s', $directory));
+            throw new RuntimeException(\sprintf('Failed to create directory: %s', $directory));
         }
 
         $result = \file_put_contents($filePath, $this->toJson(JSON_PRETTY_PRINT));
         if (false === $result) {
-            throw new \RuntimeException(\sprintf('Failed to write storage state file: %s', $filePath));
+            throw new RuntimeException(\sprintf('Failed to write storage state file: %s', $filePath));
         }
     }
 

src/Configuration/PlaywrightConfigBuilder.php

@@ -265,16 +265,16 @@ public function build(): PlaywrightConfig
         if ($this->slowMoMs < 0) {
             throw new \InvalidArgumentException('slowMoMs must be >= 0');
         }
-        if (null !== $this->channel && '' === $this->channel) {
+        if ('' === $this->channel) {
             $this->channel = null;
         }
-        if (null !== $this->downloadsDir && '' === $this->downloadsDir) {
+        if ('' === $this->downloadsDir) {
             $this->downloadsDir = null;
         }
-        if (null !== $this->videosDir && '' === $this->videosDir) {
+        if ('' === $this->videosDir) {
             $this->videosDir = null;
         }
-        if ($this->tracingEnabled && null !== $this->traceDir && '' === $this->traceDir) {
+        if ($this->tracingEnabled && '' === $this->traceDir) {
             $this->traceDir = null;
         }
 

src/Console/ConsoleMessage.php

@@ -10,6 +10,8 @@
 
 namespace PlaywrightPHP\Console;
 
+use PlaywrightPHP\Exception\ProtocolErrorException;
+
 /**
  * @author Simon André <smn.andre@gmail.com>
  */
@@ -32,7 +34,7 @@ public function type(): string
     {
         $type = $this->data['type'];
         if (!is_string($type)) {
-            throw new \RuntimeException('Invalid console message type');
+            throw new ProtocolErrorException('Invalid console message type', 0);
         }
 
         return $type;
@@ -42,7 +44,7 @@ public function text(): string
     {
         $text = $this->data['text'];
         if (!is_string($text)) {
-            throw new \RuntimeException('Invalid console message text');
+            throw new ProtocolErrorException('Invalid console message text', 0);
         }
 
         return $text;
@@ -55,7 +57,7 @@ public function args(): array
     {
         $args = $this->data['args'];
         if (!is_array($args)) {
-            throw new \RuntimeException('Invalid console message args');
+            throw new ProtocolErrorException('Invalid console message args', 0);
         }
 
         return $args;
@@ -68,13 +70,13 @@ public function location(): array
     {
         $location = $this->data['location'];
         if (!is_array($location)) {
-            throw new \RuntimeException('Invalid console message location');
+            throw new ProtocolErrorException('Invalid console message location', 0);
         }
 
         $result = [];
         foreach ($location as $key => $value) {
             if (!is_string($key)) {
-                throw new \RuntimeException('Invalid console message location: non-string key');
+                throw new ProtocolErrorException('Invalid console message location: non-string key', 0);
             }
             $result[$key] = $value;
         }

src/Exception/RuntimeException.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the playwright-php/playwright package.
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace PlaywrightPHP\Exception;
+
+/**
+ * Thrown when a runtime error occurs that is specific to Playwright operations.
+ *
+ * @author Simon André <smn.andre@gmail.com>
+ */
+class RuntimeException extends PlaywrightException
+{
+}

src/Frame/Frame.php

@@ -11,6 +11,7 @@
 namespace PlaywrightPHP\Frame;
 
 use PlaywrightPHP\Exception\PlaywrightException;
+use PlaywrightPHP\Exception\ProtocolErrorException;
 use PlaywrightPHP\Locator\Locator;
 use PlaywrightPHP\Locator\LocatorInterface;
 use PlaywrightPHP\Transport\TransportInterface;
@@ -75,7 +76,7 @@ public function name(): string
         $response = $this->sendCommand('frame.name');
         $value = $response['value'] ?? null;
         if (!is_string($value)) {
-            throw new \RuntimeException('Invalid frame.name response');
+            throw new ProtocolErrorException('Invalid frame.name response', 0);
         }
 
         return $value;
@@ -86,7 +87,7 @@ public function url(): string
         $response = $this->sendCommand('frame.url');
         $value = $response['value'] ?? null;
         if (!is_string($value)) {
-            throw new \RuntimeException('Invalid frame.url response');
+            throw new ProtocolErrorException('Invalid frame.url response', 0);
         }
 
         return $value;

src/Locator/Locator.php

@@ -11,6 +11,7 @@
 namespace PlaywrightPHP\Locator;
 
 use PlaywrightPHP\Exception\PlaywrightException;
+use PlaywrightPHP\Exception\ProtocolErrorException;
 use PlaywrightPHP\Exception\TimeoutException;
 use PlaywrightPHP\Frame\FrameLocator;
 use PlaywrightPHP\Frame\FrameLocatorInterface;
@@ -138,7 +139,7 @@ public function innerHTML(): string
         $response = $this->sendCommand('locator.innerHTML');
         $value = $response['value'];
         if (!is_string($value)) {
-            throw new \RuntimeException('Invalid innerHTML response');
+            throw new ProtocolErrorException('Invalid innerHTML response', 0);
         }
 
         return $value;
@@ -149,7 +150,7 @@ public function innerText(): string
         $response = $this->sendCommand('locator.innerText');
         $value = $response['value'];
         if (!is_string($value)) {
-            throw new \RuntimeException('Invalid innerText response');
+            throw new ProtocolErrorException('Invalid innerText response', 0);
         }
 
         return $value;
@@ -160,7 +161,7 @@ public function inputValue(): string
         $response = $this->sendCommand('locator.inputValue');
         $value = $response['value'];
         if (!is_string($value)) {
-            throw new \RuntimeException('Invalid inputValue response');
+            throw new ProtocolErrorException('Invalid inputValue response', 0);
         }
 
         return $value;

src/Network/Request.php

@@ -10,6 +10,8 @@
 
 namespace PlaywrightPHP\Network;
 
+use PlaywrightPHP\Exception\ProtocolErrorException;
+
 /**
  * @author Simon André <smn.andre@gmail.com>
  */
@@ -27,7 +29,7 @@ public function url(): string
     {
         $url = $this->data['url'];
         if (!is_string($url)) {
-            throw new \RuntimeException('Invalid URL in request data');
+            throw new ProtocolErrorException('Invalid URL in request data', 0);
         }
 
         return $url;
@@ -37,7 +39,7 @@ public function method(): string
     {
         $method = $this->data['method'];
         if (!is_string($method)) {
-            throw new \RuntimeException('Invalid method in request data');
+            throw new ProtocolErrorException('Invalid method in request data', 0);
         }
 
         return $method;
@@ -96,7 +98,7 @@ public function resourceType(): string
     {
         $resourceType = $this->data['resourceType'];
         if (!is_string($resourceType)) {
-            throw new \RuntimeException('Invalid resourceType in request data');
+            throw new ProtocolErrorException('Invalid resourceType in request data', 0);
         }
 
         return $resourceType;

src/Network/Response.php

@@ -10,6 +10,7 @@
 
 namespace PlaywrightPHP\Network;
 
+use PlaywrightPHP\Exception\ProtocolErrorException;
 use PlaywrightPHP\Transport\TransportInterface;
 
 /**
@@ -35,7 +36,7 @@ public function url(): string
     {
         $url = $this->data['url'];
         if (!is_string($url)) {
-            throw new \RuntimeException('Invalid URL in response data');
+            throw new ProtocolErrorException('Invalid URL in response data', 0);
         }
 
         return $url;
@@ -45,7 +46,7 @@ public function status(): int
     {
         $status = $this->data['status'];
         if (!is_int($status)) {
-            throw new \RuntimeException('Invalid status in response data');
+            throw new ProtocolErrorException('Invalid status in response data', 0);
         }
 
         return $status;
@@ -55,7 +56,7 @@ public function statusText(): string
     {
         $statusText = $this->data['statusText'];
         if (!is_string($statusText)) {
-            throw new \RuntimeException('Invalid statusText in response data');
+            throw new ProtocolErrorException('Invalid statusText in response data', 0);
         }
 
         return $statusText;
@@ -94,11 +95,11 @@ public function body(): string
             ]);
             $binary = $response['binary'];
             if (!is_string($binary)) {
-                throw new \RuntimeException('Invalid binary response data');
+                throw new ProtocolErrorException('Invalid binary response data', 0);
             }
             $decoded = base64_decode($binary);
             if (false === $decoded) {
-                throw new \RuntimeException('Failed to decode binary response data');
+                throw new ProtocolErrorException('Failed to decode binary response data', 0);
             }
             $this->body = $decoded;
         }