Paraunit Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev facile-it/paraunit
   

   Ensure compatibility with your PHPUnit version (check compatibility table).

2. First Run:

   vendor/bin/paraunit run
   

   This executes all tests in parallel using your existing PHPUnit configuration.

3. Verify Integration:

   • Paraunit will prompt to add a bootstrap extension to your phpunit.xml if missing. Confirm with y to auto-configure.
   • Example phpunit.xml snippet:

     <phpunit ...>
         <extensions>
             <bootstrap class="Facile\Paraunit\Bootstrap"/>
         </extensions>
     </phpunit>
     

Key First Use Cases

• Speed up CI/CD: Replace phpunit with paraunit run in your pipeline.
• Coverage Reports: Generate parallel coverage:

  vendor/bin/paraunit coverage --html=./coverage
  

  Paraunit auto-detects the fastest coverage driver (Pcov/Xdebug/PHPDbg).

Implementation Patterns

Workflow Integration

1. Replace PHPUnit Commands:

   • Use paraunit run instead of phpunit for all test executions.
   • Example CI script:

     script:
       - vendor/bin/paraunit run --stop-on-failure
     

2. Parallel Test Suites:

   • Target specific suites with --testsuite:

     vendor/bin/paraunit run --testsuite=Unit --testsuite=Feature
     

   • Exclude suites with --exclude-testsuite:

     vendor/bin/paraunit run --exclude-testsuite=Integration
     

3. Chunked Execution:

   • Split tests into chunks for large suites:

     vendor/bin/paraunit run --chunk-size=50
     

4. Randomized Order:

   • Shuffle test execution for better parallelism:

     vendor/bin/paraunit run --sort=random
     

Advanced Patterns

• Pass-Through Options: Forward PHPUnit flags directly:

  vendor/bin/paraunit run -- --group=auth --coverage-text
  

• Debugging Parallel Runs: Enable debug mode to inspect process outputs:

  vendor/bin/paraunit run --debug
  

• Stop-on-Failure: Halt execution on specific issues (e.g., errors, deprecations):

  vendor/bin/paraunit run --stop-on-error --stop-on-deprecation
  

CI/CD Optimization

• GitLab Coverage: Generate Cobertura format for GitLab visualization:

  vendor/bin/paraunit coverage --cobertura=coverage.xml
  

• Artifact Storage: Cache coverage reports between runs:

  vendor/bin/paraunit coverage --cache-warmup
  

Gotchas and Tips

Common Pitfalls

1. Bootstrap Extension Missing:

   • Symptom: Tests run sequentially or fail silently.
   • Fix: Run paraunit run once to auto-add the <bootstrap> tag to phpunit.xml.
   • Manual Fix: Add this to your config:

     <extensions>
         <bootstrap class="Facile\Paraunit\Bootstrap"/>
     </extensions>
     

2. Coverage Driver Conflicts:

   • Symptom: Coverage reports are empty or incomplete.
   • Fix: Ensure pcov or xdebug is installed:

     pecl install pcov  # For Pcov
     

     Paraunit auto-falls back to PHPDbg if others are unavailable.

3. Test Dependencies:

   • Symptom: Parallel runs fail due to shared state (e.g., in-memory caches).
   • Fix: Use --sort=random to mitigate flakiness or refactor tests to be isolated.

4. Stop-on Options:

   • Symptom: Tests continue after --stop-on-failure is set.
   • Fix: Ensure the option is passed before test arguments:

     vendor/bin/paraunit run --stop-on-failure tests/Unit/
     

Debugging Tips

• Process Output: Use --debug to see raw process logs:

  vendor/bin/paraunit run --debug | grep "Process ID"
  

• Transient Dependencies: If tests fail intermittently, check for:

  • Database locks (use --sort=random).
  • File system races (avoid shared test files).

• Coverage Cache: Warm the cache before running coverage:

  vendor/bin/paraunit coverage --cache-warmup --html=./coverage
  

Configuration Quirks

1. PHPUnit Deprecations:

   • Paraunit respects displayDetailsOnTestsThatTriggerDeprecations in phpunit.xml.
   • Default is false (hidden). Set to true to show details:

     <phpunit ...>
         <displayDetailsOnTestsThatTriggerDeprecations>true</displayDetailsOnTestsThatTriggerDeprecations>
     </phpunit>
     

2. Excluded Issues:

   • Use --display-all-issues to show suppressed warnings/notices:

     vendor/bin/paraunit run --display-all-issues
     

3. PHPUnit 13+:

   • Paraunit 2.8+ supports PHPUnit 13, but ensure your phpunit.xml uses:

     <phpunit bootstrap="vendor/autoload.php" ...>
     

Extension Points

1. Custom Test Selection: Override test filtering via --test-suffix:

   vendor/bin/paraunit run --test-suffix=Test.php --test-suffix=Spec.php
   

2. Symfony Integration: Paraunit works with Symfony Flex projects out-of-the-box. For custom setups:

   • Ensure symfony/flex is installed (or manually configure autoloading).

3. Parallelism Limits:

   • Paraunit defaults to using all available CPU cores.
   • To limit parallelism (e.g., for CI), set the PARALLEL_PROCESSES env var:

     PARALLEL_PROCESSES=4 vendor/bin/paraunit run
     

4. Custom Bootstrap: Extend the Facile\Paraunit\Bootstrap class to add pre-test logic:

   namespace App\Tests\Bootstrap;
   use Facile\Paraunit\Bootstrap as ParaunitBootstrap;
   
   class CustomBootstrap extends ParaunitBootstrap {
       public function __construct() {
           // Add custom setup here
       }
   }
   

   Update phpunit.xml:

   <bootstrap class="App\Tests\Bootstrap\CustomBootstrap"/>