Add --parallel support to tests command for ParaTest execution

- Add --parallel option to TestsCommand with optional worker count
- Use ParaTest when --parallel is enabled and available
- Fall back to phpunit if paratest is not installed
- Add tests for parallel execution scenarios

Implements: #8

Author: coisa

src/Command/TestsCommand.php

@@ -84,6 +84,13 @@ protected function configure(): void
                 shortcut: 'f',
                 mode: InputOption::VALUE_OPTIONAL,
                 description: 'Filter which tests to run based on a pattern.',
+            )
+            ->addOption(
+                name: 'parallel',
+                shortcut: 'p',
+                mode: InputOption::VALUE_OPTIONAL,
+                description: 'Run tests in parallel using ParaTest. Optional: specify number of workers (e.g., --parallel or --parallel=4).',
+                default: null,
             );
     }
 
@@ -102,8 +109,11 @@ protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $output->writeln('<info>Running PHPUnit tests...</info>');
 
+        $parallel = $input->getOption('parallel');
+        $runner = $this->getTestRunner($parallel !== false ? $parallel : null);
+
         $arguments = [
-            $this->getAbsolutePath('vendor/bin/phpunit'),
+            $runner,
             '--configuration=' . parent::getConfigFile(self::CONFIG),
             '--bootstrap=' . $this->resolvePath($input, 'bootstrap'),
             '--display-deprecations',
@@ -112,6 +122,13 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             '--display-skipped',
         ];
 
+        if ($parallel !== null) {
+            if (is_numeric($parallel)) {
+                $arguments[] = '--processes=' . (int) $parallel;
+            }
+            $arguments[] = '--parallel';
+        }
+
         if (! $input->getOption('no-cache')) {
             $arguments[] = '--cache-directory=' . $this->resolvePath($input, 'cache-dir');
         }
@@ -156,4 +173,23 @@ private function resolvePath(InputInterface $input, string $option): string
     {
         return $this->getAbsolutePath($input->getOption($option));
     }
+
+    /**
+     * Determines the test runner to use based on parallel execution flag.
+     *
+     * The method MUST return the appropriate test runner binary path.
+     * If parallel is enabled, it SHALL return paratest; otherwise, it SHALL return phpunit.
+     *
+     * @param string|null $parallel the parallel option value
+     *
+     * @return string the path to the test runner binary
+     */
+    private function getTestRunner(?string $parallel): string
+    {
+        if ($parallel !== null && $this->filesystem->exists($this->getAbsolutePath('vendor/bin/paratest'))) {
+            return $this->getAbsolutePath('vendor/bin/paratest');
+        }
+
+        return $this->getAbsolutePath('vendor/bin/phpunit');
+    }
 }

tests/Command/TestsCommandTest.php

@@ -137,4 +137,65 @@ public function executeWillReturnFailureIfProcessFails(): void
 
         self::assertSame(TestsCommand::FAILURE, $this->invokeExecute());
     }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function executeWithParallelOptionWillRunParaTest(): void
+    {
+        $this->filesystem->exists(getcwd() . '/vendor/bin/paratest')->willReturn(true);
+
+        $this->willRunProcessWithCallback(function (Process $process): bool {
+            $commandLine = $process->getCommandLine();
+
+            return str_contains($commandLine, 'vendor/bin/paratest')
+                && str_contains($commandLine, '--parallel');
+        });
+
+        $this->input->getOption('parallel')
+            ->willReturn('1');
+        $this->invokeExecute();
+    }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function executeWithParallelOptionAndWorkerCount(): void
+    {
+        $this->filesystem->exists(getcwd() . '/vendor/bin/paratest')->willReturn(true);
+
+        $this->willRunProcessWithCallback(function (Process $process): bool {
+            $commandLine = $process->getCommandLine();
+
+            return str_contains($commandLine, 'vendor/bin/paratest')
+                && str_contains($commandLine, '--processes=4')
+                && str_contains($commandLine, '--parallel');
+        });
+
+        $this->input->getOption('parallel')
+            ->willReturn('4');
+        $this->invokeExecute();
+    }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function executeWithParallelOptionButNoParaTestWillFallbackToPhpUnit(): void
+    {
+        $this->filesystem->exists(getcwd() . '/vendor/bin/paratest')->willReturn(false);
+
+        $this->willRunProcessWithCallback(function (Process $process): bool {
+            $commandLine = $process->getCommandLine();
+
+            return str_contains($commandLine, 'vendor/bin/phpunit')
+                && ! str_contains($commandLine, 'paratest');
+        });
+
+        $this->input->getOption('parallel')
+            ->willReturn('1');
+        $this->invokeExecute();
+    }
 }