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

[edwh]

The symptom

Forked pull requests fail CI in a way that looks like the contributor broke everything: all 50 Playwright tests fail at createGroup, and the job times out. #906 is the current example — 2 of 50 passing, on a diff that only removes unused component registrations.

The cause

CircleCI doesn't pass project environment variables to jobs built from forked PRs, so GOOGLE_API_CONSOLE_KEY is empty on those runs.

The evidence is in the logs: on a develop run the string "restarters" is masked 68 times (a project env var's value), while #906's log has no masked strings at all — nothing was injected.

With no key, Geocoder::geocode() returns false, API\GroupController throws ValidationException on groups.geocode_failed, the create form 422s and never redirects to /edit/, and waitForURL('**/edit/**') times out. Every test calls createGroup, so every test fails, from the first one.

Reproduced locally: blanking the key makes geocode('London') return false.

The fix

A StubGeocoder answering from a fixed table, bound only when GEOCODER_STUB is set — which CI sets only when there's no key, so runs on this repo still exercise the real geocoder, and production can't reach it.

It keeps the ForceGeocodeFailure sentinel failing, and falls back to London for an unlisted place so a new test fails on what it's actually testing.

The alternative — turning on CircleCI's "pass secrets to forked PRs" — would hand the project's API keys to anyone who opens a fork PR. Not worth it for a geocoding lookup the tests don't need to be real.

Tests

6 unit tests: the stub is off unless deliberately enabled, it satisfies the Geocoder contract, it answers the address the e2e suite actually types, it ignores case and whitespace, it falls back rather than failing, and it still fails for the sentinel. Existing GeocoderTest still passes.

Note for #906

Because CircleCI builds the fork's head rather than a merge, #906 will keep failing until this lands and that branch merges develop.

🤖 Generated with Claude Code

[edwh]

Verified the stub path rather than assuming it, since this repo's own runs always have the real key and so never exercise it.

Pushed a throwaway commit forcing GEOCODER_STUB=true for the e2e run only (after PHPUnit, so the unit test asserting the stub is off by default still saw a truthful environment). The run confirmed both halves:

stub step -> App\Helpers\StubGeocoder
Run main Playwright tests -> success

So the container really did resolve the stub, and the full Playwright suite passed with it in play — which is what a forked PR will get.

That commit is now dropped; the branch is back to the clean version, which had already passed green on its own (pipeline #5007).

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[ngm]

Using a stub geocoder on CI makes perfect sense.

As a follow up point:

so runs on this repo still exercise the real geocoder

So CI runs on our repo use the production API key? I don't mind per se. Some questions:

• What's the mechanism for storing the API key such that it's used here?
• Might it be better to switch to a development only API key for this purpose?
• Is there a good reason for CI test runs from the repo exercising the production geocoder? Why not a stub here too?

I don't have particularly strong feelings on this, but good for me to understand the answers to those questions. @edwh