rivencraft/docs/GAMETESTS.md

GameTest suites

The default dedicated-server run is a small smoke suite: 23 Rivencraft tests cover core linking, deterministic Age definition, writing persistence, legacy data migration, workstation transactions, and forged/replayed menu actions.

./gradlew runGameTestServer

The remaining 58 Rivencraft tests are archived, not deleted. They cover completed milestone details such as every Age terrain profile, Notebook and Desk surface interactions, refill edge cases, book assembly controls, and workstation break/drop behavior. Run only the relevant archive alongside the core tests when investigating an issue:

./gradlew runGameTestServer -ParchivedGameTestSuites=desk
./gradlew runGameTestServer -ParchivedGameTestSuites=grammar,binder

Available suite names are linking, environment, writing, grammar, desk, binder, mixer, and recipe. Run all 81 Rivencraft tests before a release or after broad cross-system changes:

./gradlew runGameTestServer -PwithArchivedGameTests=true

Each archive is selected by its rivencraft_archive_<suite> GameTest namespace. The suites share the normal empty test structure and do not need Create, Ponder, or Immersive Portals. The core suite delegates to the original regression methods for its selected cases, so the two suites do not maintain duplicate test logic.

GameTest Ages are created in build/gametest-run/world, not in a development client save. Every default GameTest invocation starts with a fresh world. Minecraft 1.21.1's GameTest server uses the fixed seed 0. Gradle deletes the world after every run, whether tests pass or fail. A forcibly killed run may leave world behind; the next run deletes it before starting. Logs and configuration remain available. Cleanup never targets a custom -PgameTestRunDir or a player world; callers using a custom directory manage it themselves. The full suite should still be run before shipping changes in the archived systems.

Manual Age unload/reload check

The automated suite does not unload a freshly generated Age. Minecraft can queue point-of-interest block updates after generation; closing that Age's region storage while a queued update is still pending can leave the dedicated GameTest server waiting forever in SectionStorage.readColumn. Plan save/load, terrain generation, and safe spawn remain automated; runtime unload/reload is checked in a normal game session:

1. Back up the test world. Bind one Link-Panel-only Descriptive Book and one Descriptive Book with a terrain page (for example, Island), using distinct names. Bring a working way back to the Overworld.
2. Travel through each book, confirm the named Age and expected terrain, then return to the Overworld. Close book screens and wait a few seconds.
3. With cheats enabled, run /rivencraft age list and record each Age's rivencraft:age/... dimension ID. Run /rivencraft age unload <dimension> for one Age at a time, then list again to confirm it is unloaded.
4. Reopen the same Descriptive Books and travel back. Confirm each book reaches its original Age, the terrain and safe arrival remain intact, and no extra Age entry was created. Save, restart the world, and repeat the book check.