Normalize Playwright exceptions (#15)

smnandre · web-flow · commit d47cf2d1ac5b · 2025-09-06T18:19:30.000+02:00
diff --git a/src/Browser/Browser.php b/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);
diff --git a/src/Browser/BrowserBuilder.php b/src/Browser/BrowserBuilder.php
@@ -18,7 +18,7 @@
 /**
  * @author Simon André <smn.andre@gmail.com>
  */
-class BrowserBuilder
+final class BrowserBuilder
 {
     /**
      * @var array<string, mixed>
diff --git a/src/Browser/BrowserContext.php b/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;
         }
diff --git a/src/Browser/StorageState.php b/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));
         }
     }
 
diff --git a/src/Configuration/PlaywrightConfigBuilder.php b/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;
         }
 
diff --git a/src/Console/ConsoleMessage.php b/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;
         }
diff --git a/src/Exception/RuntimeException.php b/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
+{
+}
diff --git a/src/Frame/Frame.php b/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;
diff --git a/src/Locator/Locator.php b/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;
diff --git a/src/Network/Request.php b/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;
diff --git a/src/Network/Response.php b/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;
         }
diff --git a/src/Page/Page.php b/src/Page/Page.php
diff --git a/src/Support/Sanitizer.php b/src/Support/Sanitizer.php
diff --git a/src/Support/ScreenshotHelper.php b/src/Support/ScreenshotHelper.php
diff --git a/src/Testing/PlaywrightTestCaseTrait.php b/src/Testing/PlaywrightTestCaseTrait.php
diff --git a/src/Transport/TransportFactory.php b/src/Transport/TransportFactory.php

Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@`
`18`	`18`	`/**`
`19`	`19`	`* @author Simon André <smn.andre@gmail.com>`
`20`	`20`	`*/`
`21`		`-class BrowserBuilder`
	`21`	`+final class BrowserBuilder`
`22`	`22`	`{`
`23`	`23`	`/**`
`24`	`24`	`* @var array<string, mixed>`
Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,8 @@`
`12`	`12`
`13`	`13`	`use PlaywrightPHP\Configuration\PlaywrightConfig;`
`14`	`14`	`use PlaywrightPHP\Event\EventDispatcherInterface;`
	`15`	`+use PlaywrightPHP\Exception\ProtocolErrorException;`
	`16`	`+use PlaywrightPHP\Exception\TransportException;`
`15`	`17`	`use PlaywrightPHP\Network\NetworkThrottling;`
`16`	`18`	`use PlaywrightPHP\Network\Route;`
`17`	`19`	`use PlaywrightPHP\Page\Page;`
`@@ -60,10 +62,10 @@ public function dispatchEvent(string $eventName, array $params): void`
`60`	`62`	`{`
`61`	`63`	`if ('route' === $eventName) {`
`62`	`64`	`if (!is_string($params['routeId'])) {`
`63`		`- throw new \RuntimeException('Invalid routeId in route event');`
	`65`	`+ throw new ProtocolErrorException('Invalid routeId in route event', 0);`
`64`	`66`	`}`
`65`	`67`	`if (!is_array($params['request'])) {`
`66`		`- throw new \RuntimeException('Invalid request data in route event');`
	`68`	`+ throw new ProtocolErrorException('Invalid request data in route event', 0);`
`67`	`69`	`}`
`68`	`70`	`$route = new Route(`
`69`	`71`	`$this->transport,`
`@@ -126,11 +128,11 @@ public function newPage(array $options = []): PageInterface`
`126`	`128`
`127`	`129`	`if (isset($response['error'])) {`
`128`	`130`	`$errorMsg = is_string($response['error']) ? $response['error'] : 'Unknown transport error';`
`129`		`- throw new \RuntimeException('Transport error in newPage: '.$errorMsg);`
	`131`	`+ throw new TransportException('Transport error in newPage: '.$errorMsg);`
`130`	`132`	`}`
`131`	`133`
`132`	`134`	`if (!isset($response['pageId']) \|\| !is_string($response['pageId'])) {`
`133`		`- throw new \RuntimeException('No valid pageId returned from transport in newPage');`
	`135`	`+ throw new ProtocolErrorException('No valid pageId returned from transport in newPage', 0);`
`134`	`136`	`}`
`135`	`137`
`136`	`138`	`$page = new Page($this->transport, $this, $response['pageId'], $this->config);`
`@@ -147,7 +149,7 @@ public function clipboardText(): string`
`147`	`149`	`]);`
`148`	`150`
`149`	`151`	`if (!is_string($response['value'])) {`
`150`		`- throw new \RuntimeException('Invalid clipboard text response');`
	`152`	`+ throw new ProtocolErrorException('Invalid clipboard text response', 0);`
`151`	`153`	`}`
`152`	`154`
`153`	`155`	`return $response['value'];`
`@@ -210,7 +212,7 @@ public function cookies(?array $urls = null): array`
`210`	`212`	`]);`
`211`	`213`
`212`	`214`	`if (!is_array($response['cookies'])) {`
`213`		`- throw new \RuntimeException('Invalid cookies response');`
	`215`	`+ throw new ProtocolErrorException('Invalid cookies response', 0);`
`214`	`216`	`}`
`215`	`217`
`216`	`218`	`/** @phpstan-var array<array<string, mixed>> $cookies */`
`@@ -271,7 +273,7 @@ public function storageState(?string $path = null): array`
`271`	`273`	`]);`
`272`	`274`
`273`	`275`	`if (!is_array($response['storageState'])) {`
`274`		`- throw new \RuntimeException('Invalid storageState response');`
	`276`	`+ throw new ProtocolErrorException('Invalid storageState response', 0);`
`275`	`277`	`}`
`276`	`278`
`277`	`279`	`/** @phpstan-var array<string, mixed> $storageState */`
`@@ -420,13 +422,13 @@ public function disableNetworkThrottling(): void`
`420`	`422`	`private function validateTransportArray(mixed $data, string $context = ''): array`
`421`	`423`	`{`
`422`	`424`	`if (!is_array($data)) {`
`423`		`- throw new \RuntimeException("Invalid {$context} data in transport response");`
	`425`	`+ throw new ProtocolErrorException("Invalid {$context} data in transport response", 0);`
`424`	`426`	`}`
`425`	`427`
`426`	`428`	`$result = [];`
`427`	`429`	`foreach ($data as $key => $value) {`
`428`	`430`	`if (!is_string($key)) {`
`429`		`- throw new \RuntimeException("Invalid {$context} payload: non-string key in transport response");`
	`431`	`+ throw new ProtocolErrorException("Invalid {$context} payload: non-string key in transport response", 0);`
`430`	`432`	`}`
`431`	`433`	`$result[$key] = $value;`
`432`	`434`	`}`
Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,8 @@`
`10`	`10`
`11`	`11`	`namespace PlaywrightPHP\Browser;`
`12`	`12`
	`13`	`+use PlaywrightPHP\Exception\RuntimeException;`
	`14`	`+`
`13`	`15`	`/**`
`14`	`16`	`* Storage state container for cookies and localStorage data.`
`15`	`17`	`*`
`@@ -64,7 +66,7 @@ public static function fromFile(string $filePath): self`
`64`	`66`
`65`	`67`	`$content = \file_get_contents($filePath);`
`66`	`68`	`if (false === $content) {`
`67`		`- throw new \RuntimeException(\sprintf('Failed to read storage state file: %s', $filePath));`
	`69`	`+ throw new RuntimeException(\sprintf('Failed to read storage state file: %s', $filePath));`
`68`	`70`	`}`
`69`	`71`
`70`	`72`	`return self::fromJson($content);`
`@@ -111,12 +113,12 @@ public function saveToFile(string $filePath): void`
`111`	`113`	`{`
`112`	`114`	`$directory = \dirname($filePath);`
`113`	`115`	`if (!\is_dir($directory) && !\mkdir($directory, 0755, true) && !\is_dir($directory)) {`
`114`		`- throw new \RuntimeException(\sprintf('Failed to create directory: %s', $directory));`
	`116`	`+ throw new RuntimeException(\sprintf('Failed to create directory: %s', $directory));`
`115`	`117`	`}`
`116`	`118`
`117`	`119`	`$result = \file_put_contents($filePath, $this->toJson(JSON_PRETTY_PRINT));`
`118`	`120`	`if (false === $result) {`
`119`		`- throw new \RuntimeException(\sprintf('Failed to write storage state file: %s', $filePath));`
	`121`	`+ throw new RuntimeException(\sprintf('Failed to write storage state file: %s', $filePath));`
`120`	`122`	`}`
`121`	`123`	`}`
`122`	`124`
Original file line number	Diff line number	Diff line change
`@@ -265,16 +265,16 @@ public function build(): PlaywrightConfig`
`265`	`265`	`if ($this->slowMoMs < 0) {`
`266`	`266`	`throw new \InvalidArgumentException('slowMoMs must be >= 0');`
`267`	`267`	`}`
`268`		`- if (null !== $this->channel && '' === $this->channel) {`
	`268`	`+ if ('' === $this->channel) {`
`269`	`269`	`$this->channel = null;`
`270`	`270`	`}`
`271`		`- if (null !== $this->downloadsDir && '' === $this->downloadsDir) {`
	`271`	`+ if ('' === $this->downloadsDir) {`
`272`	`272`	`$this->downloadsDir = null;`
`273`	`273`	`}`
`274`		`- if (null !== $this->videosDir && '' === $this->videosDir) {`
	`274`	`+ if ('' === $this->videosDir) {`
`275`	`275`	`$this->videosDir = null;`
`276`	`276`	`}`
`277`		`- if ($this->tracingEnabled && null !== $this->traceDir && '' === $this->traceDir) {`
	`277`	`+ if ($this->tracingEnabled && '' === $this->traceDir) {`
`278`	`278`	`$this->traceDir = null;`
`279`	`279`	`}`
`280`	`280`