POC: lightweight subprocess isolation via pcntl_fork()

.github/workflows/ci.yaml

@@ -119,6 +119,11 @@ jobs:
           - "8.3"
           - "8.4"
 
+        include:
+          - os: ubuntu-latest
+            php-version: "8.3"
+            add-ext: ", pcntl"
+
     steps:
       - name: Configure Git to avoid issues with line endings
         if: matrix.os == 'windows-latest'
@@ -131,7 +136,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
-          extensions: ${{ env.PHP_EXTENSIONS }}
+          extensions: "${{ env.PHP_EXTENSIONS }}${{ matrix.add-ext }}"
           ini-values: ${{ env.PHP_INI_VALUES }}
           tools: none
 
@@ -166,6 +171,11 @@ jobs:
           - "8.3"
           - "8.4"
 
+        include:
+          - os: ubuntu-latest
+            php-version: "8.3"
+            add-ext: ", pcntl"
+
     steps:
       - name: Configure Git to avoid issues with line endings
         if: matrix.os == 'windows-latest'
@@ -178,7 +188,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
-          extensions: ${{ env.PHP_EXTENSIONS }}
+          extensions: "${{ env.PHP_EXTENSIONS }}${{ matrix.add-ext }}"
           ini-values: ${{ env.PHP_INI_VALUES }}
           coverage: pcov
           tools: none

src/Framework/Attributes/RunClassInSeparateProcess.php

@@ -19,4 +19,15 @@
 #[Attribute(Attribute::TARGET_CLASS)]
 final readonly class RunClassInSeparateProcess
 {
+    private ?bool $forkIfPossible;
+
+    public function __construct(?bool $forkIfPossible = null)
+    {
+        $this->forkIfPossible = $forkIfPossible;
+    }
+
+    public function forkIfPossible(): ?bool
+    {
+        return $this->forkIfPossible;
+    }
 }

src/Framework/Attributes/RunInSeparateProcess.php

@@ -19,4 +19,15 @@
 #[Attribute(Attribute::TARGET_METHOD)]
 final readonly class RunInSeparateProcess
 {
+    private ?bool $forkIfPossible;
+
+    public function __construct(?bool $forkIfPossible = null)
+    {
+        $this->forkIfPossible = $forkIfPossible;
+    }
+
+    public function forkIfPossible(): ?bool
+    {
+        return $this->forkIfPossible;
+    }
 }

src/Framework/Attributes/RunTestsInSeparateProcesses.php

@@ -19,4 +19,15 @@
 #[Attribute(Attribute::TARGET_CLASS)]
 final readonly class RunTestsInSeparateProcesses
 {
+    private ?bool $forkIfPossible;
+
+    public function __construct(?bool $forkIfPossible = null)
+    {
+        $this->forkIfPossible = $forkIfPossible;
+    }
+
+    public function forkIfPossible(): ?bool
+    {
+        return $this->forkIfPossible;
+    }
 }

src/Framework/TestBuilder.php

@@ -19,6 +19,9 @@
 use PHPUnit\Metadata\ExcludeStaticPropertyFromBackup;
 use PHPUnit\Metadata\Parser\Registry as MetadataRegistry;
 use PHPUnit\Metadata\PreserveGlobalState;
+use PHPUnit\Metadata\RunClassInSeparateProcess;
+use PHPUnit\Metadata\RunInSeparateProcess;
+use PHPUnit\Metadata\RunTestsInSeparateProcesses;
 use PHPUnit\TextUI\Configuration\Registry as ConfigurationRegistry;
 use ReflectionClass;
 
@@ -51,6 +54,7 @@
                 $this->shouldTestMethodBeRunInSeparateProcess($className, $methodName),
                 $this->shouldGlobalStateBePreserved($className, $methodName),
                 $this->shouldAllTestMethodsOfTestClassBeRunInSingleSeparateProcess($className),
+                $this->shouldForkIfPossible($className, $methodName),
                 $this->backupSettings($className, $methodName),
                 $groups,
             );
@@ -64,6 +68,7 @@
             $this->shouldTestMethodBeRunInSeparateProcess($className, $methodName),
             $this->shouldGlobalStateBePreserved($className, $methodName),
             $this->shouldAllTestMethodsOfTestClassBeRunInSingleSeparateProcess($className),
+            $this->shouldForkIfPossible($className, $methodName),
             $this->backupSettings($className, $methodName),
         );
 
@@ -76,7 +81,7 @@
      * @psalm-param array{backupGlobals: ?bool, backupGlobalsExcludeList: list<string>, backupStaticProperties: ?bool, backupStaticPropertiesExcludeList: array<string,list<string>>} $backupSettings
      * @psalm-param list<non-empty-string> $groups
      */
-    private function buildDataProviderTestSuite(string $methodName, string $className, array $data, bool $runTestInSeparateProcess, ?bool $preserveGlobalState, bool $runClassInSeparateProcess, array $backupSettings, array $groups): DataProviderTestSuite
+    private function buildDataProviderTestSuite(string $methodName, string $className, array $data, bool $runTestInSeparateProcess, ?bool $preserveGlobalState, bool $runClassInSeparateProcess, bool $forkIfPossible, array $backupSettings, array $groups): DataProviderTestSuite
     {
         $dataProviderTestSuite = DataProviderTestSuite::empty(
             $className . '::' . $methodName,
@@ -98,6 +103,7 @@
                 $runTestInSeparateProcess,
                 $preserveGlobalState,
                 $runClassInSeparateProcess,
+                $forkIfPossible,
                 $backupSettings,
             );
 
@@ -110,7 +116,7 @@
     /**
      * @psalm-param array{backupGlobals: ?bool, backupGlobalsExcludeList: list<string>, backupStaticProperties: ?bool, backupStaticPropertiesExcludeList: array<string,list<string>>} $backupSettings
      */
-    private function configureTestCase(TestCase $test, bool $runTestInSeparateProcess, ?bool $preserveGlobalState, bool $runClassInSeparateProcess, array $backupSettings): void
+    private function configureTestCase(TestCase $test, bool $runTestInSeparateProcess, ?bool $preserveGlobalState, bool $runClassInSeparateProcess, bool $forkIfPossible, array $backupSettings): void
     {
         if ($runTestInSeparateProcess) {
             $test->setRunTestInSeparateProcess(true);
@@ -120,6 +126,10 @@
             $test->setRunClassInSeparateProcess(true);
         }
 
+        if ($forkIfPossible) {
+            $test->setForkIfPossible(true);
+        }
+
         if ($preserveGlobalState !== null) {
             $test->setPreserveGlobalState($preserveGlobalState);
         }
@@ -272,4 +282,53 @@
     {
         return MetadataRegistry::parser()->forClass($className)->isRunClassInSeparateProcess()->isNotEmpty();
     }
+
+    /**
+     * @psalm-param class-string $className
+     * @psalm-param non-empty-string $methodName
+     */
+    private function shouldForkIfPossible(string $className, string $methodName): bool
+    {
+        $metadataForMethod = MetadataRegistry::parser()->forMethod($className, $methodName);
+
+        if ($metadataForMethod->isRunInSeparateProcess()->isNotEmpty()) {
+            $metadata = $metadataForMethod->isRunInSeparateProcess()->asArray()[0];
+
+            assert($metadata instanceof RunInSeparateProcess);
+
+            $forkIfPossible = $metadata->forkIfPossible();
+
+            if ($forkIfPossible !== null) {
+                return $forkIfPossible;
+            }
+        }
+
+        $metadataForClass = MetadataRegistry::parser()->forClass($className);
+
+        if ($metadataForClass->isRunTestsInSeparateProcesses()->isNotEmpty()) {
+            $metadata = $metadataForClass->isRunTestsInSeparateProcesses()->asArray()[0];
+
+            assert($metadata instanceof RunTestsInSeparateProcesses);
+
+            $forkIfPossible = $metadata->forkIfPossible();
+
+            if ($forkIfPossible !== null) {
+                return $forkIfPossible;
+            }
+        }
+
+        if ($metadataForClass->isRunClassInSeparateProcess()->isNotEmpty()) {
+            $metadata = $metadataForClass->isRunClassInSeparateProcess()->asArray()[0];
+
+            assert($metadata instanceof RunClassInSeparateProcess);
+
+            $forkIfPossible = $metadata->forkIfPossible();
+
+            if ($forkIfPossible !== null) {
+                return $forkIfPossible;
+            }
+        }
+
+        return false;
+    }
 }

src/Framework/TestCase.php

@@ -142,6 +142,7 @@ abstract class TestCase extends Assert implements Reorderable, SelfDescribing, T
      */
     private ?array $backupGlobalExceptionHandlers   = null;
     private ?bool $runClassInSeparateProcess        = null;
+    private ?bool $forkIfPossible                   = null;
     private ?bool $runTestInSeparateProcess         = null;
     private bool $preserveGlobalState               = false;
     private bool $inIsolation                       = false;
@@ -340,6 +341,7 @@ final public function run(): void
                 $this,
                 $this->runClassInSeparateProcess && !$this->runTestInSeparateProcess,
                 $this->preserveGlobalState,
+                $this->forkIfPossible === true,
             );
         }
     }
@@ -709,6 +711,14 @@ final public function setRunClassInSeparateProcess(bool $runClassInSeparateProce
         $this->runClassInSeparateProcess = $runClassInSeparateProcess;
     }
 
+    /**
+     * @internal This method is not covered by the backward compatibility promise for PHPUnit
+     */
+    final public function setForkIfPossible(bool $forkIfPossible): void
+    {
+        $this->forkIfPossible = $forkIfPossible;
+    }
+
     /**
      * @internal This method is not covered by the backward compatibility promise for PHPUnit
      */

src/Framework/TestRunner.php

@@ -33,6 +33,7 @@
 use PHPUnit\TextUI\Configuration\Registry as ConfigurationRegistry;
 use PHPUnit\Util\GlobalState;
 use PHPUnit\Util\PHP\AbstractPhpProcess;
+use PHPUnit\Util\PHP\PcntlFork;
 use ReflectionClass;
 use SebastianBergmann\CodeCoverage\Exception as OriginalCodeCoverageException;
 use SebastianBergmann\CodeCoverage\InvalidArgumentException;
@@ -248,8 +249,17 @@
      * @throws ProcessIsolationException
      * @throws StaticAnalysisCacheNotConfiguredException
      */
-    public function runInSeparateProcess(TestCase $test, bool $runEntireClass, bool $preserveGlobalState): void
+    public function runInSeparateProcess(TestCase $test, bool $runEntireClass, bool $preserveGlobalState, bool $forkIfPossible): void
     {
+        if ($forkIfPossible && PcntlFork::isPcntlForkAvailable()) {
+            // forking the parent process is a more lightweight way to run a test in isolation.
+            // it requires the pcntl extension though.
+            $fork = new PcntlFork;
+            $fork->runTest($test);
+
+            return;
+        }
+
         $class = new ReflectionClass($test);
 
         if ($runEntireClass) {

src/Metadata/Metadata.php

@@ -390,19 +390,19 @@ public static function requiresSettingOnMethod(string $setting, string $value):
         return new RequiresSetting(self::METHOD_LEVEL, $setting, $value);
     }
 
-    public static function runClassInSeparateProcess(): RunClassInSeparateProcess
+    public static function runClassInSeparateProcess(?bool $forkIfPossible = null): RunClassInSeparateProcess
     {
-        return new RunClassInSeparateProcess(self::CLASS_LEVEL);
+        return new RunClassInSeparateProcess(self::CLASS_LEVEL, $forkIfPossible);
     }
 
-    public static function runTestsInSeparateProcesses(): RunTestsInSeparateProcesses
+    public static function runTestsInSeparateProcesses(?bool $forkIfPossible = null): RunTestsInSeparateProcesses
     {
-        return new RunTestsInSeparateProcesses(self::CLASS_LEVEL);
+        return new RunTestsInSeparateProcesses(self::CLASS_LEVEL, $forkIfPossible);
     }
 
-    public static function runInSeparateProcess(): RunInSeparateProcess
+    public static function runInSeparateProcess(?bool $forkIfPossible = null): RunInSeparateProcess
     {
-        return new RunInSeparateProcess(self::METHOD_LEVEL);
+        return new RunInSeparateProcess(self::METHOD_LEVEL, $forkIfPossible);
     }
 
     public static function test(): Test

src/Metadata/Parser/AttributeParser.php

@@ -297,12 +297,20 @@ public function forClass(string $className): MetadataCollection
                     break;
 
                 case RunClassInSeparateProcess::class:
-                    $result[] = Metadata::runClassInSeparateProcess();
+                    assert($attributeInstance instanceof RunClassInSeparateProcess);
+
+                    $result[] = Metadata::runClassInSeparateProcess(
+                        $attributeInstance->forkIfPossible(),
+                    );
 
                     break;
 
                 case RunTestsInSeparateProcesses::class:
-                    $result[] = Metadata::runTestsInSeparateProcesses();
+                    assert($attributeInstance instanceof RunTestsInSeparateProcesses);
+
+                    $result[] = Metadata::runTestsInSeparateProcesses(
+                        $attributeInstance->forkIfPossible(),
+                    );
 
                     break;
 
@@ -638,7 +646,11 @@ public function forMethod(string $className, string $methodName): MetadataCollec
                     break;
 
                 case RunInSeparateProcess::class:
-                    $result[] = Metadata::runInSeparateProcess();
+                    assert($attributeInstance instanceof RunInSeparateProcess);
+
+                    $result[] = Metadata::runInSeparateProcess(
+                        $attributeInstance->forkIfPossible(),
+                    );
 
                     break;
 

src/Metadata/RunClassInSeparateProcess.php

@@ -16,6 +16,23 @@
  */
 final readonly class RunClassInSeparateProcess extends Metadata
 {
+    private ?bool $forkIfPossible;
+
+    /**
+     * @psalm-param 0|1 $level
+     */
+    protected function __construct(int $level, ?bool $forkIfPossible = null)
+    {
+        $this->forkIfPossible = $forkIfPossible;
+
+        parent::__construct($level);
+    }
+
+    public function forkIfPossible(): ?bool
+    {
+        return $this->forkIfPossible;
+    }
+
     /**
      * @psalm-assert-if-true RunClassInSeparateProcess $this
      */

src/Metadata/RunInSeparateProcess.php

@@ -16,6 +16,23 @@
  */
 final readonly class RunInSeparateProcess extends Metadata
 {
+    private ?bool $forkIfPossible;
+
+    /**
+     * @psalm-param 0|1 $level
+     */
+    protected function __construct(int $level, ?bool $forkIfPossible = null)
+    {
+        $this->forkIfPossible = $forkIfPossible;
+
+        parent::__construct($level);
+    }
+
+    public function forkIfPossible(): ?bool
+    {
+        return $this->forkIfPossible;
+    }
+
     /**
      * @psalm-assert-if-true RunInSeparateProcess $this
      */

src/Metadata/RunTestsInSeparateProcesses.php

@@ -16,6 +16,23 @@
  */
 final readonly class RunTestsInSeparateProcesses extends Metadata
 {
+    private ?bool $forkIfPossible;
+
+    /**
+     * @psalm-param 0|1 $level
+     */
+    protected function __construct(int $level, ?bool $forkIfPossible = null)
+    {
+        $this->forkIfPossible = $forkIfPossible;
+
+        parent::__construct($level);
+    }
+
+    public function forkIfPossible(): ?bool
+    {
+        return $this->forkIfPossible;
+    }
+
     /**
      * @psalm-assert-if-true RunTestsInSeparateProcesses $this
      */