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 resolution for 30 days', function (): void { Http::fake([ '*/outcodes/PE7' => Http::response([ 'status' => 200, 'result' => [ 'outcode' => 'PE7', 'latitude' => 52.536397, 'longitude' => -0.210181, ], ]), ]); $this->service->resolve('PE7'); $this->service->resolve('PE7'); Http::assertSentCount(1); expect(Cache::get('postcode:pe7'))->toBeInstanceOf(LocationResult::class); }); 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); });