Waesel Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev dab-libs/waesel-bundle
   

   Ensure the bundle is enabled in config/bundles.php (Symfony 5+).

2. First Use Case:

   • Create a fixture class implementing Fixture to define test data.
   • Use the fixture in a test case by extending WeaselTestCase (or manually bootstrapping the bundle).
   • Example:

     use DabLibs\WeaselBundle\Test\WeaselTestCase;
     
     class FindPetsTest extends WeaselTestCase
     {
         protected function getFixtures(): array
         {
             return [new FindPets_Fixture($this->getService('create_pet'))];
         }
     
         public function testFindPetsByName()
         {
             $service = $this->getService('find_pets');
             $pets = $service->do(null, 'cat');
             $this->assertCount(2, $pets); // pet1 (cat) + pet2 (cat)
         }
     }
     

3. Key Files to Explore:

   • src/Test/WeaselTestCase.php (base test class).
   • src/Fixture/FixtureInterface.php (fixture contract).
   • src/WeaselBundle.php (bundle configuration).

Implementation Patterns

Workflows

1. Fixture-Based Testing:

   • Define fixtures for isolated test states (e.g., User_Fixture, Order_Fixture).
   • Reuse fixtures across tests by returning them in getFixtures().
   • Example:

     protected function getFixtures(): array
     {
         return [
             new User_Fixture($this->getService('user_repository')),
             new Order_Fixture($this->getService('order_repository')),
         ];
     }
     

2. Service Injection:

   • Access Symfony services via $this->getService('service_id') in tests.
   • Avoid hardcoding container references; use dependency injection in fixtures.

3. Test Lifecycle:

   • Fixtures run once per test class (not per test method) by default.
   • Override WeaselTestCase::setUp() to customize behavior (e.g., per-test fixture resets).

4. Database Transactions:

   • Weasel automatically rolls back transactions after tests (Symfony’s DatabaseTestCase behavior).
   • No manual cleanup needed for fixtures.

Integration Tips

• Combine with PHPUnit:

  use DabLibs\WeaselBundle\Test\WeaselTestCase;
  use PHPUnit\Framework\TestCase;
  
  class HybridTest extends WeaselTestCase & TestCase { ... }
  

• Mock External Services: Replace real services in fixtures with mocks:

  $this->createMock(ExternalApi::class);
  

• Dynamic Fixtures: Use factory methods in fixtures to generate varied test data:

  public function createData(): void {
      $this->pet1 = $this->createPet->do('pet_' . uniqid(), Pet::CAT);
  }
  

Gotchas and Tips

Pitfalls

1. Fixture Scope:

   • Fixtures run once per test class, not per method. Reset critical state in tearDown() if needed.
   • Example:

     protected function tearDown(): void
     {
         $this->getService('cache')->clear();
         parent::tearDown();
     }
     

2. Service Unavailability:

   • If getService() fails, verify:
     • The service is tagged as public in Symfony’s container.
     • The bundle is properly registered in config/bundles.php.

3. Database Constraints:

   • Weasel does not handle foreign key violations automatically. Ensure fixtures respect DB constraints.

4. Legacy Symfony:

   • The bundle assumes Symfony 5+. For older versions, manually bootstrap the bundle or use a wrapper.

Debugging

• Fixture Failures:
  • Check createData() for exceptions. Use try-catch to log errors:

    public function createData(): void {
        try {
            $this->pet1 = $this->createPet->do('pet1', Pet::CAT);
        } catch (\Exception $e) {
            $this->fail('Fixture creation failed: ' . $e->getMessage());
        }
    }
    

• Service Not Found:
  • Run php bin/console debug:container to verify service IDs.

Extension Points

1. Custom Fixture Loaders:
   • Extend WeaselTestCase to add pre/post-fixture logic:

     class CustomTestCase extends WeaselTestCase {
         protected function loadFixtures(array $fixtures): void {
             // Custom logic (e.g., parallel fixture loading)
             parent::loadFixtures($fixtures);
         }
     }
     

2. Event Listeners:
   • Attach listeners to weasel.fixture.load or weasel.fixture.create events (if the bundle supports them).
3. Parallel Testing:
   • Fixtures are not thread-safe by default. Use separate databases or disable shared state for parallel runs:

     // In phpunit.xml
     <php>
         <server name="WEASEL_PARALLEL" value="1"/>
     </php>