claude-checkpoint-tooling
3679e4dbc4
Reported directly by the user playtesting the exported exe: Play was permanently disabled and there was no way to log in or register. Root cause: main_menu.tscn wired Play and Quit, but nothing was ever connected to _on_login_button_pressed()/_on_register_button_pressed() -- the AuthPanel, its form, and all its backend-calling logic were fully correct, just completely unreachable. The script's own top comment even said "(the existing Play/Quit buttons)" as if Play/Quit somehow doubled as login triggers, which they never did -- a sign nobody ever actually clicked through the running scene, only checked things at the API level. Fix: added a real AuthButtonsRow (LoginButton, RegisterButton) wired to the existing handlers, which now hide themselves once auth succeeds. Also fixed grab_focus() targeting the AuthPanel (which can't accept focus, just a background warning) to focus the username field instead. Verified via two new smoke tests (smoke_test_main_menu_ui.gd, smoke_test_main_menu_full_flow.gd) using a *real signal emission* on the buttons, not a direct method call -- that distinction is exactly what would have caught the original bug. Full click-through confirmed against a real backend: open register form, fill it, submit, Play actually becomes enabled, welcome message shows, auth buttons hide. Also documents a real headless-testing gotcha found while verifying this: a synthetic Button.pressed.emit() on an await-using handler doesn't reliably get driven forward in --script/SceneTree mode the way real GUI input dispatch does -- confirmed by comparing direct-call vs emit() behavior side by side. Not a bug in the actual click-driven flow, a test-harness quirk to route around (call the handler directly, awaited, instead of emitting the signal). Full checkpoint suite re-verified clean on this branch: migrations, 68/68 pytest, all 6 Godot smoke tests (including the 2 new ones, picked up automatically by run_checkpoint_tests.py's glob). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
101 lines
8.3 KiB
Markdown
101 lines
8.3 KiB
Markdown
# Test Inventory
|
|
|
|
What automated coverage actually exists, what it actually verifies, and what
|
|
doesn't have coverage yet. Keep this current as tests are added — it's the
|
|
thing a Package Checkpoint review (see `docs/testing/README.md`) reads first
|
|
to know what "run the tests" actually checked.
|
|
|
|
Run everything below in one shot with `scripts/run_checkpoint_tests.py`.
|
|
|
|
Last verified against `main`: 2026-08-20 (commit `927f9bd`) — full PC1
|
|
checkpoint run, fresh clone, migrations + pytest + all 4 Godot smoke tests +
|
|
both platform exports, all clean.
|
|
|
|
## Backend — `backend/tests/` (pytest)
|
|
|
|
Run: `cd backend && python -m pytest -v` (needs `DATABASE_URL` pointed at a
|
|
reachable Postgres — see the runner script).
|
|
|
|
**Current total: 68 tests, all passing on a clean `main` checkout.**
|
|
|
|
| File | Tests | What it covers |
|
|
|---|---|---|
|
|
| `test_auth_age_gate.py` | 17 | `calculate_age()` date-math correctness (exact boundary, leap years, birthday-not-yet-this-year) + `RegisterRequest` date-of-birth validation (parametrized valid/invalid date rejection). Backs the 18+ registration gate (PR #23). |
|
|
| `test_gltf_metadata.py` | 21 | glTF/GLB binary + JSON parsing: magic-byte detection, chunk-padding handling, mesh/animation/texture-reference metadata extraction, malformed-input rejection. Backs the asset-import pipeline (PR #27). |
|
|
| `test_auth_endpoints.py` | 11 | **Integration tests** for `POST /api/auth/register` and `POST /api/auth/login` against the real FastAPI app + real Postgres. Covers: successful register (201), duplicate username (409), duplicate email (409), underage rejection (400), invalid date format (422), exact-18 registration, successful login with correct credentials (200), wrong password (401), nonexistent user (401), form-encoded login (OAuth2), and JWT validity of returned tokens. |
|
|
| `test_refresh_endpoint.py` | 8 | **Integration tests** for `POST /api/auth/refresh`. Covers: successful refresh (200, new access token, same refresh token returned), refresh produces different access tokens on repeated calls, invalid refresh token (401), empty body (422), missing field (422), refresh token from login also works, returned access token is valid JWT decodable with public key, `access_token_expires_minutes` in response. |
|
|
| `test_refresh_token_jti.py` | 6 | Unit tests for refresh token uniqueness (jti claim) and model column length. Covers: two calls with same sub produce different tokens (jti uniqueness), jti is valid UUID, rapid repeated calls all produce unique jtis, jti survives decode, `RefreshToken.token` column is `String(512)`, column type is `String`. |
|
|
| `test_auth_expired_token.py` | 5 | **Integration tests** for expired-token rejection across auth endpoints. Covers: expired access JWT rejected by `GET /api/auth/me` (401), garbage access token rejected by `/me` (401), missing bearer token returns 401, expired refresh token (DB `expires_at` in past) rejected by `/refresh` (401), expired refresh JWT (past `exp` claim) rejected before DB lookup (401). |
|
|
|
|
**What these are, honestly:** a mix of pure unit tests (`test_auth_age_gate.py`,
|
|
`test_gltf_metadata.py`, `test_refresh_token_jti.py`) and real integration tests
|
|
(`test_auth_endpoints.py`, `test_refresh_endpoint.py`, `test_auth_expired_token.py`)
|
|
that hit the FastAPI app against a real Postgres database via `TestClient`.
|
|
The integration tests exercise the full stack: Pydantic validation → DB →
|
|
JWT → response. The suite is also re-runnable without manual cleanup —
|
|
`backend/tests/conftest.py` has a session-scoped autouse fixture that
|
|
truncates all app tables once before the suite runs.
|
|
|
|
**Known coverage gaps** (real gaps, not placeholders — nothing enforces filling
|
|
these yet):
|
|
- No endpoint tests for `GET /api/worlds`, `GET /api/assets/*`, or any
|
|
world/asset CRUD routes — only auth endpoints have integration coverage
|
|
(`GET /api/worlds` is covered indirectly via the Godot smoke tests below).
|
|
- No tests for the moderation schema/migration beyond "the migration runs."
|
|
- No tests for the `GET /api/auth/me` endpoint's response body (only its
|
|
auth-header validation is covered via expired-token tests).
|
|
- No tests for session management (create/validate/revoke sessions).
|
|
|
|
## Godot client — `scripts/smoke_test_*.gd`
|
|
|
|
**6 smoke tests merged into `main`.** Each needs a live backend —
|
|
`AGP_API_BASE_URL` env var, falling back to the
|
|
`application/agp/api_base_url` project setting (default
|
|
`http://127.0.0.1:8000`) if unset.
|
|
|
|
| File | What it covers |
|
|
|---|---|
|
|
| `smoke_test_api.gd` | Exercises `ApiClient.health_check()` against a live backend. Verifies the real HTTP request path (`HTTPRequest` node lifecycle, JSON parse, result-dictionary contract). Exits 1 on failure. |
|
|
| `smoke_test_auth.gd` | Tests the full auth flow via `ApiClient` autoload: register unique user (201), duplicate username (409), under-18 registration (400), correct login (200), wrong password (401), nonexistent user (401). |
|
|
| `smoke_test_e2e.gd` | End-to-end flow: health check → register → login → worlds list. Verifies the full request chain with a fresh user, including token storage and `get_worlds()` with auth header. |
|
|
| `smoke_test_world_list.gd` | Instantiates `world_list.tscn` as a real scene, adds to tree (catches `@onready` node-path bugs), waits for `_refresh_worlds()` to complete, confirms the screen reaches a real end state (world cards, empty-list message, or error label — not stuck loading). |
|
|
| `smoke_test_main_menu_ui.gd` | Instantiates `main_menu.tscn`, confirms the auth panel starts hidden, and confirms a **real signal emission** on LoginButton/RegisterButton (not calling the handler method directly) actually opens it. This is the check that would have caught 2026-08-20's real bug: the auth panel and its logic were fully correct, but nothing in the scene was ever wired to open it, so Login/Register were completely unreachable from the UI. |
|
|
| `smoke_test_main_menu_full_flow.gd` | Full click-through: open the register form, fill it exactly as a user would, submit, confirm Play actually becomes enabled, the welcome message shows, and the auth buttons hide themselves. Calls the submit handler directly (awaited) rather than via `auth_button.pressed.emit()` — see the note at the top of the file: a synthetic `.emit()` on an `await`-using handler doesn't get driven forward reliably in `--script`/SceneTree headless mode the way real GUI input event dispatch does, confirmed by comparing direct-call vs `.emit()` behavior. Not a bug in the actual click-driven flow, just a headless-test-harness quirk to route around when writing tests. |
|
|
|
|
Run (once, to build the class cache): `godot --headless --path . --import`,
|
|
then for each smoke test: `godot --headless --path . --script
|
|
res://scripts/smoke_test_<name>.gd` — **no `--quit`**, it kills these before
|
|
their awaited HTTP calls finish.
|
|
|
|
**Known gaps:**
|
|
- No smoke tests for chunk loading/streaming (`chunk.gd`, `chunk_scene.gd`).
|
|
- No smoke tests for dynamic/static object nodes.
|
|
- All smoke tests require a live backend; no offline/unit smoke tests exist.
|
|
- `smoke_test_world_list.gd` and `smoke_test_main_menu_*.gd` are the only
|
|
ones that exercise a real `.tscn` scene instantiation — others only test
|
|
the `ApiClient` autoload directly.
|
|
- `get_me()` (`GET /auth/me`) is implemented in `scripts/api_client.gd` but
|
|
has no smoke coverage yet.
|
|
- The Login path (as opposed to Register) through `main_menu.gd` isn't
|
|
separately smoke-tested — it shares the same `_on_auth_button_pressed()`/
|
|
`_on_auth_complete()` code path already exercised for Register, but that's
|
|
inference, not a direct check.
|
|
|
|
## Client export
|
|
|
|
`scripts/build.sh` produces real Linux (`agp-game.x86_64`) and Windows
|
|
(`agp-game.exe`) binaries via `--export-release`. Verified 2026-08-20: both
|
|
exports complete clean from a fresh checkout and produce valid binaries
|
|
(confirmed via `file` — real ELF64/PE32+, not empty or truncated). Neither
|
|
export is exercised by an automated GUI test (headless Godot can't drive a
|
|
window) — actually launching and clicking through the exported binary is a
|
|
manual step, see `docs/checkpoints/PC1.md` for playtest instructions.
|
|
|
|
## What "full coverage" should eventually mean here
|
|
|
|
Not defined precisely yet — the honest target as of 2026-08-20 is
|
|
"integration tests for every endpoint + smoke tests for every major scene."
|
|
As real integration/endpoint tests get added, update the tables above
|
|
rather than letting this doc drift stale; a wrong inventory is worse than
|
|
no inventory.
|