Pact Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require buero/pact-bundle
   

   Register the bundle in config/app.php under extra.bundles:

   Buero\PactBundle\PactBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=pact-config
   

   Update config/pact.php with your Pact Broker URL and consumer/provider details.

3. First Use Case: Consumer Contract Testing Write a test in tests/Feature/PactTests:

   use Buero\PactBundle\Tests\PactTestCase;
   
   class MyServicePactTest extends PactTestCase
   {
       public function test_service_interaction()
       {
           $this->pact('my-service-provider')
                ->given('a valid request')
                ->expects()
                    ->atLeastOne()
                    ->get('/api/endpoint')
                    ->willRespondWith(200, ['data' => 'test'])
                ->verify();
       }
   }
   

   Run with:

   php artisan pact:test
   

Implementation Patterns

Workflow: Pact Contract Testing

1. Define Provider Contracts Use annotations in provider code to document expected interactions:

   /**
    * @PactContract(
    *     name="my-service-provider",
    *     description="Handles user data requests"
    * )
    */
   class UserController extends Controller
   {
       // ...
   }
   

2. Consumer-Driven Development

   • Write consumer tests first (e.g., MyServicePactTest).
   • Generate provider stubs:

     php artisan pact:generate
     

   • Implement provider logic to match stubs.

3. Integration with CI Add to .github/workflows/pact.yml:

   - name: Pact Tests
     run: php artisan pact:test
   

Integration Tips

• Laravel HTTP Client: Use Http::pact() for Pact-aware requests:

  $response = Http::pact('my-service-provider')->get('/endpoint');
  

• Mocking External APIs: Replace Http calls with Pact mocks in tests:

  $this->mockHttpClient()
       ->expects()
       ->get('https://external-api.com')
       ->willRespondWith(200, ['mocked' => 'data']);
  

• Dynamic Pact Names: Use environment variables for dynamic Pact names:

  $this->pact(config('services.pact.consumer_name'));
  

Gotchas and Tips

Pitfalls

1. State Management

   • Forgetting to call given() before expectations leads to silent failures.
   • Fix: Always chain given() before expects() in tests.

2. Provider Stub Generation

   • Generated stubs may not cover all edge cases. Manually review pact/stubs/ after generation.
   • Fix: Use --force flag to regenerate stubs:

     php artisan pact:generate --force
     

3. Broker Authentication

   • Hardcoded broker credentials in config/pact.php can cause security issues.
   • Fix: Use Laravel's env() or vault integration:

     'broker' => [
         'url' => env('PACT_BROKER_URL'),
         'token' => env('PACT_BROKER_TOKEN'),
     ],
     

4. Test Isolation

   • Pact tests are slow; avoid running them in parallel unless using --parallel flag:

     php artisan pact:test --parallel
     

Debugging

• Verbose Output: Enable debug mode in config/pact.php:

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

• Pact Logs: Check storage/logs/pact.log for interaction details.
• Stub Validation: Use php artisan pact:validate to check stubs against the broker.

Extension Points

1. Custom Matchers Extend Buero\PactBundle\Matchers\MatcherInterface for domain-specific assertions:

   class CustomMatcher implements MatcherInterface
   {
       public function matches($expected, $actual): bool
       {
           // Custom logic
       }
   }
   

   Register in config/pact.php:

   'matchers' => [
       CustomMatcher::class,
   ],
   

2. Provider Verification Override PactBundle\Providers\ProviderVerifier to add custom verification steps:

   class CustomVerifier extends ProviderVerifier
   {
       protected function verifyInteraction($interaction)
       {
           // Custom logic
           parent::verifyInteraction($interaction);
       }
   }
   

   Bind in AppServiceProvider:

   $this->app->bind(
       ProviderVerifier::class,
       CustomVerifier::class
   );
   

3. Event Listeners Listen for pact.generated or pact.verified events to trigger post-processing:

   use Buero\PactBundle\Events\PactGenerated;
   
   public function handlePactGenerated(PactGenerated $event)
   {
       // Example: Upload stubs to S3
   }