fuel-alert/tests/Unit/Services/PostcodeServiceTest.php

<?php

use App\Models\Outcode;
use App\Models\Postcode;
use App\Services\ApiLogger;
use App\Services\LocationResult;
use App\Services\PostcodeService;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;

uses(RefreshDatabase::class);

beforeEach(function (): void {
    $this->service = new PostcodeService(new ApiLogger);
});

// --- Full postcode ---

it('resolves a full postcode to coordinates', function (): void {
    Http::fake([
        '*/postcodes/SW1A1AA' => Http::response([
            'status' => 200,
            'result' => [
                'postcode' => 'SW1A 1AA',
                'latitude' => 51.501009,
                'longitude' => -0.141588,
            ],
        ]),
    ]);

    $result = $this->service->resolve('SW1A 1AA');

    expect($result)->toBeInstanceOf(LocationResult::class)
        ->and($result->displayName)->toBe('SW1A 1AA')
        ->and($result->lat)->toBe(51.501009)
        ->and($result->lng)->toBe(-0.141588);
});

it('normalises postcode spacing before lookup', function (): void {
    Http::fake([
        '*/postcodes/SW1A1AA' => Http::response([
            'status' => 200,
            'result' => [
                'postcode' => 'SW1A 1AA',
                'latitude' => 51.501009,
                'longitude' => -0.141588,
            ],
        ]),
    ]);

    $result = $this->service->resolve('sw1a1aa');

    expect($result)->not->toBeNull()
        ->and($result->displayName)->toBe('SW1A 1AA');
});

// --- Outcode ---

it('resolves an outcode to coordinates', function (): void {
    Http::fake([
        '*/outcodes/PE7' => Http::response([
            'status' => 200,
            'result' => [
                'outcode' => 'PE7',
                'latitude' => 52.536397,
                'longitude' => -0.210181,
            ],
        ]),
    ]);

    $result = $this->service->resolve('PE7');

    expect($result)->toBeInstanceOf(LocationResult::class)
        ->and($result->displayName)->toBe('PE7')
        ->and($result->lat)->toBe(52.536397)
        ->and($result->lng)->toBe(-0.210181);
});

it('resolves a lowercase outcode', function (): void {
    Http::fake([
        '*/outcodes/M1' => Http::response([
            'status' => 200,
            'result' => [
                'outcode' => 'M1',
                'latitude' => 53.480957,
                'longitude' => -2.237428,
            ],
        ]),
    ]);

    $result = $this->service->resolve('m1');

    expect($result)->not->toBeNull()
        ->and($result->displayName)->toBe('M1');
});

// --- Place name ---

it('resolves a city name to coordinates', function (): void {
    Http::fake([
        '*/places*' => Http::response([
            'status' => 200,
            'result' => [
                [
                    'name_1' => 'Manchester',
                    'latitude' => 53.480957,
                    'longitude' => -2.237428,
                ],
            ],
        ]),
    ]);

    $result = $this->service->resolve('Manchester');

    expect($result)->toBeInstanceOf(LocationResult::class)
        ->and($result->displayName)->toBe('Manchester')
        ->and($result->lat)->toBe(53.480957)
        ->and($result->lng)->toBe(-2.237428);
});

it('returns null when place name yields no results', function (): void {
    Http::fake([
        '*/places*' => Http::response([
            'status' => 200,
            'result' => [],
        ]),
    ]);

    $result = $this->service->resolve('Narnia');

    expect($result)->toBeNull();
});

// --- Caching ---

it('caches a successful place resolution for 30 days', function (): void {
    Http::fake([
        '*/places*' => Http::response([
            'status' => 200,
            'result' => [[
                'name_1' => 'Manchester',
                'latitude' => 53.480957,
                'longitude' => -2.237428,
            ]],
        ]),
    ]);

    $this->service->resolve('Manchester');
    $this->service->resolve('Manchester');

    Http::assertSentCount(1);
    expect(Cache::get('place:manchester'))->toBeInstanceOf(LocationResult::class);
});

it('does not cache postcode resolutions in the Cache store (DB is the cache)', function (): void {
    Http::fake([
        '*/postcodes/SW1A1AA' => Http::response([
            'status' => 200,
            'result' => [
                'postcode' => 'SW1A 1AA',
                'latitude' => 51.501009,
                'longitude' => -0.141588,
            ],
        ]),
    ]);

    $this->service->resolve('SW1A 1AA');

    expect(Cache::get('postcode:sw1a1aa'))->toBeNull()
        ->and(Postcode::find('SW1A1AA'))->not->toBeNull();
});

it('does not cache failed lookups', function (): void {
    Http::fake([
        '*/postcodes/ZZ99ZZ' => Http::response(['status' => 404], 404),
    ]);

    $result = $this->service->resolve('ZZ9 9ZZ');

    expect($result)->toBeNull()
        ->and(Cache::get('postcode:zz99zz'))->toBeNull();
});

it('returns null and does not throw on API failure', function (): void {
    Http::fake([
        '*/outcodes/PE7' => Http::response([], 500),
    ]);

    $result = $this->service->resolve('PE7');

    expect($result)->toBeNull();
});

// --- Local DB (full postcode) ---

it('resolves a full postcode from local DB without calling HTTP', function (): void {
    Postcode::create([
        'postcode' => 'SW1A1AA',
        'outcode' => 'SW1A',
        'lat' => 51.501009,
        'lng' => -0.141588,
    ]);

    Http::fake(); // any HTTP call will be recorded

    $result = $this->service->resolve('SW1A 1AA');

    expect($result)->toBeInstanceOf(LocationResult::class)
        ->and($result->displayName)->toBe('SW1A 1AA')
        ->and($result->lat)->toBe(51.501009)
        ->and($result->lng)->toBe(-0.141588);

    Http::assertNothingSent();
});

// --- Local DB (outcode) ---

it('resolves an outcode from local DB without calling HTTP', function (): void {
    Outcode::create([
        'outcode' => 'PE7',
        'lat' => 52.536397,
        'lng' => -0.210181,
    ]);

    Http::fake();

    $result = $this->service->resolve('PE7');

    expect($result)->toBeInstanceOf(LocationResult::class)
        ->and($result->displayName)->toBe('PE7')
        ->and($result->lat)->toBe(52.536397)
        ->and($result->lng)->toBe(-0.210181);

    Http::assertNothingSent();
});

// --- HTTP fallback persistence ---

it('persists a full postcode resolved via HTTP fallback', function (): void {
    Http::fake([
        '*/postcodes/SW1A1AA' => Http::response([
            'status' => 200,
            'result' => [
                'postcode' => 'SW1A 1AA',
                'latitude' => 51.501009,
                'longitude' => -0.141588,
            ],
        ]),
    ]);

    $this->service->resolve('SW1A 1AA');

    $row = Postcode::find('SW1A1AA');

    expect($row)->not->toBeNull()
        ->and($row->outcode)->toBe('SW1A')
        ->and((float) $row->lat)->toBe(51.501009)
        ->and((float) $row->lng)->toBe(-0.141588);
});

it('persists an outcode resolved via HTTP fallback', function (): void {
    Http::fake([
        '*/outcodes/PE7' => Http::response([
            'status' => 200,
            'result' => [
                'outcode' => 'PE7',
                'latitude' => 52.536397,
                'longitude' => -0.210181,
            ],
        ]),
    ]);

    $this->service->resolve('PE7');

    $row = Outcode::find('PE7');

    expect($row)->not->toBeNull()
        ->and((float) $row->lat)->toBe(52.536397)
        ->and((float) $row->lng)->toBe(-0.210181);
});

// --- Reverse geocoding (area label) ---

it('reverse-geocodes coordinates to the admin district', function (): void {
    Http::fake([
        '*/postcodes?*' => Http::response([
            'status' => 200,
            'result' => [
                ['admin_district' => 'Peterborough', 'region' => 'East of England'],
            ],
        ]),
    ]);

    expect($this->service->reverseResolve(52.5364, -0.2102))->toBe('Peterborough');
});

it('falls back to a broader area when admin district is missing', function (): void {
    Http::fake([
        '*/postcodes?*' => Http::response([
            'status' => 200,
            'result' => [
                ['admin_district' => null, 'region' => 'Scotland'],
            ],
        ]),
    ]);

    expect($this->service->reverseResolve(57.4, -4.2))->toBe('Scotland');
});

it('returns null when reverse geocoding finds no area', function (): void {
    Http::fake([
        '*/postcodes?*' => Http::response(['status' => 200, 'result' => null]),
    ]);

    expect($this->service->reverseResolve(0.0, 0.0))->toBeNull();
});

it('returns null when the reverse geocode request fails', function (): void {
    Http::fake([
        '*/postcodes?*' => Http::response([], 500),
    ]);

    expect($this->service->reverseResolve(52.5364, -0.2102))->toBeNull();
});

it('caches the reverse-geocoded area per bucket', function (): void {
    Http::fake([
        '*/postcodes?*' => Http::response([
            'status' => 200,
            'result' => [['admin_district' => 'Peterborough']],
        ]),
    ]);

    // Two coordinates inside the same ~1km (2dp) bucket → one HTTP call.
    $this->service->reverseResolve(52.5364, -0.2102);
    $this->service->reverseResolve(52.5359, -0.2148);

    Http::assertSentCount(1);
});

it('queries postcodes.io with a wide radius so low-density buckets still match', function (): void {
    Http::fake([
        '*/postcodes?*' => Http::response([
            'status' => 200,
            'result' => [['admin_district' => 'Peterborough']],
        ]),
    ]);

    $this->service->reverseResolve(52.54, -0.25);

    // The default 100m radius misses the bucket centroid in rural areas; we send 2000m.
    Http::assertSent(fn ($request) => str_contains($request->url(), 'radius=2000'));
});