Test Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle via Composer:

   composer require chesteroni/test-bundle
   

   Enable the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Chesteroni\TestBundle\ChesteroniTestBundle::class => ['all' => true],
   ];
   

2. First Use Case The bundle provides a TestCase base class for writing PHPUnit tests. Extend it in your test classes:

   use Chesteroni\TestBundle\Test\TestCase;
   
   class ExampleTest extends TestCase
   {
       public function testExample()
       {
           $this->assertTrue(true);
       }
   }
   

3. Where to Look First

   • Documentation: Check the README.md for basic setup and features.
   • TestCase Class: Inspect src/Test/TestCase.php for built-in assertions, helpers, or overrides.
   • Configuration: Look for config/packages/chesteroni_test.yaml (if provided) for customizable settings.

Implementation Patterns

Usage Patterns

1. Base Test Class Extend Chesteroni\TestBundle\Test\TestCase for all functional/unit tests to leverage shared functionality (e.g., database transactions, fixtures, or custom assertions).

2. Fixtures and Data Loading If the bundle supports fixtures (common in Symfony test bundles), load them in setUp():

   protected function setUp(): void
   {
       parent::setUp();
       $this->loadFixtures(['app:fixtures/user.yml']);
   }
   

3. Database Transactions Use the bundle’s transaction handling to avoid test pollution:

   public function testDatabaseOperations()
   {
       $this->beginTransaction();
       // Test logic here
       $this->rollBack();
   }
   

4. Custom Assertions Add custom assertions by overriding methods in your test class or extending the TestCase:

   protected function assertCustomCondition($condition)
   {
       $this->assertTrue($condition, 'Custom condition failed');
   }
   

5. Integration with Symfony Components Leverage Symfony’s Kernel or Container access (if provided by the bundle):

   public function testService()
   {
       $service = $this->getContainer()->get('app.service');
       $this->assertInstanceOf(SomeClass::class, $service);
   }
   

Workflows

1. Unit Testing Workflow

   • Write tests extending TestCase.
   • Use built-in helpers (e.g., createMock(), assertDatabaseHas() if available).
   • Run tests with PHPUnit:

     ./vendor/bin/phpunit
     

2. Functional Testing Workflow

   • Extend TestCase and use Symfony’s Client or KernelBrowser (if supported):

     public function testHomepage()
     {
         $client = static::createClient();
         $client->request('GET', '/');
         $this->assertResponseStatusCodeSame(200);
     }
     

3. CI/CD Integration Configure PHPUnit in phpunit.xml.dist to use the bundle’s test suite:

   <phpunit>
       <extensions>
           <extension class="Chesteroni\TestBundle\Test\Extension\ExampleExtension"/>
       </extensions>
   </phpunit>
   

Gotchas and Tips

Pitfalls

1. Lack of Documentation

   • The bundle has no stars or dependents, suggesting limited adoption. Assume minimal documentation; inspect the source code (src/) for undocumented features.
   • Example: If assertDatabaseHas() is missing, check if the bundle provides a custom trait or method.

2. Symfony-Specific Assumptions

   • The bundle may rely on Symfony components (e.g., Kernel, Container). If using Laravel, you’ll need to adapt or avoid this bundle entirely.
   • Laravel Alternative: Use Laravel’s built-in TestCase or packages like laravel/testbench for Symfony integration.

3. Configuration Overrides

   • If the bundle provides YAML/configuration files, ensure they don’t conflict with Laravel’s existing setup. Override or disable them if needed:

     // config/app.php
     'providers' => [
         // Avoid adding ChesteroniTestBundle if not needed.
     ];
     

4. Transaction Handling

   • If the bundle uses database transactions, ensure your Laravel environment supports them (e.g., SQLite or MySQL with DB_CONNECTION=sqlite in .env for testing).
   • Laravel’s default DatabaseTransactions trait may conflict; test thoroughly.

5. Extension Points

   • The bundle may lack Laravel-specific features (e.g., Eloquent model assertions). Extend the TestCase manually:

     use Illuminate\Foundation\Testing\TestCase as LaravelTestCase;
     
     class CustomTestCase extends ChesteroniTestCase
     {
         use LaravelTestCase::assertDatabaseHasTrait;
     }
     

Debugging Tips

1. Check for Deprecated Methods

   • The bundle might use Symfony-specific methods (e.g., getContainer()). Replace with Laravel equivalents:

     // Symfony:
     $container = $this->getContainer();
     // Laravel:
     $container = $this->app;
     

2. Enable Debugging

   • Add debug output in TestCase to trace execution:

     protected function setUp(): void
     {
         error_log('TestBundle TestCase setup called');
         parent::setUp();
     }
     

3. Isolate Dependencies

   • If the bundle pulls in Symfony packages, use composer require symfony/* explicitly to avoid version conflicts.

4. Fallback to PHPUnit

   • For unsupported features, fall back to raw PHPUnit:

     $this->assertTrue($condition, 'Message');
     

Extension Points

1. Custom Test Traits Add Laravel-specific traits to the TestCase:

   namespace Chesteroni\TestBundle\Test;
   
   use Illuminate\Foundation\Testing\RefreshDatabase;
   
   trait LaravelRefreshDatabase
   {
       use RefreshDatabase;
   }
   
   class TestCase extends \PHPUnit\Framework\TestCase
   {
       use LaravelRefreshDatabase;
   }
   

2. Override Assertions Extend the TestCase to add Laravel-specific assertions:

   protected function assertModelExists($modelClass, $attributes = [])
   {
       $this->assertDatabaseHas((new $modelClass)->getTable(), $attributes);
   }
   

3. Event Listeners If the bundle dispatches events, listen in Laravel’s EventServiceProvider:

   protected $listen = [
       'chesteroni.test.event' => [
           \App\Listeners\TestEventListener::class,
       ],
   ];