Tests Laravel Package

## Getting Started

### Minimal Steps
1. **Installation**
   ```bash
   composer require omnipay/tests --dev

Ensure omnipay/omnipay (≥v3.2) and PHPUnit 10/11 are installed (peer dependencies). Note: GuzzleHttp/Psr7 v2.0+ is now supported.

2. First Use Case: Testing a Payment Gateway Create a test class extending Omnipay\Tests\TestCase:

   use Omnipay\Tests\TestCase;
   use Omnipay\Omnipay;
   
   class StripePaymentTest extends TestCase
   {
       public function testSuccessfulPurchase()
       {
           $gateway = Omnipay::create('Stripe');
           $response = $gateway->purchase([
               'amount' => '10.00',
               'currency' => 'USD',
               'card' => 'tok_visa'
           ])->send();
   
           $this->assertTrue($response->isSuccessful());
       }
   }
   

3. Where to Look First

   • TestCase: vendor/omnipay/tests/src/TestCase.php (updated for PHPUnit 10/11).
   • Mocks: vendor/omnipay/tests/src/Mock/ (now compatible with GuzzleHttp/Psr7 v2.0+).
   • Assertions: vendor/omnipay/tests/src/Assert.php (unchanged).

Implementation Patterns

Usage Patterns

1. Mocking External Gateways Use TestGateway with updated Guzzle/Psr7 support:

   use Omnipay\Tests\TestGateway;
   
   $testGateway = TestGateway::create('Stripe');
   $testGateway->setTestResponse('purchase', [
       'success' => true,
       'transactionReference' => 'test_ref_123'
   ]);
   
   // Guzzle v2.0+ streams are now supported in mock responses
   $response = $testGateway->purchase([...])->send();
   

2. Testing Error Scenarios Simulate failures with updated PHPUnit 10/11 assertions:

   $testGateway->setTestResponse('purchase', [
       'success' => false,
       'message' => 'Card declined',
       'code' => 'card_declined'
   ]);
   
   $response = $testGateway->purchase([...])->send();
   $this->assertFalse($response->isSuccessful());
   $this->assertStringContainsString('declined', $response->getMessage());
   

3. Integration with Laravel

   • Service Providers: Bind Omnipay gateways in AppServiceProvider:

     public function register()
     {
         $this->app->bind('stripe', function () {
             return Omnipay::create('Stripe');
         });
     }
     

   • PHPUnit 10/11: Update phpunit.xml to support new syntax:

     <phpunit bootstrap="vendor/autoload.php">
         <extensions>
             <extension class="Omnipay\Tests\PHPUnit\Extensions\OmnipayExtension"/>
         </extensions>
     </phpunit>
     

4. Testing Webhooks Mock webhook responses with Guzzle v2.0+ compatibility:

   $testGateway->setTestResponse('completePurchase', [
       'success' => true,
       'transactionReference' => 'webhook_ref_456',
       'body' => new \Psr\Http\Message\StreamInterface() // Guzzle v2.0+ stream
   ]);
   

Workflows

1. Test-Driven Development (TDD) for Payments

   • Write tests for payment flows before implementing logic.
   • Example: Test subscription creation with PHPUnit 10/11 traits:

     use PHPUnit\Framework\Attributes\Test;
     
     #[Test]
     public function testSubscriptionCreation()
     {
         $gateway = Omnipay::create('Stripe');
         // ...
     }
     

2. CI/CD Pipeline

   • Update workflow to use PHPUnit 10/11:

     jobs:
       test:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - uses: shivammathur/setup-php@v2
             with:
               php-version: '8.2'
               extensions: guzzle
           - run: composer install --dev
           - run: vendor/bin/phpunit --testdox-html report.html
     

3. Edge Case Testing

   • Test multi-currency with updated Guzzle streams:

     $testGateway->setTestResponse('refund', [
         'success' => true,
         'amountRefunded' => '5.00',
         'remainingBalance' => '5.00',
         'headers' => ['Content-Type' => 'application/json']
     ]);
     

Gotchas and Tips

Pitfalls

1. PHPUnit Version Conflicts

   • Issue: Project uses PHPUnit <10, but omnipay/tests requires 10/11.
   • Fix: Update composer.json or pin version:

     "require-dev": {
         "phpunit/phpunit": "^10.0 || ^11.0"
     }
     

2. GuzzleHttp/Psr7 v2.0+ Migration

   • Issue: Tests fail with Psr\Http\Message\StreamInterface deprecations.
   • Fix: Update mock responses to use Guzzle v2.0+ streams:

     $testGateway->setTestResponse('purchase', [
         'body' => \GuzzleHttp\Psr7\stream_for('{"success":true}')
     ]);
     

3. Missing Test Coverage for Custom Gateways

   • Issue: Omnipay’s test suite lacks support for custom gateways.
   • Fix: Extend TestGateway with Guzzle v2.0+ support:

     class CustomGatewayTest extends TestCase
     {
         protected function getGateway()
         {
             $gateway = new CustomGateway();
             $gateway->setHttpClient(new \GuzzleHttp\Client());
             return $gateway;
         }
     }
     

4. Flaky Tests Due to Non-Deterministic Mocks

   • Issue: Mock responses not consistently applied in parallel tests.
   • Fix: Reset mocks in setUp() with PHPUnit 10/11:

     public function setUp(): void
     {
         parent::setUp();
         $this->getGateway()->clearTestResponses();
         $this->markTestSkippedIf(!class_exists(\GuzzleHttp\Psr7\Stream::class), 'Guzzle v2.0+ required');
     }
     

Debugging Tips

1. Enable Verbose Logging Use TestCase::enableVerboseLogging() with PHPUnit 10/11:

   public function setUp(): void
   {
       parent::setUp();
       $this->enableVerboseLogging();
       $this->setLogger(new \Monolog\Logger('test'));
   }
   

2. Inspect Mock Responses Dump mock responses to verify Guzzle v2.0+ compatibility:

   $response = $this->getGateway()->getTestResponse('purchase');
   $this->assertInstanceOf(\Psr\Http\Message\ResponseInterface::class, $response);
   

3. Test Database Transactions For Laravel, use transactions with PHPUnit 10/11:

   public function testPaymentWithDatabase()
   {
       $this->beginTransaction();
       try {
           // Test payment logic
           $this->commitTransaction();
       } catch (\Exception $e) {
           $this->rollBackTransaction();
           $this->fail('Test failed: ' . $e->getMessage());
       }
   }
   

Extension Points

1. Custom Assertions Extend Omnipay\Tests\Assert for domain-specific checks with PHPUnit 10/11:

   use PHPUnit\Framework\Attributes\DataProvider;
   
   class PaymentAssertions extends Assert
   {
       #[DataProvider('refundProvider')]
       public function testRefundAmount($response, $expected)
       {
           $this->assertEquals($expected, $response->getAmountRefunded());
       }
   }
   

2. Dynamic Test Data Use factories with Guzzle v2.0+ streams:

   $testGateway->setTestResponse('purchase', [
       'body' => \GuzzleHttp\Psr7\stream_for(json_encode([
           'success' => true,
           'card' => 'tok_visa_' . Str::random(10)
       ]))
   ]);
   

3. Parallel Test Execution Avoid collisions in parallel tests with PHPUnit 10/11:

   class