Paratest Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev brianium/paratest
   

   Ensure your phpunit version is compatible (check PHPUnit compatibility).

2. First Run: Replace phpunit with vendor/bin/paratest in your test command:

   vendor/bin/paratest
   

   Default behavior parallelizes tests by TestCase. For granular parallelism (by individual tests), use:

   vendor/bin/paratest --functional
   

3. Key Environment Variables:

   • TEST_TOKEN: Unique per-process identifier (e.g., for isolated database connections).
   • UNIQUE_TEST_TOKEN: Unique per-run and per-process (e.g., for shared state coordination).

First Use Case: Speeding Up Test Suites

Replace your existing test command in package.json or CI/CD scripts:

"scripts": {
  "test": "vendor/bin/paratest --coverage-text --coverage-clover=coverage.clover"
}

Note: Ensure your CI environment has sufficient CPU cores (e.g., GitHub Actions: jobs.test.env.CI=true).

Implementation Patterns

Workflow: Parallelizing Tests by TestCase

1. Default Behavior: ParaTest automatically splits tests by TestCase class. No configuration needed.

   vendor/bin/paratest --processes=4  # Uses 4 CPU cores
   

2. Granular Parallelism (Functional Mode): Split tests by individual test methods (useful for large suites):

   vendor/bin/paratest --functional --shard-test-distribution=random
   

   • Sharding Strategies:
     • round-robin: Distribute tests evenly across processes.
     • random: Randomize test distribution (reduces flakiness from order-dependent tests).

3. Integration with CI/CD:

   • GitHub Actions:

     - name: Run tests in parallel
       run: vendor/bin/paratest --processes=$(nproc) --coverage-clover=coverage.clover
     

   • Docker: Use --passthru-php to enable pcov or xdebug:

     vendor/bin/paratest --passthru-php="'-d pcov.enabled=1'"
     

Workflow: Handling Shared State

1. Database Isolation: Use TEST_TOKEN to create isolated database schemas:

   $dbName = getenv('TEST_TOKEN') ? "test_{$token}" : 'test';
   

2. One-Time Initialization: Avoid static variables. Use filesystem locks for coordination:

   public function setUp(): void {
       $lockFile = fopen('/tmp/test_init.lock', 'w+');
       flock($lockFile, LOCK_EX); // Block until first process acquires lock
       if (!file_exists('/tmp/initialized')) {
           self::initialize();
           file_put_contents('/tmp/initialized', '1');
       }
       flock($lockFile, LOCK_UN);
   }
   

3. Test Dependencies:

   • Avoid: Static methods/variables in test classes.
   • Do: Move shared logic to non-test classes (e.g., TestHelper).

Workflow: Code Coverage

1. Combining Reports: ParaTest now correctly merges PHP coverage reports (fixed in v7.22.4):

   vendor/bin/paratest --coverage-clover=coverage.clover
   

   • Supports pcov (PHP 8+) and xdebug:

     XDEBUG_MODE=coverage vendor/bin/paratest
     

2. Excluding Sources:

   vendor/bin/paratest --exclude-source-from-xml-coverage="vendor/"
   

Workflow: Debugging Failed Tests

1. Verbose Output:

   vendor/bin/paratest --verbose
   

   • Copy-paste the failing sub-command to debug:

     php -d pcov.enabled=1 vendor/bin/phpunit --printer \NullPhpunitPrinter tests/Unit/UserTest
     

2. Rerunning Failures: Use --failed to retry only failed tests:

   vendor/bin/paratest --failed
   

Gotchas and Tips

Pitfalls

1. Static State:

   • Issue: Static variables/methods in test classes cause race conditions.
   • Fix: Refactor shared logic into non-test classes or use filesystem locks.

2. Order-Dependent Tests:

   • Issue: Tests assuming execution order may fail in parallel.
   • Fix: Use --shard-test-distribution=random to shuffle test order.

3. Coverage Gaps:

   • Issue: pcov/xdebug may not work without --passthru-php.
   • Fix: Explicitly pass PHP flags:

     vendor/bin/paratest --passthru-php="'-d pcov.enabled=1'"
     

4. JUnit Reports:

   • Issue: Missing test cases in --functional mode (fixed in v7.22.3).
   • Fix: Update ParaTest:

     composer update brianium/paratest
     

Debugging Tips

1. Worker Crashes:

   • If workers crash silently, add --debug to see raw PHPUnit output:

     vendor/bin/paratest --debug
     

2. Resource Limits:

   • Error: Allowed memory size exhausted.
   • Fix: Reduce --processes or increase memory_limit in php.ini.

3. Test Token Conflicts:

   • Error: TEST_TOKEN collisions in CI.
   • Fix: Use UNIQUE_TEST_TOKEN for per-run uniqueness.

Extension Points

1. Custom Sharding: Override test distribution via --shard:

   vendor/bin/paratest --shard=1-10,20-30  # Run tests 1-10 and 20-30 in parallel
   

2. PHPStorm Integration:

   • Configure a custom ParaTest run configuration:
     1. Set interpreter options to ./vendor/bin/paratest_for_phpstorm.
     2. Add ParaTest flags to "Test runner options."

3. TestDox Reports: Generate human-readable test reports:

   vendor/bin/paratest --testdox-text=report.txt --testdox-html=report.html
   

Configuration Quirks

1. PHPUnit Events:

   • ParaTest triggers TestRunner\Started after TestSuite\Loaded (fixed in v7.14.1).
   • Impact: Custom event listeners may need adjustments.

2. Symfony Compatibility:

   • ParaTest drops support for Symfony <8 (v7.15.0+).
   • Fix: Update Symfony dependencies if using newer ParaTest.

3. Deprecation Warnings:

   • Use --display-all-issues to show deprecations:

     vendor/bin/paratest --display-all-issues
     

Performance Optimization

1. Max Processes: Limit CPU usage with --max-processes:

   vendor/bin/paratest --max-processes=2  # Use 2 cores max
   

2. Do Not Fail: Skip failures for specific test types:

   vendor/bin/paratest --do-not-fail-on-risky --do-not-fail-on-incomplete
   

3. Useless Tests: Exclude skipped/useless tests from reports:

   vendor/bin/paratest --do-not-report-useless-tests