loop: baseline

docs/TESTING.md

@@ -1,7 +1,9 @@
 # TESTING.md
 
 Runner: built-in `node:test` + `node:assert/strict`. No Jest/Mocha.
-Script: `"test": "node --test tests/"` (add `--test-concurrency=1` if DB tests collide).
+Script: `"test": "NODE_ENV=test node --test --test-concurrency=1"`.
+**Do NOT pass a directory or an unquoted glob** (`node --test tests/` finds nothing on Node 21+; `tests/**/*.test.js` is expanded by `sh` and skips top-level files). Plain `node --test` auto-discovers every `*.test.js`.
+Test files MUST be named `*.test.js`.
 
 ## Layout
 - `tests/unit/` — pure functions in `src/game` and `src/utils`. No DB, no HTTP.
@@ -37,6 +39,9 @@ Inject time: tests set `time.setNow(fn)` to fast-forward energy/expeditions inst
 `describe('energy.computeEnergy', () => { it('caps at max', ...) })`.
 
 ## Rules
+- Run `npm test` and check the TOTAL against the sum of tests in all `*.test.js` files. A bad glob once silently skipped 17 tests.
+- Integration tests use `setup()` from `tests/helpers.js`, which clears every `src/` module from the require cache so each test gets a fresh app and DB. Never hand-pick modules to clear.
+- Force game outcomes with test-only zones/monsters and the `{ rng, now }` options of services — don't rely on luck, and don't weaken assertions to "winner is hero or monster".
 - A failing test is never deleted to make the suite green. Fix the code or log a Known Issue.
 - New bug → write the failing test first, then fix.
 - Update the Test Summary table in STATUS.md after each phase.