Provider Integration Tests Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require geocoder-php/provider-integration-tests --dev
   

   (Note: This is primarily a test package; install only in test environments.)

2. First Use Case:

   • Clone or reference the test suite in your project’s tests/Feature/Geocoder/ directory.
   • Use the provided GeocoderProviderTestCase base class to bootstrap tests for your custom geocoding provider (e.g., GoogleMapsProvider, OpenStreetMapProvider).

3. Key Files:

   • src/GeocoderProviderTestCase.php: Base test class with shared assertions.
   • src/Providers/: Example provider test classes (e.g., GoogleMapsProviderTest.php).

Quick Start Example

use Geocoder\Provider\GoogleMapsProvider;
use Geocoder\Provider\IntegrationTests\GeocoderProviderTestCase;

class CustomGoogleMapsProviderTest extends GeocoderProviderTestCase
{
    protected function getProvider(): GoogleMapsProvider
    {
        return new GoogleMapsProvider('YOUR_API_KEY');
    }

    // Inherits assertions from GeocoderProviderTestCase
}

Implementation Patterns

Workflow Integration

1. Test-Driven Provider Development:

   • Extend GeocoderProviderTestCase to validate:
     • Address geocoding (e.g., "1600 Amphitheatre Parkway, Mountain View" → {lat, lng}).
     • Reverse geocoding (e.g., {lat, lng} → formatted address).
     • Edge cases (empty inputs, rate limits, invalid responses).
   • Example:

     public function testGeocodeAddress()
     {
         $result = $this->geocode('Paris');
         $this->assertNotNull($result->getCoordinates());
     }
     

2. Provider-Specific Customization:

   • Override methods in GeocoderProviderTestCase to mock API responses or adjust assertions:

     protected function getExpectedCoordinatesForAddress(string $address): array
     {
         return ['lat' => 48.8566, 'lng' => 2.3522]; // Paris coordinates
     }
     

3. CI/CD Integration:

   • Run tests in GitHub Actions with environment variables for API keys:

     - name: Run Geocoder Tests
       run: php vendor/bin/phpunit --env API_KEY=${{ secrets.GOOGLE_MAPS_API_KEY }}
     

Common Patterns

• Mocking API Responses: Use HttpMock (from geocoder-php/http-adapter-guzzle) to simulate network calls:

  $this->httpMock->append(
      'https://maps.googleapis.com/...',
      json_encode(['results' => [...]])
  );
  

• Provider-Specific Assertions: Add custom assertions for provider quirks (e.g., Google’s geometry.location vs. OpenStreetMap’s lat/lng):

  protected function assertCoordinates(array $actual, array $expected): void
  {
      $this->assertEquals($expected['lat'], $actual['geometry']['location']['lat']);
  }
  

Gotchas and Tips

Pitfalls

1. API Key Leaks:

   • Risk: Hardcoding API keys in test files.
   • Fix: Use .env.testing or CI secrets:

     $provider = new GoogleMapsProvider(env('GOOGLE_MAPS_API_KEY'));
     

2. Rate Limits:

   • Issue: Free-tier providers (e.g., OpenStreetMap) throttle requests during test suites.
   • Fix: Use HttpMock to bypass live API calls or implement exponential backoff.

3. Response Schema Mismatches:

   • Problem: Providers return inconsistent JSON structures (e.g., nested location vs. flat lat/lng).
   • Solution: Override parseResponse() in your provider or extend test assertions.

Debugging Tips

• Enable Verbose Logging:

  $provider->setLogger(new \Monolog\Logger('test', ['handler' => new \Monolog\Handler\StreamHandler('php://stdout')]));
  

• Inspect Raw Responses:

  $this->httpMock->append('...', $rawResponse);
  $this->assertStringContainsString('error', $rawResponse); // Debug failures
  

Extension Points

1. Custom Providers:

   • Extend GeocoderProviderTestCase for unsupported providers (e.g., Mapbox, TomTom):

     class MapboxProviderTest extends GeocoderProviderTestCase
     {
         protected function getProvider(): MapboxProvider { ... }
         protected function getExpectedCoordinatesForAddress(string $address): array { ... }
     }
     

2. Test Data Fixtures:

   • Preload test addresses/coordinates in setUp():

     protected function loadTestData(): void
     {
         $this->testAddresses = [
             'Paris' => ['lat' => 48.8566, 'lng' => 2.3522],
             'New York' => ['lat' => 40.7128, 'lng' => -74.0060],
         ];
     }
     

3. Performance Testing:

   • Measure geocoding latency with microtime():

     $start = microtime(true);
     $this->geocode('Berlin');
     $this->assertLessThan(1.0, microtime(true) - $start); // <1s threshold