| name | run-firestore-tests |
| description | Run the emulator-gated Firestore test suites (session + park store) for the Go and Python ports. Use after changing session/park-store code or workflow event fields — these suites are excluded from the default `make ci` gate. |
Run Firestore Tests
The Firestore session/park-store backends are validated against the Cloud Firestore emulator, not the default unit run — make cover deliberately excludes them so nobody needs the emulator for everyday work. This skill runs that gated slice explicitly.
Parameters: none
Usage examples:
/run-firestore-tests # start emulator, run go/ + python/ suites, stop emulator
The authoritative flow, backend matrix, and coverage rationale live in okf/standards/testing.md (Firestore-backed tests section) and okf/tooling/ci-gates.md. This skill is a thin driver.
When to Use
After any change touching:
- Session-store or park-store code (
*_firestore backends, store conformance suites)
- Workflow event fields that get persisted (session history shape, park record fields)
- The
SESSION_BACKEND switching logic or store construction in the setup layer
Not needed for changes that never touch persisted state — the default make ci covers those.
Steps
-
Start the emulator (needs Java 17+; gcloud components install cloud-firestore-emulator one-time), capturing the PID so teardown kills exactly what was started:
gcloud emulators firestore start --host-port=127.0.0.1:8791 &
EMULATOR_PID=$!
Wait for the "Dev App Server is now running" line before proceeding.
-
Run the Go suite (from go/):
FIRESTORE_EMULATOR_HOST=127.0.0.1:8791 GOOGLE_CLOUD_PROJECT=test make cover-firestore
-
Run the Python suite (from python/):
FIRESTORE_EMULATOR_HOST=127.0.0.1:8791 make cover-firestore
-
Stop the emulator — kill the process you started (the gcloud wrapper spawns a
Java child, so kill the process group, not just the PID):
kill -- -"$(ps -o pgid= -p "$EMULATOR_PID" | tr -d ' ')" 2>/dev/null || kill "$EMULATOR_PID" 2>/dev/null || true
Verify nothing is left listening: lsof -i :8791 should be empty. If the PID was
lost (different shell), fall back to pkill -f 'firestore.*8791' — scoped to this
port so unrelated emulators survive.
-
Report pass/fail per port. On failure, fix and re-run only the failing port's step (leave the emulator up between retries; still stop it when done).
Key Rules
- Both targets fail fast with a hint if
FIRESTORE_EMULATOR_HOST is unset — that's expected, not a bug; set the var on the same command line.
- Only
go/ and python/ have cover-firestore targets (the modern pair). The frozen pair (kotlin/, javascript/) is out of scope here.
- Always stop the emulator when done — a stale emulator on the port makes later runs hit old state.
- Test isolation is per-run (timestamped collection prefixes), so re-runs against a warm emulator are safe.
- These suites complement, not replace, the normal gates — run
/verify as usual too.
