Make functional tests more robust and informative

.github/workflows/functional.yml

@@ -45,7 +45,7 @@ jobs:
 
       - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
         with:
-          php-version: "${{ matrix.php-version }}"
+          php-version: ${{ matrix.php-version }}
           coverage: xdebug
 
       - uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # 4.0.0
@@ -54,10 +54,10 @@ jobs:
 
       - name: Run tests
         if: ${{ !matrix.experimental }}
-        # Include --fail-on-skipped when min PHP is > 7.2.5
-        run: vendor/bin/phpunit --group functional
+        # Include --fail-on-skipped when min PHP is > 7.2.5 (for PHPUnit 9.5+)
+        run: vendor/bin/phpunit --group xdebug-functional
 
       # Show deprecations on latest PHP
       - name: Run tests (experimental)
         if: ${{ matrix.experimental }}
-        run: vendor/bin/phpunit --group functional --fail-on-skipped --display-deprecations
+        run: vendor/bin/phpunit --group xdebug-functional --fail-on-skipped --display-deprecations

phpunit.xml.dist

@@ -11,7 +11,7 @@
 
     <groups>
         <exclude>
-            <group>functional</group>
+            <group>xdebug-functional</group>
         </exclude>
     </groups>
 </phpunit>

tests/App/Framework/AppHelper.php

@@ -16,23 +16,31 @@
 use Composer\XdebugHandler\Process;
 use Composer\XdebugHandler\XdebugHandler;
 
+/**
+ * This class runs and provides functionality for the xdebug-handler functional
+ * test apps.
+ *
+ * It sets up the logger and outputs debug and status messages to stdout.
+ *
+ * The test apps can be run from the command-line and will show detailed output
+ * with the --display and --inis options.
+ */
 class AppHelper extends AppRunner
 {
     public const ENV_IS_DISPLAY = 'XDEBUG_HANDLER_TEST_DISPLAY';
     public const ENV_SHOW_INIS = 'XDEBUG_HANDLER_TEST_INIS';
 
     /** @var string */
     private $appName;
+
     /** @var string */
     private $envPrefix;
+
     /** @var non-empty-list<string> */
     private $serverArgv;
+
     /** @var class-string|null */
     private $className;
-    /** @var bool */
-    private $display;
-    /** @var bool */
-    private $showInis;
 
     /** @var Logger */
     private $logger;
@@ -41,21 +49,19 @@ class AppHelper extends AppRunner
     private $output;
 
     /** @var Status */
-    private $status = null;
+    private $status;
 
     public function __construct(string $script)
     {
         parent::__construct(dirname($script));
         $this->appName = $this->getAppName($script);
         $this->envPrefix = $this->getEnvPrefix($script);
 
-        $this->display = $this->getDisplayFromServer();
-        $this->showInis = $this->getInisFromServer();
-        $this->setServerArgv();
+        [$display, $showInis] = $this->setServerArgvAndOptions();
 
-        $this->output = new Output($this->display);
+        $this->output = new Output($display);
         $this->logger = new Logger($this->output);
-        $this->status = new Status($this->display, $this->showInis);
+        $this->status = new Status($display, $showInis);
     }
 
     /**
@@ -73,9 +79,10 @@ public function getServerArgv0(): string
     }
 
     /**
+     * Starts an instance of XdebugHandler
      *
-     * @param class-string $class
-     * @param array<string, string> $settings
+     * @param class-string $class Extending class name
+     * @param array<string, string> $settings XdebugHandler settings
      */
     public function getXdebugHandler(?string $class = null, ?array $settings = null): XdebugHandler
     {
@@ -102,16 +109,40 @@ public function getXdebugHandler(?string $class = null, ?array $settings = null)
         return $xdebug;
     }
 
+    /**
+     * Runs a PHP sub-process
+     *
+     * @param string $script The file to run
+     * @param PhpOptions $options
+     */
     public function runScript(string $script, ?PhpOptions $options = null): void
     {
-        parent::runScript($script, $options);
+        $script = $this->checkScript($script);
+
+        if ($options === null) {
+            $options = new PhpOptions();
+        }
+
+        // set passthru in child proccesses so output gets collected
+        $options->setPassthru(true);
+        $this->phpExecutor->run($script, $options, $this->scriptDir);
     }
 
+    /**
+     * Outputs a message prefixed appname[pid] to stdout
+     *
+     * @param string $message
+     */
     public function write(string $message): void
     {
         $this->logger->write($message, $this->appName);
     }
 
+    /**
+     * Outputs the Xdebug loaded status to stdout
+     *
+     * More details can be shown with the --display and --inis options.
+     */
     public function writeXdebugStatus(): void
     {
         $className = $this->className ?? XdebugHandler::class;
@@ -122,10 +153,20 @@ public function writeXdebugStatus(): void
         }
     }
 
-    private function setServerArgv(): void
+    /**
+     * Checks $_SERVER['argv'] and returns $display and $showInis values
+     *
+     * The flags to display the full status and ini file list are passed on the
+     * command-line, then removed and set in the environment.
+     *
+     * @return array<bool, bool>
+     */
+    private function setServerArgvAndOptions(): array
     {
         $args = [];
         $errors = false;
+        $display = false;
+        $showInis = false;
 
         if (isset($_SERVER['argv']) && is_array($_SERVER['argv'])) {
             foreach ($_SERVER['argv'] as $value) {
@@ -134,6 +175,18 @@ private function setServerArgv(): void
                     break;
                 }
 
+                if ($value === '--display') {
+                    $display = true;
+                    Process::setEnv(self::ENV_IS_DISPLAY, '1');
+                    continue;
+                }
+
+                if ($value === '--inis') {
+                    $showInis = true;
+                    Process::setEnv(self::ENV_SHOW_INIS, '1');
+                    continue;
+                }
+
                 $args[] = $value;
             }
         }
@@ -142,46 +195,12 @@ private function setServerArgv(): void
             throw new \RuntimeException('$_SERVER[argv] is not as expected');
         }
 
+        $_SERVER['argv'] = $args;
         $this->serverArgv = $args;
-    }
-
-    private function getDisplayFromServer(): bool
-    {
-        $result = false;
-
-        if (isset($_SERVER['argv']) && is_array($_SERVER['argv'])) {
-            $key = array_search('--display', $_SERVER['argv'], true);
-
-            if (is_int($key)) {
-                $result = true;
-                Process::setEnv(self::ENV_IS_DISPLAY, '1');
-                // @phpstan-ignore argument.type
-                array_splice($_SERVER['argv'], $key, 1);
-            } else {
-                $result = false !== getenv(self::ENV_IS_DISPLAY);
-            }
-        }
-
-        return $result;
-    }
-
-    private function getInisFromServer(): bool
-    {
-        $result = false;
-
-        if (isset($_SERVER['argv']) && is_array($_SERVER['argv'])) {
-            $key = array_search('--inis', $_SERVER['argv'], true);
-
-            if (is_int($key)) {
-                $result = true;
-                Process::setEnv(self::ENV_SHOW_INIS, '1');
-                // @phpstan-ignore argument.type
-                array_splice($_SERVER['argv'], $key, 1);
-            } else {
-                $result = false !== getenv(self::ENV_SHOW_INIS);
-            }
-        }
 
-        return $result;
+        return [
+            $display || false !== getenv(self::ENV_IS_DISPLAY),
+            $showInis || false !== getenv(self::ENV_SHOW_INIS),
+        ];
     }
 }

tests/App/Framework/AppRunner.php

@@ -13,12 +13,16 @@
 
 namespace Composer\XdebugHandler\Tests\App\Framework;
 
+/**
+ * This class runs and provides functionality for the xdebug-handler functional
+ * tests.
+ */
 class AppRunner
 {
     /** @var string */
-    private $scriptDir;
+    protected $scriptDir;
     /** @var PhpExecutor */
-    private $phpExecutor;
+    protected $phpExecutor;
 
     public function __construct(?string $scriptDir = null)
     {
@@ -31,6 +35,9 @@ public function __construct(?string $scriptDir = null)
         $this->phpExecutor = new PhpExecutor();
     }
 
+    /**
+     * Runs a script and returns its captured output
+     */
     public function run(string $script, ?PhpOptions $options = null, bool $allow = false): Logs
     {
         $script = $this->checkScript($script);
@@ -54,19 +61,6 @@ public function run(string $script, ?PhpOptions $options = null, bool $allow = f
         return new Logs($outputLines);
     }
 
-    public function runScript(string $script, ?PhpOptions $options = null): void
-    {
-        $script = $this->checkScript($script);
-
-        if ($options === null) {
-            $options = new PhpOptions();
-        }
-
-        // set passthru in child proccesses so output gets collected
-        $options->setPassthru(true);
-        $this->phpExecutor->run($script, $options, $this->scriptDir);
-    }
-
     public function getAppName(string $script): string
     {
         return basename($script, '.php');
@@ -84,7 +78,7 @@ public function getEnvPrefix(string $script): string
         return strtoupper(str_replace(array('-', ' '), '_', $name));
     }
 
-    private function checkScript(string $script): string
+    protected function checkScript(string $script): string
     {
         if (file_exists($script)) {
             return $script;