Beautify Specify Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require barthy-koeln/beautify-specify --dev
   

   Register the service provider in config/app.php under providers:

   BarthyKoeln\BeautifySpecify\BeautifySpecifyServiceProvider::class,
   

2. First Use Case Run PHPUnit with the --specify flag (if not already configured):

   ./vendor/bin/phpunit --specify
   

   The package will automatically enhance the output with colors and structured formatting.

3. Where to Look First

   • Configuration: Check config/beautify-specify.php (if generated) for customization options.
   • Documentation: Review the package’s README.md (if available) for basic usage examples.
   • Source Code: Inspect src/BeautifySpecifyServiceProvider.php and src/BeautifySpecify.php for core logic.

Implementation Patterns

Workflow Integration

1. Automated Testing Workflow

   • Use the package in CI/CD pipelines to improve test output readability.
   • Example CI command (GitHub Actions):

     - run: ./vendor/bin/phpunit --specify --coverage-text
     

2. Customizing Output

   • Override default colors or formatting via config:

     // config/beautify-specify.php
     return [
         'colors' => [
             'passed' => '#2ecc71', // Green
             'failed' => '#e74c3c', // Red
             'skipped' => '#f39c12', // Orange
         ],
     ];
     

3. Integration with Laravel Testing

   • Use with Laravel’s phpunit.xml by extending the default configuration:

     <phpunit>
         <extensions>
             <extension class="BarthyKoeln\BeautifySpecify\BeautifySpecifyExtension"/>
         </extensions>
     </phpunit>
     

4. Dynamic Test Grouping

   • Leverage PHPUnit’s @group annotations to visually separate test suites in the output.

Gotchas and Tips

Pitfalls

1. Archived Package

   • The package is archived (no active maintenance). Use cautiously in production or long-term projects.
   • Consider forking or replacing if critical bugs arise.

2. Color Compatibility

   • Some terminals (e.g., Windows CMD) may not support ANSI colors. Test in your target environment.
   • Fallback: Use --no-colors flag if colors cause issues.

3. Configuration Overrides

   • If the config/beautify-specify.php file isn’t generated, manually create it in the config directory.
   • Ensure the config is published first:

     php artisan vendor:publish --provider="BarthyKoeln\BeautifySpecify\BeautifySpecifyServiceProvider"
     

4. PHPUnit Version Conflicts

   • The package may not support newer PHPUnit versions (last release in 2021). Test thoroughly with your PHPUnit version.

Debugging Tips

1. Disable Formatting Temporarily disable the package to isolate issues:

   ./vendor/bin/phpunit --specify --no-beautify-specify
   

   (Note: This flag may not exist; check the package’s source for disable options.)

2. Log Output Add debug logs to the BeautifySpecify class to trace formatting logic:

   \Log::debug('Specify output:', ['raw' => $rawOutput]);
   

3. Fallback to Plain Output If the package fails, revert to default PHPUnit output by removing the service provider or using a plain PHPUnit extension.

Extension Points

1. Custom Formatters Extend the BarthyKoeln\BeautifySpecify\Formatters\SpecifyFormatter class to add new output styles (e.g., emojis, icons).

2. Event Listeners Hook into PHPUnit’s events (e.g., TestListener) to pre-process output before formatting:

   PHPUnit\Runner\AfterLastTestMethod::class => function ($event) {
       // Modify $event->result before beautification
   };
   

3. Template Overrides Replace the default output template by binding a custom formatter in the service provider:

   $this->app->bind(
       'beautify-specify.formatter',
       CustomFormatter::class
   );