Service Test Helper Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require dayspring-tech/service-test-helper
   

   Register the service provider in config/app.php under providers:

   DayspringTech\ServiceTestHelper\ServiceTestHelperServiceProvider::class,
   

2. First Use Case Test a service class with mock dependencies:

   use DayspringTech\ServiceTestHelper\ServiceTestHelper;
   
   public function testExampleService()
   {
       $service = new ExampleService();
       $helper = new ServiceTestHelper($service);
   
       // Mock a dependency
       $mockDependency = $this->createMock(DependencyInterface::class);
       $helper->mock(DependencyInterface::class, $mockDependency);
   
       // Execute and assert
       $result = $service->doSomething();
       $this->assertEquals('expected', $result);
   }
   

3. Where to Look First

   • Documentation: Check the README for basic usage.
   • Source Code: Focus on src/ServiceTestHelper.php for core functionality.
   • Tests: Review tests/ for real-world examples (if available).

Implementation Patterns

Common Workflows

1. Mocking Dependencies Replace real dependencies with mocks for isolated testing:

   $helper->mock(RepositoryInterface::class, $this->createMock(RepositoryInterface::class));
   

2. Stubbing Methods Stub specific methods on dependencies:

   $mock = $this->createMock(LoggerInterface::class);
   $mock->method('log')->willReturn(true);
   $helper->mock(LoggerInterface::class, $mock);
   

3. Testing Service Lifecycle Verify constructor injection and method calls:

   $helper->verifyConstructorInjection(DependencyInterface::class);
   $helper->verifyMethodCall('doSomething', [$arg1, $arg2]);
   

4. Integration with Laravel Use with Laravel’s built-in testing tools (e.g., Mockery or PHPUnit):

   use Illuminate\Foundation\Testing\TestCase;
   
   class ExampleServiceTest extends TestCase
   {
       use ServiceTestHelperTrait; // If provided
   
       public function testService()
       {
           $helper = new ServiceTestHelper(new ExampleService());
           // ... test logic
       }
   }
   

5. Testing Exception Handling Assert exceptions are thrown correctly:

   $mock->method('fetchData')->willThrowException(new \RuntimeException('Error'));
   $this->expectException(\RuntimeException::class);
   $service->fetchData();
   

Gotchas and Tips

Pitfalls

1. Static Method Limitations The package may not handle static method calls natively. Workaround:

   // Manually stub static calls or refactor to instance methods.
   

2. Circular Dependencies Mocking services with circular dependencies requires manual setup:

   $mockA = $this->createMock(ServiceA::class);
   $mockB = $this->createMock(ServiceB::class);
   $mockA->method('getB')->willReturn($mockB);
   $mockB->method('getA')->willReturn($mockA);
   $helper->mock(ServiceA::class, $mockA);
   

3. Laravel Service Container Conflicts Avoid mixing with Laravel’s container bindings unless explicitly supported:

   // Prefer manual mocking over container binding in tests.
   

4. Magic Methods Services using __call or __callStatic may need custom handling.

Debugging Tips

• Verify Mocks: Use var_dump($helper->getMock(DependencyInterface::class)) to inspect mocks.
• Check Method Calls: Use verifyMethodCall() to ensure expected interactions:

  $helper->verifyMethodCall('save', [$entity]);
  

• Enable Strict Typing: Add strict_types=1 to PHP files to catch type-related issues early.

Extension Points

1. Custom Matchers Extend the helper to support custom PHPUnit matchers:

   $helper->extendMatcher('customMatcher', function ($actual, $expected) {
       return $actual === $expected;
   });
   

2. Trait Integration If the package provides a trait (e.g., ServiceTestHelperTrait), use it in test classes:

   use DayspringTech\ServiceTestHelper\ServiceTestHelperTrait;
   
   class ExampleServiceTest extends TestCase
   {
       use ServiceTestHelperTrait;
   }
   

3. Logging Interactions Log method calls for debugging:

   $helper->enableCallLogging();
   // Later, inspect logs with $helper->getCallLog().
   

4. Partial Mocking Use partial mocks for services with complex dependencies:

   $partialMock = $this->getMockBuilder(ComplexService::class)
       ->disableOriginalConstructor()
       ->onlyMethods(['methodToMock'])
       ->getMock();
   $helper->mock(ComplexService::class, $partialMock);