Pao Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev nunomaduro/pao
   

   Add to composer.json under require-dev if not using global install.

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="NunoMaduro\Pao\PaoServiceProvider" --tag="pao-config"
   

   Edit config/pao.php to define your preferred output format (e.g., json, tap, junit).

3. First Use Case Run tests with PAO in your phpunit.xml:

   <phpunit>
       <extensions>
           <extension class="NunoMaduro\Pao\Extensions\PaoExtension"/>
       </extensions>
   </phpunit>
   

   Execute tests:

   ./vendor/bin/phpunit --testdox-html --pao=json
   

   Output will now be formatted as JSON (or your chosen format) in tests/_output/.

Implementation Patterns

Workflow Integration

1. CI/CD Pipelines Use PAO to generate structured output for:

   • JUnit (GitHub Actions, GitLab CI): Enables test trend analysis.

     ./vendor/bin/phpunit --pao=junit
     

   • TAP (Perl-compatible): Useful for tools like prove or TAP::Harness.

     ./vendor/bin/phpunit --pao=tap
     

   • JSON: Parse test results programmatically in scripts.

     ./vendor/bin/phpunit --pao=json | jq '.tests'
     

2. Local Development

   • Debugging: Use --pao=json to inspect failed tests interactively:

     ./vendor/bin/phpunit --pao=json | grep -A 5 '"status":"failed"'
     

   • Custom Reports: Pipe output to tools like glow for colored JSON:

     ./vendor/bin/phpunit --pao=json | glow
     

3. Parallel Testing Configure PAO in parallel test suites (e.g., phpunit-parallel) by ensuring each worker writes to a unique output directory:

   ./vendor/bin/phpunit --pao=json --testdox-html --workers=4 --output-dir=tests/_output/worker_
   

Extension Points

• Custom Formats: Extend NunoMaduro\Pao\Output\OutputInterface to create new formats (e.g., Markdown or HTML).
• Pre/Post-Processing: Hook into PaoServiceProvider::boot() to modify output before writing.

Gotchas and Tips

Pitfalls

1. Output Directory Permissions Ensure tests/_output/ is writable:

   mkdir -p tests/_output && chmod -R 777 tests/_output
   

   Fix: Configure a custom path in config/pao.php:

   'output_dir' => storage_path('logs/pao'),
   

2. Conflicts with Other Extensions PAO may clash with phpunit-snapshot or phpunit-coverage. Solution:

   • Order extensions in phpunit.xml (PAO last).
   • Use --exclude-group=pao to skip PAO for specific tests.

3. JSON Parsing Issues

   • Empty Arrays: PAO may output [] for skipped tests. Handle in consumers:

     $output = json_decode(file_get_contents('tests/_output/results.json'), true);
     if (empty($output['tests'])) { /* Handle edge case */ }
     

   • UTF-8 Encoding: Ensure your terminal/editor supports UTF-8 for non-ASCII test names.

Debugging Tips

• Verbose Mode: Add --verbose to PAO commands to see raw test data:

  ./vendor/bin/phpunit --pao=json --verbose
  

• Log Output: Enable Laravel logging for PAO events in config/pao.php:

  'debug' => env('APP_DEBUG', false),
  

• Validate JSON: Use jsonlint.com to validate PAO JSON output.

Performance Quirks

• Large Test Suites: PAO adds ~10-15% overhead. For CI, consider:

  ./vendor/bin/phpunit --pao=junit --no-coverage  # Skip coverage if not needed
  

• Memory Limits: Increase memory_limit in php.ini if processing huge JSON outputs:

  memory_limit = 512M
  

Extension Tips

• Dynamic Output Paths: Use a closure in config/pao.php to set paths dynamically:

  'output_dir' => function () {
      return sys_get_temp_dir() . '/pao_' . date('Ymd');
  },
  

• Conditional Formatting: Skip PAO for specific environments:

  'enabled' => !app()->environment('production'),