Merge pull request php-webdriver#1027 from OndraM/feature/exceptions-tree

Refactor internal exceptions

Author: OndraM

.php-cs-fixer.dist.php

@@ -26,7 +26,6 @@
         'implode_call' => true,
         'is_null' => true,
         'lambda_not_used_import' => true,
-        'linebreak_after_opening_tag' => true,
         'list_syntax' => true,
         'lowercase_cast' => true,
         'lowercase_static_reference' => true,

CHANGELOG.md

@@ -2,9 +2,14 @@
 This project versioning adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
+### Added
+- `PhpWebDriverExceptionInterface` as a common interface to identify all exceptions thrown in php-webdriver
 
 ### Changed
 - Require PHP ^7.3.
+- Throw `UnexpectedResponseException` instead of `UnknownErrorException` in `findElement()` and `findElements()` methods.
+- Throw custom php-webdriver exceptions instead of native PHP SPL exceptions.
+- Do not mix internal non-W3C WebDriver exceptions, separate them into own namespace.
 
 ## 1.13.0 - 2022-10-03
 ### Added

lib/AbstractWebDriverCheckboxOrRadio.php

@@ -2,9 +2,9 @@
 
 namespace Facebook\WebDriver;
 
+use Facebook\WebDriver\Exception\InvalidElementStateException;
 use Facebook\WebDriver\Exception\NoSuchElementException;
 use Facebook\WebDriver\Exception\UnexpectedTagNameException;
-use Facebook\WebDriver\Exception\WebDriverException;
 use Facebook\WebDriver\Support\XPathEscaper;
 
 /**
@@ -30,7 +30,7 @@ public function __construct(WebDriverElement $element)
 
         $this->name = $element->getAttribute('name');
         if ($this->name === null) {
-            throw new WebDriverException('The input does not have a "name" attribute.');
+            throw new InvalidElementStateException('The input does not have a "name" attribute.');
         }
 
         $this->element = $element;

lib/Cookie.php

@@ -2,7 +2,7 @@
 
 namespace Facebook\WebDriver;
 
-use InvalidArgumentException;
+use Facebook\WebDriver\Exception\Internal\LogicException;
 
 /**
  * Set values of an cookie.
@@ -36,10 +36,10 @@ public function __construct($name, $value)
     public static function createFromArray(array $cookieArray)
     {
         if (!isset($cookieArray['name'])) {
-            throw new InvalidArgumentException('Cookie name should be set');
+            throw LogicException::forError('Cookie name should be set');
         }
         if (!isset($cookieArray['value'])) {
-            throw new InvalidArgumentException('Cookie value should be set');
+            throw LogicException::forError('Cookie value should be set');
         }
         $cookie = new self($cookieArray['name'], $cookieArray['value']);
 
@@ -107,7 +107,7 @@ public function getPath()
     public function setDomain($domain)
     {
         if (mb_strpos($domain, ':') !== false) {
-            throw new InvalidArgumentException(sprintf('Cookie domain "%s" should not contain a port', $domain));
+            throw LogicException::forError(sprintf('Cookie domain "%s" should not contain a port', $domain));
         }
 
         $this->offsetSet('domain', $domain);
@@ -258,11 +258,11 @@ public function offsetUnset($offset)
     protected function validateCookieName($name)
     {
         if ($name === null || $name === '') {
-            throw new InvalidArgumentException('Cookie name should be non-empty');
+            throw LogicException::forError('Cookie name should be non-empty');
         }
 
         if (mb_strpos($name, ';') !== false) {
-            throw new InvalidArgumentException('Cookie name should not contain a ";"');
+            throw LogicException::forError('Cookie name should not contain a ";"');
         }
     }
 
@@ -272,7 +272,7 @@ protected function validateCookieName($name)
     protected function validateCookieValue($value)
     {
         if ($value === null) {
-            throw new InvalidArgumentException('Cookie value is required when setting a cookie');
+            throw LogicException::forError('Cookie value is required when setting a cookie');
         }
     }
 }

lib/Exception/DriverServerDiedException.php

@@ -0,0 +1,16 @@
+<?php declare(strict_types=1);
+
+namespace Facebook\WebDriver\Exception\Internal;
+
+use Facebook\WebDriver\Exception\PhpWebDriverExceptionInterface;
+
+/**
+ * The driver server process is unexpectedly no longer available.
+ */
+class DriverServerDiedException extends \RuntimeException implements PhpWebDriverExceptionInterface
+{
+    public function __construct(\Exception $previous = null)
+    {
+        parent::__construct('The driver server has died.', 0, $previous);
+    }
+}

lib/Exception/Internal/DriverServerDiedException.php

@@ -0,0 +1,16 @@
+<?php declare(strict_types=1);
+
+namespace Facebook\WebDriver\Exception\Internal;
+
+use Facebook\WebDriver\Exception\PhpWebDriverExceptionInterface;
+
+/**
+ * Exception class thrown when a filesystem related operation failure happens.
+ */
+class IOException extends \LogicException implements PhpWebDriverExceptionInterface
+{
+    public static function forFileError(string $message, string $path): self
+    {
+        return new self(sprintf($message . ' ("%s")', $path));
+    }
+}

lib/Exception/Internal/IOException.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types=1);
+
+namespace Facebook\WebDriver\Exception\Internal;
+
+use Facebook\WebDriver\Exception\PhpWebDriverExceptionInterface;
+
+/**
+ * Exception thrown when error in program logic occurs. This includes invalid domain data and unexpected data states.
+ */
+class LogicException extends \LogicException implements PhpWebDriverExceptionInterface
+{
+    public static function forError(string $message): self
+    {
+        return new self($message);
+    }
+
+    public static function forInvalidHttpMethod(string $url, string $httpMethod, array $params): self
+    {
+        return new self(
+            sprintf(
+                'The http method called for "%s" is "%s", but it has to be POST' .
+                ' if you want to pass the JSON params %s',
+                $url,
+                $httpMethod,
+                json_encode($params)
+            )
+        );
+    }
+}

lib/Exception/Internal/LogicException.php

@@ -0,0 +1,32 @@
+<?php declare(strict_types=1);
+
+namespace Facebook\WebDriver\Exception\Internal;
+
+use Facebook\WebDriver\Exception\PhpWebDriverExceptionInterface;
+use Symfony\Component\Process\Process;
+
+/**
+ * Exception thrown if an error which can only be found on runtime occurs.
+ */
+class RuntimeException extends \RuntimeException implements PhpWebDriverExceptionInterface
+{
+    public static function forError(string $message): self
+    {
+        return new self($message);
+    }
+
+    /**
+     * @param Process $process
+     * @return RuntimeException
+     */
+    public static function forDriverError(Process $process): self
+    {
+        return new self(
+            sprintf(
+                'Error starting driver executable "%s": %s',
+                $process->getCommandLine(),
+                $process->getErrorOutput()
+            )
+        );
+    }
+}

lib/Exception/Internal/RuntimeException.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types=1);
+
+namespace Facebook\WebDriver\Exception\Internal;
+
+use Facebook\WebDriver\Exception\PhpWebDriverExceptionInterface;
+
+/**
+ * Exception thrown on invalid or unexpected server response.
+ */
+class UnexpectedResponseException extends \RuntimeException implements PhpWebDriverExceptionInterface
+{
+    public static function forError(string $message): self
+    {
+        return new self($message);
+    }
+
+    public static function forJsonDecodingError(int $jsonLastError, string $rawResults): self
+    {
+        return new self(
+            sprintf(
+                "JSON decoding of remote response failed.\n" .
+                "Error code: %d\n" .
+                "The response: '%s'\n",
+                $jsonLastError,
+                $rawResults
+            )
+        );
+    }
+}