fix: stop CI failing on forked PRs for want of a geocoding key

.circleci/config.yml

@@ -47,6 +47,16 @@ jobs:
             echo "GOOGLE_API_CONSOLE_KEY=$GOOGLE_API_CONSOLE_KEY" >> .env
             echo "MAPBOX_TOKEN=$MAPBOX_TOKEN" >> .env
 
+            # CircleCI does not give project environment variables to jobs built
+            # from forked pull requests, so those runs have no geocoding key.
+            # Without this every group creation 422s on geocode_failed and the
+            # whole Playwright suite fails at its first createGroup(), which
+            # reads as the contributor having broken something.
+            if [ -z "$GOOGLE_API_CONSOLE_KEY" ]; then
+              echo "No geocoding key available - using the stub geocoder."
+              echo "GEOCODER_STUB=true" >> .env
+            fi
+
       # Start Docker services using Task
       - run:
           name: Start Docker services

app/Helpers/StubGeocoder.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Helpers;
+
+/**
+ * A Geocoder that answers from a fixed table instead of calling Google.
+ *
+ * CircleCI does not pass project environment variables to jobs built from
+ * forked pull requests, so GOOGLE_API_CONSOLE_KEY is empty on those runs.
+ * Every geocode then returns false, group creation 422s on
+ * groups.geocode_failed, and the whole Playwright suite fails at its first
+ * createGroup() - which looks exactly like the contributor having broken
+ * something. This stub keeps those runs meaningful, and keeps the suite off
+ * the live Google API generally.
+ *
+ * Only used when GEOCODER_STUB is set, which CI does when there is no key.
+ */
+class StubGeocoder extends Geocoder
+{
+    /**
+     * Coordinates the end-to-end tests need. Anything else gets London, so a
+     * new test that geocodes somewhere unlisted still passes rather than
+     * failing for a reason that has nothing to do with what it is testing.
+     */
+    private const PLACES = [
+        'london' => [51.5072178, -0.1275862, 'GB'],
+        'london, uk' => [51.5072178, -0.1275862, 'GB'],
+        'edinburgh' => [55.9533456, -3.1883749, 'GB'],
+        'brussels' => [50.8476424, 4.3571696, 'BE'],
+        'paris' => [48.8575475, 2.3513765, 'FR'],
+    ];
+
+    public function geocode($location)
+    {
+        // Preserve the sentinel the tests use to exercise the failure path.
+        if ($location === 'ForceGeocodeFailure') {
+            return false;
+        }
+
+        [$latitude, $longitude, $country_code] =
+            self::PLACES[mb_strtolower(trim((string) $location))] ?? self::PLACES['london'];
+
+        return [
+            'latitude' => $latitude,
+            'longitude' => $longitude,
+            'country_code' => $country_code,
+        ];
+    }
+}

app/Providers/AppServiceProvider.php

@@ -46,7 +46,9 @@ public function boot(): void
     public function register(): void
     {
         $this->app->singleton(Geocoder::class, function () {
-            return new Geocoder();
+            return config('restarters.geocoder_stub')
+                ? new \App\Helpers\StubGeocoder()
+                : new Geocoder();
         });
 
         // Override the existing translator with our own robust one.

config/restarters.php

@@ -31,4 +31,9 @@
     ],
 
     'support_email_address' => env('SUPPORT_EMAIL_ADDRESS'),
+
+    // Answer geocoding from a fixed table instead of calling Google. Set by CI
+    // when no API key is available (forked pull requests get no project
+    // environment variables), never in production.
+    'geocoder_stub' => env('GEOCODER_STUB', false),
 ];

tests/Unit/StubGeocoderTest.php

@@ -0,0 +1,66 @@
+<?php
+
+use App\Helpers\Geocoder;
+use App\Helpers\StubGeocoder;
+use Tests\TestCase;
+
+class StubGeocoderTest extends TestCase
+{
+    /**
+     * The property that matters in production: nothing stubs geocoding unless
+     * GEOCODER_STUB is deliberately set, which only CI does and only when it
+     * has no key. (The container binding itself can't be asserted here -
+     * TestCase binds a GeocoderMock for every test.)
+     */
+    public function testStubIsOffUnlessDeliberatelyEnabled(): void
+    {
+        self::assertFalse((bool) config('restarters.geocoder_stub'));
+    }
+
+    public function testStubStillSatisfiesTheGeocoderContract(): void
+    {
+        self::assertInstanceOf(Geocoder::class, new StubGeocoder());
+    }
+
+    /**
+     * The end-to-end suite always types "London, UK", so that is the one
+     * answer the stub has to get right for CI to be worth anything.
+     */
+    public function testAnswersTheAddressTheEndToEndTestsUse(): void
+    {
+        $geocoded = (new StubGeocoder())->geocode('London, UK');
+
+        self::assertEqualsWithDelta(51.5072178, $geocoded['latitude'], 0.001);
+        self::assertEqualsWithDelta(-0.1275862, $geocoded['longitude'], 0.001);
+        self::assertEquals('GB', $geocoded['country_code']);
+    }
+
+    public function testIsNotCaseOrWhitespaceSensitive(): void
+    {
+        self::assertEquals(
+            (new StubGeocoder())->geocode('London, UK'),
+            (new StubGeocoder())->geocode('  LONDON, uk ')
+        );
+    }
+
+    /**
+     * An unlisted place still geocodes, so a new test that happens to use one
+     * fails on what it is actually testing rather than on the stub.
+     */
+    public function testFallsBackRatherThanFailingForAnUnlistedPlace(): void
+    {
+        $geocoded = (new StubGeocoder())->geocode('Somewhere nobody listed');
+
+        self::assertNotFalse($geocoded);
+        self::assertArrayHasKey('latitude', $geocoded);
+    }
+
+    /**
+     * The suite uses this sentinel to exercise the geocode-failure path, so
+     * the stub has to keep failing for it.
+     */
+    public function testStillFailsForTheForcedFailureSentinel(): void
+    {
+        self::assertFalse((new StubGeocoder())->geocode('ForceGeocodeFailure'));
+    }
+}