Tester Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require draw/tester-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Draw\Bundle\TesterBundle\TesterBundle::class => ['test' => true],
   ];
   

2. First Use Case: Kernel Event Dispatcher Validation

   • Create a test class extending Symfony\Bundle\FrameworkBundle\Test\KernelTestCase.
   • Use the EventDispatcherTesterTrait to validate event listeners.
   • Run the test once to generate a baseline event_dispatcher.xml fixture.

   // tests/EventDispatcherTest.php
   namespace App\Tests;
   
   use Draw\Bundle\TesterBundle\EventDispatcher\EventDispatcherTesterTrait;
   use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
   
   class EventDispatcherTest extends KernelTestCase
   {
       use EventDispatcherTesterTrait;
   
       public function testEventDispatcherConfiguration(): void
       {
           $this->assertEventDispatcherConfiguration(
               __DIR__.'/fixtures/event_dispatcher.xml'
           );
       }
   }
   

3. Run the Test

   php bin/phpunit tests/EventDispatcherTest
   

   • On first run, the test generates event_dispatcher.xml in your fixtures directory.
   • Commit this file to version control.

Implementation Patterns

Workflow: Validating Kernel Components

1. Event Dispatcher Validation

   • Use EventDispatcherTesterTrait to assert that all event listeners/subcribers are correctly registered.
   • Ideal for CI/CD pipelines to catch accidental changes in event wiring.
   • Example:

     $this->assertEventDispatcherConfiguration(
         __DIR__.'/fixtures/event_dispatcher.xml',
         'event_dispatcher' // Optional: Custom service ID if not using default
     );
     

2. Service Container Validation (Future-Proofing)

   • The bundle hints at future traits for service validation (e.g., ServiceContainerTesterTrait).
   • Pattern: Extend KernelTestCase and use provided traits to assert service configurations.
   • Example (hypothetical):

     use Draw\Bundle\TesterBundle\ServiceContainer\ServiceContainerTesterTrait;
     
     class ServiceTest extends KernelTestCase
     {
         use ServiceContainerTesterTrait;
     
         public function testServiceConfiguration(): void
         {
             $this->assertServiceConfiguration(
                 __DIR__.'/fixtures/services.xml'
             );
         }
     }
     

3. Integration with Custom Test Suites

   • Combine with existing test suites (e.g., PHPUnit) to enforce consistency.
   • Useful for large applications where event listeners/subcribers are scattered across bundles.
   • Example: Run tests in a post-merge Git hook to catch misconfigurations early.

Integration Tips

1. Fixtures Management

   • Store generated XML fixtures (e.g., event_dispatcher.xml) in tests/fixtures/ or a dedicated config/ directory.
   • Use .gitignore for intermediate files (e.g., event_dispatcher.tmp.xml) but commit the finalized fixtures.

2. Customizing Assertions

   • Override the assertEventDispatcherConfiguration method to add custom validation logic (e.g., ignore specific listeners).
   • Example:

     protected function assertEventDispatcherConfiguration(string $fixturePath): void
     {
         $this->ignoreListeners(['kernel.request', 'some.ignored.listener']);
         parent::assertEventDispatcherConfiguration($fixturePath);
     }
     

3. Debugging

   • Use Symfony’s debug:event-dispatcher command to manually inspect the current state:

     php bin/console debug:event-dispatcher
     

   • Compare output with the fixture to identify discrepancies.

Gotchas and Tips

Pitfalls

1. Fixture Drift

   • Issue: Forgetting to update fixtures after changing event listeners/subcribers.
   • Fix: Run tests in CI/CD to fail fast. Use a pre-commit hook to warn about drift.
   • Example Hook (.git/hooks/pre-commit):

     #!/bin/sh
     php bin/phpunit --testdox-html=coverage.xml tests/EventDispatcherTest
     if [ $? -ne 0 ]; then
         echo "Event dispatcher test failed! Update fixtures or fix configuration."
         exit 1
     fi
     

2. Service ID Mismatches

   • Issue: Using a non-existent service ID in assertEventDispatcherConfiguration.
   • Fix: Defaults to 'event_dispatcher', but verify the correct ID with:

     php bin/console debug:container | grep event.dispatcher
     

3. Performance Overhead

   • Issue: Running event dispatcher tests in large applications may be slow.
   • Fix: Cache the fixture generation step or run tests selectively in CI.

Debugging Tips

1. Manual Fixture Generation

   • Regenerate fixtures manually with:

     php bin/console debug:event-dispatcher > event_dispatcher.xml
     

   • Compare with the committed fixture using diff or a visual diff tool.

2. Selective Testing

   • Focus tests on critical bundles first (e.g., SecurityBundle, DoctrineBundle).
   • Example:

     public function testSecurityEventListeners(): void
     {
         $this->assertEventDispatcherConfiguration(
             __DIR__.'/fixtures/security_events.xml',
             'event_dispatcher'
         );
     }
     

3. Extension Points

   • Missing Traits: The README mentions "work in progress" for other traits (e.g., command testing).
   • Workaround: Extend the bundle or contribute missing features (e.g., CommandTesterTrait).
   • Example Contribution:

     // src/EventDispatcher/CommandTesterTrait.php (hypothetical)
     trait CommandTesterTrait
     {
         public function assertCommandConfiguration(string $fixturePath): void
         {
             // Logic to validate commands...
         }
     }
     

Configuration Quirks

1. Bundle Loading Order

   • Ensure TesterBundle is loaded after your application bundles in config/bundles.php (Symfony 4+).
   • Example:

     return [
         // ...
         App\SomeBundle\SomeBundle::class => ['all' => true],
         Draw\Bundle\TesterBundle\TesterBundle::class => ['test' => true],
     ];
     

2. KernelTestCase Requirements

   • Tests must boot the kernel. Avoid using StaticTestCase or non-kernel tests.
   • Example of incorrect usage:

     // ❌ Wrong: StaticTestCase cannot access the kernel
     use Symfony\Bundle\FrameworkBundle\Test\StaticTestCase;
     

3. XML Fixture Format

   • Fixtures are generated in a specific XML format. Avoid manual edits unless necessary.
   • Example structure:

     <event-dispatcher>
         <listeners>
             <listener event="kernel.request" method="onKernelRequest" service="app.event_listener"/>
         </listeners>
         <subscribers>
             <subscriber service="app.event_subscriber"/>
         </subscribers>
     </event-dispatcher>