modbison/docs/testing/test_inventory.md

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. 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	Real integration tests against the FastAPI app via TestClient: register, login, duplicate username/email, wrong password, JWT shape. Hits a real Postgres, not mocked (PR #35).
test_refresh_endpoint.py	8	POST /auth/refresh end-to-end: valid token exchange, distinct access tokens per call (jti-based), invalid/missing token rejection, login-issued tokens also work (PR #37).
test_refresh_token_jti.py	6	Refresh-token jti uniqueness and the refresh_tokens.token column length/type (PR #33's RS256 upgrade).
test_auth_expired_token.py	5	Expired-token rejection on two distinct paths: an access JWT with a past exp claim, and a refresh token whose persisted expires_at is in the past (PR #38).

What changed since the last inventory (2026-08-19): that version said "no integration/endpoint tests at all" — that gap is closed. test_auth_endpoints.py, test_refresh_endpoint.py, test_refresh_token_jti.py, and test_auth_expired_token.py all hit the real FastAPI app against a real Postgres, not mocks. The suite is also re-runnable without manual cleanup now — 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):

• /worlds (POST) and /assets/* have no endpoint tests yet — GET /worlds is covered indirectly via the Godot smoke tests below, but there's no pytest coverage for either.
• No tests for the moderation schema/migration — it exists (0003_add_moderation_tables_and_user_roles) and the migration itself runs clean, but nothing in backend/tests/ exercises the models or any moderation endpoint (there isn't one yet).

Godot client — scripts/smoke_test_*.gd

4 real smoke tests merged on 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.

Run: godot --headless --path . --import once (builds the class cache — skip this and every class_name-declared class falsely errors as undeclared), then for each file below: godot --headless --path . --script res://scripts/<name>.gd — no --quit, it kills these before their awaited HTTP calls finish.

File	What it covers
smoke_test_api.gd	ApiClient.health_check() against a live backend — the HTTP request path itself (HTTPRequest node lifecycle, JSON parse, result-dictionary contract).
smoke_test_auth.gd	6 real scenarios end-to-end: register, duplicate username, under-18 rejection, correct login, wrong password, non-existent user.
smoke_test_e2e.gd	Full loop: health check → register → login → fetch worlds list, 4/4 steps.
smoke_test_world_list.gd	Instantiates the real world_list.tscn scene (not just the API layer) — registers a user, adds the scene to the tree, confirms it reaches a real end state (cards, empty-list, or error) and actually renders world cards when data exists.

Known gap: get_me() (GET /auth/me) is implemented in scripts/api_client.gd but has no smoke coverage yet.

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 the checkpoint playtest instructions.

What "full coverage" should eventually mean here

Not defined precisely yet — the honest target is "close the /worlds POST and /assets/* gaps next, and add get_me() smoke coverage" rather than a number. 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.