Test Support Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require tipoff/test-support --dev
   

   Register the service provider in config/app.php under providers (if not auto-discovered):

   Tipoff\TestSupport\TestSupportServiceProvider::class,
   

2. First Use Case: Mocking External Services Use the MockExternalService trait in your test class to simulate API calls or third-party services:

   use Tipoff\TestSupport\Traits\MockExternalService;
   
   class MyTest extends TestCase
   {
       use MockExternalService;
   
       public function test_something()
       {
           $this->mockExternalService('http://api.example.com', [
               'response' => 'mocked_data'
           ]);
   
           // Assertions...
       }
   }
   

   Windows Blade Testing Fix The package now includes a Laravel fix for Blade testing on Windows environments. Ensure your test environment is properly configured to leverage this improvement.

3. Key Files to Explore

   • src/Traits/MockExternalService.php – Core trait for mocking HTTP requests.
   • src/Traits/Assertions.php – Custom assertions for testing package behavior.
   • src/Helpers/TestHelper.php – Utility functions for common test scenarios.
   • src/WindowsBladeFix/BladeWindowsFix.php – New helper for Blade testing on Windows.

Implementation Patterns

Workflows

1. Mocking HTTP Requests Replace real HTTP calls with predefined responses:

   $this->mockExternalService('https://api.example.com/users', [
       'status' => 200,
       'body'   => json_encode(['id' => 1, 'name' => 'Test User']),
   ]);
   

2. Testing Package Dependencies Use the TestPackageDependency trait to isolate package tests:

   use Tipoff\TestSupport\Traits\TestPackageDependency;
   
   class MyPackageTest extends TestCase
   {
       use TestPackageDependency;
   
       protected function setUp(): void
       {
           $this->mockDependency('vendor/package', [
               'method' => 'someMethod',
               'return' => 'mocked_value',
           ]);
       }
   }
   

3. Custom Assertions Extend built-in assertions for package-specific logic:

   $this->assertPackageExceptionThrown(
       fn() => MyPackage::doSomething(),
       MyPackageException::class,
       'Expected error message'
   );
   

4. Blade Testing on Windows Use the new Blade fix for Windows environments to avoid common path resolution issues:

   use Tipoff\TestSupport\WindowsBladeFix\BladeWindowsFix;
   
   class BladeTest extends TestCase
   {
       use BladeWindowsFix;
   
       public function test_blade_rendering_on_windows()
       {
           $this->setWindowsBladePaths();
           // Test Blade rendering logic...
       }
   }
   

Integration Tips

• Laravel Integration: Works seamlessly with Laravel’s testing tools (e.g., Http::fake() can be combined with mockExternalService).
• Database Testing: Use TestHelper::refreshDatabase() for clean state between tests.
• Configuration Overrides: Override package configs in tests via TestHelper::overrideConfig():

  TestHelper::overrideConfig('package.key', 'test_value');
  

• Windows-Specific Blade Paths: Ensure your test environment uses the setWindowsBladePaths() method when testing Blade templates on Windows.

Gotchas and Tips

Pitfalls

1. Mock Scope Leakage Mocks defined in setUp() persist across tests unless cleared. Use:

   $this->clearMocks();
   

   after each test to avoid unintended side effects.

2. HTTP Mock Matching Mocks are matched by exact URL. Use wildcards sparingly (e.g., 'https://api.example.com/*' may not work as expected).

3. Static Method Mocking The package does not natively mock static methods. Use PHPUnit’s getMockBuilder() as a fallback:

   $mock = $this->getMockBuilder(StaticClass::class)
       ->onlyMethods(['staticMethod'])
       ->getMock();
   

4. Blade Path Resolution on Windows If you encounter Blade path resolution issues on Windows, ensure you call setWindowsBladePaths() in your test setup. Failure to do so may result in incorrect path handling.

Debugging

• Verify Mocks: Use TestHelper::dumpMocks() to inspect active mocks:

  $this->dumpMocks(); // Outputs all registered mocks to console.
  

• Log HTTP Requests: Enable debug mode in config/test-support.php:

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

• Blade Debugging on Windows: Use BladeWindowsFix::logBladePaths() to debug path resolution issues:

  BladeWindowsFix::logBladePaths();
  

Extension Points

1. Custom Mock Providers Extend Tipoff\TestSupport\Contracts\MockProvider to support new services:

   class CustomMockProvider implements MockProvider
   {
       public function mock($service, $response)
       {
           // Custom logic...
       }
   }
   

   Register via the service provider.

2. Assertion Extensions Add custom assertions by publishing the package’s config:

   php artisan vendor:publish --provider="Tipoff\TestSupport\TestSupportServiceProvider"
   

   Then extend config/test-support.php under assertions.

3. Database Seed Overrides Override seeds for specific tests:

   TestHelper::seedDatabase(['CustomSeeder']);
   

4. Windows-Specific Blade Extensions Extend the BladeWindowsFix trait to add custom path resolution logic for your project:

   class CustomBladeWindowsFix extends BladeWindowsFix
   {
       protected function getCustomWindowsPaths()
       {
           return [
               'custom/path' => 'C:\custom\path',
           ];
       }
   }
   

   Use this custom trait in your test classes.