Capabilities must be provided when resuing session, do not allow them to be null

Null capabilities causes issues and inconsistencies in various places.

Author: OndraM

lib/Remote/RemoteWebDriver.php

@@ -56,22 +56,19 @@ class RemoteWebDriver implements WebDriver, JavaScriptExecutor, WebDriverHasInpu
     /**
      * @param HttpCommandExecutor $commandExecutor
      * @param string $sessionId
-     * @param WebDriverCapabilities|null $capabilities
+     * @param WebDriverCapabilities $capabilities
      * @param bool $isW3cCompliant false to use the legacy JsonWire protocol, true for the W3C WebDriver spec
      */
     protected function __construct(
         HttpCommandExecutor $commandExecutor,
         $sessionId,
-        WebDriverCapabilities $capabilities = null,
+        WebDriverCapabilities $capabilities,
         $isW3cCompliant = false
     ) {
         $this->executor = $commandExecutor;
         $this->sessionID = $sessionId;
         $this->isW3cCompliant = $isW3cCompliant;
-
-        if ($capabilities !== null) {
-            $this->capabilities = $capabilities;
-        }
+        $this->capabilities = $capabilities;
     }
 
     /**
@@ -147,6 +144,8 @@ public static function create(
      * @param int|null $connection_timeout_in_ms Set timeout for the connect phase to remote Selenium WebDriver server
      * @param int|null $request_timeout_in_ms Set the maximum time of a request to remote Selenium WebDriver server
      * @param bool $isW3cCompliant True to use W3C WebDriver (default), false to use the legacy JsonWire protocol
+     * @param WebDriverCapabilities|null $existingCapabilities Provide capabilities of the existing previously created
+     *  session. If not provided, we will attempt to read them, but this will only work when using Selenium Grid.
      * @return static
      */
     public static function createBySessionID(
@@ -157,6 +156,7 @@ public static function createBySessionID(
     ) {
         // BC layer to not break the method signature
         $isW3cCompliant = func_num_args() > 4 ? func_get_arg(4) : true;
+        $existingCapabilities = func_num_args() > 5 ? func_get_arg(5) : null;
 
         $executor = new HttpCommandExecutor($selenium_server_url, null, null);
         if ($connection_timeout_in_ms !== null) {
@@ -170,7 +170,13 @@ public static function createBySessionID(
             $executor->disableW3cCompliance();
         }
 
-        return new static($executor, $session_id, null, $isW3cCompliant);
+        if ($existingCapabilities === null) {
+            throw new UnknownErrorException(
+                'Existing capabilities must be provided when reusing previous session.'
+            );
+        }
+
+        return new static($executor, $session_id, $existingCapabilities, $isW3cCompliant);
     }
 
     /**

phpstan.neon

@@ -23,5 +23,7 @@ parameters:
         # Parameter is intentionally not part of signature to not break BC
         - message: '#PHPDoc tag \@param references unknown parameter: \$isW3cCompliant#'
           path: 'lib/Remote/RemoteWebDriver.php'
+        - message: '#PHPDoc tag \@param references unknown parameter: \$existingCapabilities#'
+          path: 'lib/Remote/RemoteWebDriver.php'
 
     inferPrivatePropertyTypeFromConstructor: true

tests/unit/Remote/RemoteWebDriverTest.php

@@ -22,7 +22,14 @@ class RemoteWebDriverTest extends TestCase
 
     protected function setUp(): void
     {
-        $this->driver = RemoteWebDriver::createBySessionID('session-id', 'http://foo.bar:4444');
+        $this->driver = RemoteWebDriver::createBySessionID(
+            'session-id',
+            'http://foo.bar:4444',
+            null,
+            null,
+            true,
+            new DesiredCapabilities([])
+        );
     }
 
     /**