Paratest Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev brianium/paratest
   

   Ensure your phpunit version is up-to-date (ParaTest requires the latest PHPUnit).

2. First Run: Replace your existing phpunit command with:

   vendor/bin/paratest
   

   This defaults to parallelizing tests by TestCase (entire test classes).

3. Functional-Level Parallelism: For finer-grained parallelism (individual test methods), use:

   vendor/bin/paratest --functional
   

4. Verify Integration: Run a single test file to confirm:

   vendor/bin/paratest tests/Feature/ExampleTest.php
   

Key First Use Case

Speed up CI/CD pipelines by reducing test execution time. For example:

# Run all tests in parallel (4 processes)
vendor/bin/paratest --processes=4

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline: Replace phpunit with paratest in your workflow (GitHub Actions, GitLab CI, etc.):

   # GitHub Actions example
   - name: Run tests in parallel
     run: vendor/bin/paratest --processes=auto --coverage-text
   

2. Local Development:

   • Use --processes=auto to auto-detect CPU cores.
   • Combine with coverage:

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

3. Test Sharding: Split tests into chunks for large suites:

   # Shard tests into 3 chunks
   vendor/bin/paratest --shard=3
   

   Or use custom distributions:

   # Round-robin distribution
   vendor/bin/paratest --shard-test-distribution=round-robin --shard=4
   

4. Database Isolation: Leverage TEST_TOKEN for unique DB connections:

   $dbName = getenv('TEST_TOKEN') ? "testdb_{$token}" : 'testdb';
   

Common Patterns

• Test Initialization: Use filesystem locks for one-time setup (see README).
• Coverage Reporting: Combine coverage from parallel runs:

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

• Debugging: Reproduce failed subprocesses:

  vendor/bin/paratest --verbose
  

  Then copy the subprocess command from the output and run it manually.

IDE Integration (PHPStorm)

1. Configure a new PHPUnit run configuration:
   • Interpreter options: ./vendor/bin/paratest_for_phpstorm
   • Test runner options: --processes=4 --coverage-clover=coverage.clover
2. Use the ParaTest configuration for parallel runs.

Gotchas and Tips

Pitfalls

1. Static State Issues:

   • Problem: Static variables/methods in test classes behave per-process (not shared).
   • Fix: Move shared logic to non-test classes or use filesystem locks.

2. Coverage Quirks:

   • PCov/xDebug: Ensure proper activation:

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

   • Coverage Exclusion: Use --exclude-source-from-xml-coverage to filter paths.

3. Test Dependencies:

   • Problem: Tests relying on global state (e.g., singletons) may fail.
   • Fix: Reset state per-test or use TEST_TOKEN for isolation.

4. Subprocess Failures:

   • Debugging: Use --verbose to inspect subprocess commands. Remove --printer flags temporarily to see raw PHPUnit output.

5. PHPUnit Version Lock:

   • ParaTest only supports the latest PHPUnit. Avoid mixing versions.

Debugging Tips

• Isolate Failing Tests: Run a single test class with --processes=1 to debug:

  vendor/bin/paratest tests/Feature/ExampleTest.php --processes=1
  

• Check Shard Logic: If tests hang, verify shard distribution with --shard-test-distribution=random.
• Resource Limits: Use --max-processes to cap CPU usage:

  vendor/bin/paratest --max-processes=2
  

Extension Points

1. Custom Test Distribution: Extend sharding logic by implementing a custom TestDistributionStrategy (see source).

2. Pre/Post-Test Hooks: Use PHPUnit events (e.g., TestRunner\Started) for setup/teardown. ParaTest respects these events.

3. Environment Variables: Override defaults via .env or CI variables:

   PARATEST_PROCESSES=4 vendor/bin/paratest
   

Configuration Quirks

• --do-not-fail-on-* Options: Use to skip failures for specific test types (e.g., --do-not-fail-on-risky).
• TestDox Support: Generate reports with:

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

• Symfony Integration: ParaTest supports Symfony 8+ but drops support for older versions. Ensure your symfony/* packages are compatible.

Performance Tuning

• Optimal Process Count: Start with --processes=auto (defaults to CPU cores). Adjust based on test complexity.
• Memory Usage: Monitor memory spikes with --max-memory=512M to limit per-process usage.
• Test Grouping: Group tests by @group annotations for logical parallelism:

  vendor/bin/paratest --groups=unit,integration