Test Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require axstrad/test
   

   Publish the config (if available) with:

   php artisan vendor:publish --provider="Axstrad\Test\TestServiceProvider" --tag="config"
   

2. First Use Case The package likely provides a base TestCase class for writing unit/feature tests. Extend it in your test classes:

   use Axstrad\Test\TestCase;
   
   class ExampleTest extends TestCase
   {
       public function test_example()
       {
           $this->assertTrue(true); // Basic assertion
       }
   }
   

3. Where to Look First

   • Check the src/TestCase.php for core functionality (e.g., trait inclusions, helper methods).
   • Review config/test.php (if published) for customizable settings like default assertions or mocking behavior.
   • Explore tests/ in the package repo for usage examples (if provided).

Implementation Patterns

Core Workflows

1. Base Test Class Extension Replace Laravel’s default TestCase with Axstrad\Test\TestCase for consistent test setup:

   // phpunit.xml
   <testsuites>
       <testsuite name="Application Test Suite">
           <directory suffix="Test.php">./tests/</directory>
       </testsuite>
   </testsuites>
   

2. Helper Methods Leverage package-provided traits (e.g., AssertsHttp, MocksDatabase) for DRY test code:

   use Axstrad\Test\Traits\AssertsHttp;
   
   class UserTest extends TestCase
   {
       use AssertsHttp;
   
       public function test_create_user()
       {
           $this->postJson('/users', ['name' => 'John'])
                ->assertCreated()
                ->assertJsonStructure(['data' => ['id', 'name']]);
       }
   }
   

3. Mocking and Factories Use built-in mocking utilities (if available) to avoid repetitive create()/factory() calls:

   public function test_user_creation_with_mock()
   {
       $mockUser = $this->mockUser(['email' => 'test@example.com']);
       $this->assertDatabaseHas('users', $mockUser->toArray());
   }
   

4. Custom Assertions Extend or override assertions in a dedicated TestHelper class:

   use Axstrad\Test\TestCase;
   
   class CustomTestCase extends TestCase
   {
       protected function assertCustomResponse($response, $expected)
       {
           // Custom logic
       }
   }
   

Integration Tips

• Laravel Mixins: If the package supports mixins (e.g., for HttpTests), integrate them into your createApplication():

  protected function createApplication()
  {
      $app = require __DIR__.'/../bootstrap/app.php';
      $app->make(Axstrad\Test\TestServiceProvider::class)->register();
      return $app;
  }
  

• Database Transactions: Use the package’s transaction helpers to avoid test pollution:

  public function setUp(): void
  {
      parent::setUp();
      $this->beginDatabaseTransaction();
  }
  

Gotchas and Tips

Pitfalls

1. Missing Documentation

   • The package lacks stars/dependents, so assume minimal docs. Inspect TestCase.php for undocumented methods.
   • Example: If assertCustom() exists but isn’t documented, check its usage in the package’s tests.

2. Configuration Overrides

   • If the package publishes config, ensure your config/test.php doesn’t conflict with defaults:

     // Avoid:
     'assert_strict' => false, // If package expects true
     

   • Test config changes with a simple assertion:

     $this->assertEquals(config('test.assert_strict'), true);
     

3. Trait Conflicts

   • Avoid naming collisions with Laravel’s built-in traits (e.g., RefreshDatabase). Prefix custom traits:

     use Axstrad\Test\Traits\CustomRefreshDatabase as RefreshDatabase;
     

4. Mocking Quirks

   • If the package provides mocking helpers, verify they play well with Laravel’s Mockery:

     // Potential issue: Mocks may not respect Laravel’s service container bindings.
     $mock = $this->mock(User::class);
     $this->assertInstanceOf(User::class, $mock);
     

Debugging

• Assertion Failures: Use dd() or dump() from the package’s TestCase to inspect state:

  $this->dumpResponse($response); // Hypothetical helper
  

• Transaction Rollbacks: If tests fail silently, enable debug mode in phpunit.xml:

  <php>
      <server name="APP_DEBUG" value="true"/>
  </php>
  

Extension Points

1. Custom Traits Extend the package’s TestCase to add domain-specific helpers:

   namespace Tests;
   
   use Axstrad\Test\TestCase;
   
   trait AssertsApiTokens
   {
       public function assertTokenValid($response)
       {
           $response->assertHeader('Authorization', 'Bearer *');
       }
   }
   
   class ApiTestCase extends TestCase
   {
       use AssertsApiTokens;
   }
   

2. Service Provider Hooks Bind custom test services in the package’s TestServiceProvider:

   public function register()
   {
       $this->app->singleton(TestService::class, function () {
           return new TestService(config('test.custom_setting'));
       });
   }
   

3. Event Listeners Attach listeners to test lifecycle events (e.g., TestCase::booting()):

   TestCase::booting(function () {
       if (app()->environment('testing')) {
           // Setup shared test data
       }
   });
   

Performance Tips

• Skip Heavy Setup: Use self::skipIf() to bypass tests in CI:

  public static function skipIf(): bool
  {
      return app()->environment('ci') && !config('test.run_heavy_tests');
  }
  

• Parallel Testing: Ensure the package’s TestCase supports parallel runs (check for static state).