Test Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require microshop/test
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       MicroShop\Test\TestServiceProvider::class,
   ],
   

2. Publish Config

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

   Review config/test.php for default settings.

3. First Use Case: Basic Test Execution

   use MicroShop\Test\Facades\TestRunner;
   
   // Run a simple test
   $result = TestRunner::run('UserTest');
   dd($result); // Outputs test results (pass/fail, assertions, etc.)
   

4. Key Facades/Classes

   • TestRunner: Execute tests programmatically.
   • TestGenerator: Scaffold new test classes.
   • TestAssert: Custom assertions for MicroShop-specific logic.

Implementation Patterns

Workflow: Test-Driven Development (TDD) with MicroShop

1. Generate a Test Class

   TestGenerator::create('Feature\\User\\CreateUserTest', [
       'uses' => 'UserTestCase',
       'description' => 'Tests user creation flow',
   ]);
   

   Outputs a skeleton test file in tests/Feature/User/.

2. Integrate with Laravel’s Testing Extend MicroShop\Test\TestCase for shared setup:

   use MicroShop\Test\TestCase;
   
   class UserTestCase extends TestCase {
       protected function setUp(): void {
           parent::setUp();
           $this->user = User::factory()->create();
       }
   }
   

3. Programmatic Test Execution

   // Run all tests in a group
   $results = TestRunner::runGroup('user');
   
   // Filter by status
   $failed = $results->filterByStatus('failed');
   

4. Custom Assertions

   use MicroShop\Test\Facades\TestAssert;
   
   TestAssert::assertMicroShopResponse($response, 200, 'success');
   TestAssert::assertModelExists(User::class, ['email' => 'test@example.com']);
   

5. Hook into Application Events Use TestListener to trigger tests on deployments or CI:

   TestRunner::addListener(new SlackNotificationListener(config('test.slack_webhook')));
   

Integration Tips

• CI/CD Pipelines Add to .github/workflows/test.yml:

  - name: Run MicroShop Tests
    run: php artisan test:run --group=regression
  

• Database Transactions Enable in config/test.php:

  'database' => [
      'transactions' => true,
  ],
  

  Ensures tests run in isolated DB states.

• Parallel Testing Use TestRunner::parallel() for large test suites:

  TestRunner::parallel()->runGroup('integration');
  

Gotchas and Tips

Pitfalls

1. Database State Leakage

   • Issue: Tests may fail due to stale data if transactions are disabled.
   • Fix: Always enable transactions in config or manually rollback:

     $this->artisan('db:rollback')->run();
     

2. Facade Caching

   • Issue: TestRunner caches results by default, which can hide flaky tests.
   • Fix: Disable caching for debug:

     TestRunner::setCache(false);
     

3. Test Group Conflicts

   • Issue: Overlapping test groups (e.g., unit and api) may cause unintended execution.
   • Fix: Use explicit group names and document them in README.md.

4. Custom Assertions Overhead

   • Issue: MicroShop-specific assertions may slow down tests.
   • Fix: Use native PHPUnit assertions where possible and benchmark custom ones.

Debugging

1. Verbose Output Enable debug mode in config/test.php:

   'debug' => env('TEST_DEBUG', false),
   

   Logs detailed test execution steps to storage/logs/test.log.

2. Test Isolation If tests interfere, use TestRunner::isolate():

   TestRunner::isolate()->run('UserTest');
   

   Spins up a fresh Laravel instance for the test.

3. Mocking MicroShop Services Use the MicroShopMock helper:

   $this->mockMicroShopService('payment', function ($mock) {
       $mock->shouldReceive('charge')->andReturn(true);
   });
   

Extension Points

1. Custom Test Reporters Implement MicroShop\Test\Contracts\TestReporter:

   class CustomReporter implements TestReporter {
       public function report(array $results) {
           // Send to external system (e.g., Jira, Datadog)
       }
   }
   

   Register via:

   TestRunner::addReporter(new CustomReporter());
   

2. Dynamic Test Generation Extend TestGenerator to auto-generate tests from API specs:

   TestGenerator::fromOpenApi('api-spec.yaml');
   

3. Pre/Post Test Hooks Add setup/teardown logic:

   TestRunner::before(function () {
       // Seed test data
   });
   
   TestRunner::after(function () {
       // Cleanup
   });
   

Config Quirks

• Timezone Handling Tests may fail if timezone differs from production. Set in config/test.php:

  'timezone' => 'UTC',
  

• Environment Variables Use .env.testing for test-specific configs. Load via:

  TestRunner::loadEnvironment('.env.testing');
  

• Parallel Worker Limits Adjust in config/test.php:

  'parallel' => [
      'workers' => 4, // Default: CPU core count
  ],