Fastest Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev liuggio/fastest
   

   Or globally:

   composer global require liuggio/fastest
   

2. Basic Usage: Pipe test files to fastest with your test command:

   find tests/ -name "*Test.php" | ./vendor/liuggio/fastest/fastest "vendor/bin/phpunit {}"
   

   Or use the bin/ directory if configured:

   find tests/ -name "*Test.php" | ./bin/fastest "bin/phpunit {}"
   

3. First Use Case: Run PHPUnit tests in parallel using database isolation for functional tests:

   find tests/Feature -name "*Test.php" | ./bin/fastest -b"php artisan migrate --env=testing --database=test_{p}" "bin/phpunit {}"
   

Implementation Patterns

Workflows

1. Parallel Test Execution:

   • Use find or ls to pipe test files:

     ls tests/Unit | ./bin/fastest "bin/phpunit {}"
     

   • Preserve order (if needed):

     ./bin/fastest -o "bin/phpunit {}"
     

2. Database Isolation for Functional Tests:

   • Leverage environment variables (ENV_TEST_CHANNEL_READABLE) to dynamically configure database names:

     // config/database.php
     'connections' => [
         'test_{p}' => [
             'url' => env('DATABASE_URL').'_test_'.env('ENV_TEST_CHANNEL_READABLE'),
         ],
     ],
     

   • Run migrations/fixtures per process:

     ./bin/fastest -b"php artisan migrate --env=testing_{p}" "bin/phpunit {}"
     

3. Code Coverage Merging:

   • Generate coverage files per test:

     find tests/ -name "*Test.php" | ./bin/fastest "bin/phpunit --coverage-text --coverage-clover=coverage/{n}.xml {}"
     

   • Merge with phpcov:

     phpcov merge coverage/ --html=coverage/merged
     

4. Behat Integration:

   • List scenarios for parallel execution:

     ./bin/behat --list-scenarios | ./bin/fastest "./bin/behat {}"
     

   • Add Behat extension to behat.yml:

     extensions:
         Liuggio\Fastest\Behat\ListFeaturesExtension\Extension: ~
     

5. Custom Commands:

   • Parallelize any CLI command (e.g., linting, static analysis):

     find src/ -name "*.php" | ./bin/fastest "phpstan analyze --memory-limit=1G {}"
     

Integration Tips

1. Symfony Integration:

   • Override Doctrine connection factories for database isolation:

     # config/packages/doctrine.yaml
     doctrine:
         dbal:
             connection_factory: Liuggio\Fastest\Doctrine\DBAL\ConnectionFactory
     

   • For SQLite, use __DBNAME__ placeholder in path:

     doctrine:
         dbal:
             driver: pdo_sqlite
             path: "%kernel.cache_dir%/__DBNAME__.sqlite"
     

2. Environment Setup:

   • Set ENV_TEST_CHANNEL_READABLE in your test environment (e.g., .env.testing):

     ENV_TEST_CHANNEL_READABLE=test_${ENV_TEST_CHANNEL}
     

3. CI/CD Pipelines:

   • Use --no-progress for cleaner logs:

     ./bin/fastest --no-progress "bin/phpunit {}"
     

   • Limit processes to avoid resource contention:

     ./bin/fastest -p4 "bin/phpunit {}"
     

4. Debugging:

   • Increase verbosity for troubleshooting:

     ./bin/fastest -vvv "bin/phpunit {}"
     

Gotchas and Tips

Pitfalls

1. Environment Variables:

   • Ensure variables_order in php.ini includes E (e.g., EAC):

     variables_order = "EGPCS"
     

   • Test commands in PATH may fail if environment variables are not set correctly.

2. Database Connections:

   • SQLite: Replace __DBNAME__ with ENV_TEST_CHANNEL_READABLE in the path.
   • Doctrine: Clear caches per process if using --rerun-failed:

     ./bin/fastest -b"php artisan cache:clear" -r "bin/phpunit {}"
     

3. Behat Scenarios:

   • Avoid --list-scenarios for scenario outlines (duplicate test names in JUnit reports).
   • Use --list-features for safer JUnit merging:

     ./bin/behat --list-features | ./bin/fastest "./bin/behat {}"
     

4. Resource Limits:

   • Parallel processes may hit memory limits. Monitor with:

     ./bin/fastest -p2 "bin/phpunit --memory-limit=512M {}"
     

5. Order Dependencies:

   • Disable randomization (-o) if tests assume execution order (e.g., setup/teardown).

Debugging Tips

1. Verbose Output:

   • Use -vvv to debug process assignment:

     ./bin/fastest -vvv "bin/phpunit {}"
     

2. Process Isolation:

   • Check environment variables in tests:

     dd([
         'Channel' => getenv('ENV_TEST_CHANNEL_READABLE'),
         'Test File' => getenv('ENV_TEST_ARGUMENT'),
     ]);
     

3. Failed Tests:

   • Rerun only failed tests with -r:

     ./bin/fastest -r "bin/phpunit {}"
     

4. Custom Placeholders:

   • Use {p}, {n}, or {} in commands for dynamic values:

     ./bin/fastest "bin/phpunit --filter={n} {}"
     

Extension Points

1. Custom Adapters:

   • Extend Liuggio\Fastest\Doctrine\DBAL\ConnectionFactory for other ORMs (e.g., Eloquent).

2. Pre/Post Commands:

   • Chain commands with -b (before) or add post-processing scripts:

     ./bin/fastest -b"php artisan migrate" "bin/phpunit {}" && php artisan optimize
     

3. Progress Bar:

   • Disable with --no-progress for CI output:

     ./bin/fastest --no-progress "bin/phpunit {}"
     

4. Cross-Platform:

   • Use absolute paths for commands to avoid PATH issues:

     ./bin/fastest "/full/path/to/phpunit {}"