Add tests for town sync job and search endpoint

- SyncTownsTest: covers API syncing, pagination, upsert, retired towns, error logging, and success logging
- TownSearchTest: covers auth requirement, min query length, prefix matching, state filtering, retired town exclusion, result limit, response shape, and ordering
- Update TownFactory with retired() and inState() states

tests/Feature/Towns/TownSearchTest.php

@@ -0,0 +1,119 @@
+<?php
+
+namespace Tests\Feature\Towns;
+
+use App\Enums\AustralianState;
+use App\Models\Town;
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class TownSearchTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private function actingAsUser(): static
+    {
+        return $this->actingAs(User::factory()->create());
+    }
+
+    public function test_requires_authentication(): void
+    {
+        $this->get('/towns/search?query=Perth')->assertRedirect('/login');
+    }
+
+    public function test_returns_empty_array_for_query_shorter_than_two_characters(): void
+    {
+        Town::factory()->create(['town_name' => 'Perth']);
+
+        $this->actingAsUser()
+            ->getJson('/towns/search?query=P')
+            ->assertOk()
+            ->assertExactJson([]);
+    }
+
+    public function test_returns_matching_towns_by_prefix(): void
+    {
+        Town::factory()->create(['town_name' => 'Perth', 'state' => AustralianState::WA->value]);
+        Town::factory()->create(['town_name' => 'Pertham', 'state' => AustralianState::WA->value]);
+        Town::factory()->create(['town_name' => 'Sydney', 'state' => AustralianState::NSW->value]);
+
+        $response = $this->actingAsUser()
+            ->getJson('/towns/search?query=Per')
+            ->assertOk();
+
+        $this->assertCount(2, $response->json());
+        $this->assertSame('Perth, WA', $response->json('0.label'));
+        $this->assertSame('Pertham, WA', $response->json('1.label'));
+    }
+
+    public function test_filters_results_by_state(): void
+    {
+        Town::factory()->create(['town_name' => 'Port Hedland', 'state' => AustralianState::WA->value]);
+        Town::factory()->create(['town_name' => 'Port Augusta', 'state' => AustralianState::SA->value]);
+
+        $response = $this->actingAsUser()
+            ->getJson('/towns/search?query=Port&state='.AustralianState::WA->value)
+            ->assertOk();
+
+        $this->assertCount(1, $response->json());
+        $this->assertSame('Port Hedland', $response->json('0.name'));
+    }
+
+    public function test_excludes_retired_towns(): void
+    {
+        Town::factory()->create(['town_name' => 'Perth', 'state' => AustralianState::WA->value]);
+        Town::factory()->retired()->create(['town_name' => 'Perthville', 'state' => AustralianState::WA->value]);
+
+        $response = $this->actingAsUser()
+            ->getJson('/towns/search?query=Per')
+            ->assertOk();
+
+        $this->assertCount(1, $response->json());
+        $this->assertSame('Perth', $response->json('0.name'));
+    }
+
+    public function test_returns_at_most_ten_results(): void
+    {
+        Town::factory()->count(15)->create([
+            'town_name' => 'Perth',
+            'state' => AustralianState::WA->value,
+        ]);
+
+        $response = $this->actingAsUser()
+            ->getJson('/towns/search?query=Per')
+            ->assertOk();
+
+        $this->assertCount(10, $response->json());
+    }
+
+    public function test_response_includes_name_state_and_label_fields(): void
+    {
+        Town::factory()->create(['town_name' => 'Perth', 'state' => AustralianState::WA->value]);
+
+        $response = $this->actingAsUser()
+            ->getJson('/towns/search?query=Per')
+            ->assertOk();
+
+        $result = $response->json('0');
+        $this->assertArrayHasKey('name', $result);
+        $this->assertArrayHasKey('state', $result);
+        $this->assertArrayHasKey('label', $result);
+        $this->assertSame('Perth', $result['name']);
+        $this->assertSame('WA', $result['state']);
+        $this->assertSame('Perth, WA', $result['label']);
+    }
+
+    public function test_results_are_ordered_alphabetically(): void
+    {
+        Town::factory()->create(['town_name' => 'Pertham', 'state' => AustralianState::WA->value]);
+        Town::factory()->create(['town_name' => 'Perth', 'state' => AustralianState::WA->value]);
+
+        $response = $this->actingAsUser()
+            ->getJson('/towns/search?query=Per')
+            ->assertOk();
+
+        $this->assertSame('Perth', $response->json('0.name'));
+        $this->assertSame('Pertham', $response->json('1.name'));
+    }
+}