Upgrade phpstan; increase phpstan level; fix a few bugs

composer.json

@@ -20,8 +20,8 @@
     },
     "require-dev": {
         "mink/driver-testsuite": "dev-master",
-        "phpstan/phpstan": "^1.10",
-        "phpstan/phpstan-phpunit": "^1.3",
+        "phpstan/phpstan": "^2",
+        "phpstan/phpstan-phpunit": "^2",
         "phpunit/phpunit": "^9.6.8",
         "symfony/error-handler": "^5.4 || ^6.0 || ^7.0",
         "symfony/process": "^5.4 || ^6.0 || ^7.0",

phpstan.dist.neon

@@ -1,10 +1,12 @@
 parameters:
-    level: 8
+    level: 10
     paths:
         - src
         - tests
-    checkMissingIterableValueType: false
     treatPhpDocTypesAsCertain: false
+    stubFiles:
+        - stubs/WebDriverTimeouts.stub
+        - stubs/RemoteWebDriver.stub
 
 includes:
     - vendor/phpstan/phpstan-phpunit/extension.neon

src/WebdriverClassicDriver.php

@@ -77,6 +77,9 @@ class WebdriverClassicDriver extends CoreDriver
 
     private DesiredCapabilities $desiredCapabilities;
 
+    /**
+     * @var array{script?: null|numeric, implicit?: null|numeric, page?: null|numeric}
+     */
     private array $timeouts = [];
 
     private string $webDriverHost;
@@ -85,6 +88,7 @@ class WebdriverClassicDriver extends CoreDriver
 
     /**
      * @param string $browserName One of 'edge', 'firefox', 'chrome' or any one of {@see WebDriverBrowserType} constants.
+     * @param array<string, mixed> $desiredCapabilities
      */
     public function __construct(
         string $browserName = self::DEFAULT_BROWSER,
@@ -262,7 +266,7 @@ public function getWindowNames(): array
 
     public function getWindowName(): string
     {
-        $name = (string)$this->evaluateScript('window.name');
+        $name = $this->getAsString($this->evaluateScript('window.name'), 'Window name');
 
         if ($name === '') {
             $name = self::W3C_WINDOW_HANDLE_PREFIX . $this->getWebDriver()->getWindowHandle();
@@ -299,22 +303,22 @@ public function getText(
         return trim(str_replace(
             ["\r\n", "\r", "\n", "\xc2\xa0"],
             ' ',
-            $this->getElementDomProperty($this->findElement($xpath), 'innerText')
+            $this->getAsString($this->getElementDomProperty($this->findElement($xpath), 'innerText'), 'The element\'s innerText')
         ));
     }
 
     public function getHtml(
         #[Language('XPath')]
         string $xpath
     ): string {
-        return $this->getElementDomProperty($this->findElement($xpath), 'innerHTML');
+        return $this->getAsString($this->getElementDomProperty($this->findElement($xpath), 'innerHTML'), 'The element\'s innerHTML');
     }
 
     public function getOuterHtml(
         #[Language('XPath')]
         string $xpath
     ): string {
-        return $this->getElementDomProperty($this->findElement($xpath), 'outerHTML');
+        return $this->getAsString($this->getElementDomProperty($this->findElement($xpath), 'outerHTML'), 'The element\'s outerHTML');
     }
 
     public function getAttribute(
@@ -326,9 +330,13 @@ public function getAttribute(
         // so we cannot use webdriver api for this. See also: https://w3c.github.io/webdriver/#dfn-get-element-attribute
         $escapedName = $this->jsonEncode($name, 'get attribute', 'attribute name');
         $script = "return arguments[0].getAttribute($escapedName)";
-        return $this->executeJsOnXpath($xpath, $script);
+        $result = $this->executeJsOnXpath($xpath, $script);
+        return $result === null ? null : $this->getAsString($result, "The element's $name attribute");
     }
 
+    /**
+     * @return array<array-key, mixed>|bool|mixed|string|null
+     */
     public function getValue(
         #[Language('XPath')]
         string $xpath
@@ -369,6 +377,9 @@ public function getValue(
         }
     }
 
+    /**
+     * @param array<array-key, mixed>|bool|mixed|string|null $value
+     */
     public function setValue(
         #[Language('XPath')]
         string $xpath,
@@ -386,7 +397,7 @@ public function setValue(
                     if (is_array($value)) {
                         $this->deselectAllOptions($element);
                         foreach ($value as $option) {
-                            $this->selectOptionOnElement($element, $option, true);
+                            $this->selectOptionOnElement($element, $this->getAsString($option, 'Option value'), true);
                         }
                         return;
                     }
@@ -736,7 +747,7 @@ public function getWebDriverSessionId(): ?string
     /**
      * Sets the timeouts to apply to the webdriver session
      *
-     * @param array $timeouts The session timeout settings: Array of {script, implicit, page} => time in milliseconds
+     * @param array{script?: numeric, implicit?: numeric, page?: numeric} $timeouts The session timeout settings: Array of {script, implicit, page} => time in milliseconds
      * @throws DriverException
      * @api
      */
@@ -785,6 +796,8 @@ private function getNormalisedBrowserName(): string
     /**
      * Detect and assign appropriate browser capabilities
      *
+     * @param array<string, mixed> $desiredCapabilities
+     *
      * @see https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities
      */
     private function initCapabilities(array $desiredCapabilities): DesiredCapabilities
@@ -1227,5 +1240,20 @@ private function getElementDomProperty(RemoteWebElement $element, string $proper
         }
     }
 
+    /**
+     * @param mixed $value
+     */
+    private function getAsString($value, string $name): string
+    {
+        if (!is_scalar($value)) {
+            $actualType = gettype($value);
+            throw new \RuntimeException(
+                "$name should be a string or at least a scalar value, but received `$actualType` instead"
+            );
+        }
+
+        return (string)$value;
+    }
+
     // </editor-fold>
 }

stubs/RemoteWebDriver.stub

@@ -0,0 +1,11 @@
+<?php
+
+namespace Facebook\WebDriver\Remote;
+
+interface RemoteWebDriver
+{
+    /**
+     * @return list<string>
+     */
+    public function getWindowHandles(): array;
+}

stubs/WebDriverTimeouts.stub

@@ -0,0 +1,24 @@
+<?php
+
+namespace Facebook\WebDriver;
+
+/**
+ * To be removed after {@see https://github.com/php-webdriver/php-webdriver/pull/1120} is merged.
+ */
+interface WebDriverTimeouts
+{
+    /**
+     * @param null|int|float $seconds Wait time in seconds.
+     */
+    public function implicitlyWait($seconds): self;
+
+    /**
+     * @param null|int|float $seconds Wait time in seconds.
+     */
+    public function setScriptTimeout($seconds): self;
+
+    /**
+     * @param null|int|float $seconds Wait time in seconds.
+     */
+    public function pageLoadTimeout($seconds): self;
+}

tests/Custom/TimeoutTest.php

@@ -65,6 +65,9 @@ public function testDeprecatedShortPageLoadTimeoutThrowsException(string $type):
         $this->driver->visit($this->pathTo('/page_load.php?sleep=2'));
     }
 
+    /**
+     * @return iterable<array{type: string}>
+     */
     public static function deprecatedPageLoadDataProvider(): iterable
     {
         yield 'selenium 3 style' => ['type' => 'pageLoad'];

tests/WebdriverClassicConfig.php

@@ -21,7 +21,10 @@ public static function getInstance(): self
 
     public function createDriver(): WebdriverClassicDriver
     {
-        $seleniumHost = $_SERVER['DRIVER_URL'];
+        $seleniumHost = $_SERVER['DRIVER_URL'] ?? null;
+        if (!is_string($seleniumHost)) {
+            throw new \RuntimeException('Selenium host must be specified (as a string) in $_SERVER[DRIVER_URL].');
+        }
 
         return new WebdriverClassicDriver($this->getBrowserName(), [], $seleniumHost);
     }

tests/bootstrap.php

@@ -4,9 +4,11 @@
 
 use Symfony\Component\Process\Process;
 
-$minkTestServerPort = isset($_SERVER['WEB_FIXTURES_HOST'])
-    ? parse_url($_SERVER['WEB_FIXTURES_HOST'], PHP_URL_PORT)
-    : '8002';
+$fixturesHost = $_SERVER['WEB_FIXTURES_HOST'] ?? '//host:8002';
+if (!is_string($fixturesHost)) {
+    throw new RuntimeException('The fixtures host must be specified in $_SERVER[WEB_FIXTURES_HOST] as a string');
+}
+$minkTestServerPort = parse_url($fixturesHost, PHP_URL_PORT);
 
 $minkTestServer = new Process([
     PHP_BINARY,