The command tables and the page-side reads, screens and dispatch (scripts/lib/mcp-commands.js and
mcp-page.js) become src/agent/, the facade window.TUBES.call(tool, args) in the page's own scope.
A new <!-- @include-dev agent --> line in src/index.html pastes it in after the game, but only in the
development page (npm run dev, the MCP server, i18n-check, tests that ask with load({agent:true})).
The build drops the line whole: _site/ is byte for byte what main builds.
Tests load the page players get by default, the build test fails if anything outside src/agent/ names
the facade's api/API_ names, and the pages test checks the built page carries none of it and still
plays. ADR 0004 records the rule.
56 lines
2.8 KiB
Markdown
56 lines
2.8 KiB
Markdown
---
|
|
name: write-tests
|
|
description: Write deterministic jsdom tests for Series of Tubes features and fixes in tests/*.test.js.
|
|
---
|
|
|
|
# Writing tests
|
|
|
|
Tests use `node:test` and `tests/harness.js`, which assembles the game page from `src/`
|
|
(once per test file) and loads it in jsdom with the animation loop off, a seeded `Math.random` and a recording fake canvas.
|
|
Code runs inside the page through `ev()`. `load()` is the page players get; tests of the agent facade
|
|
(`src/agent/`, `window.TUBES`) ask for the development page with `load({ agent: true })`.
|
|
|
|
## Pattern
|
|
|
|
```js
|
|
const test = require('node:test');
|
|
const assert = require('node:assert/strict');
|
|
const { load } = require('./harness');
|
|
|
|
test('what the player should see happen', () => {
|
|
const { ev, errors } = load();
|
|
ev("ACT.start({});S.cash=1e8;for(const g of GOALS)S.done[g.id]=0;ACT.launchBB({city:'fra'})");
|
|
ev("ACT.buyTransit({city:'fra',net:'cog',tier:1});compute()");
|
|
assert.ok(ev("R.served") > 0);
|
|
assert.deepEqual(errors, []); // always: no page errors
|
|
});
|
|
```
|
|
|
|
## Where to put it
|
|
|
|
Pick the suite by topic: `game` (core loop), `build`, `persist` (save/import/migrate),
|
|
`services` (customers), `peering`, `issues` (GitHub issue regressions, name them
|
|
`#NN …`), `regions`, `modes` (scenarios, sandbox, weekly), `i18n`, `pages` (hosting).
|
|
For a new feature, prefer a new file named after it (`tests/route-servers.test.js`): every
|
|
`tests/*.test.js` runs on its own (`scripts/test.js`), and a file of your own never conflicts
|
|
with someone else's tests. Appending to the big suites (`issues`, `regions`) is where
|
|
pull requests collide. Run one file with `npm test -- tests/route-servers.test.js`.
|
|
|
|
## Rules
|
|
|
|
- **Text in assertions:** match what the player sees (`/Ready in about 3 days/`), or compare with
|
|
`ev("tr('pnis.ready_in_about_n_days',{n:3})")`. Tests run the source page, where labels are readable;
|
|
the shipped page (ids instead of labels) is covered by `tests/pages.test.js`.
|
|
- **Deterministic.** Never rely on luck. Use the default seed, `window.__reseed(n)`,
|
|
or set state directly (`S.day=…`, `S.ev.x=…`).
|
|
- **Force a specific random failure or event** by patching the picker:
|
|
```js
|
|
ev("eval('('+fireFailure.toString().replace('const e=pick(opts);',\"const e='crash';\")+')')()");
|
|
```
|
|
Check the current source for the exact `pick` line first (`grep -rn "function fireFailure" src/game`); it may differ.
|
|
- **Drive the game through `ACT`** like a player would, then `compute()` or `dayTick()`.
|
|
- **Saves:** for persistence changes, round-trip `JSON.stringify(S)` through
|
|
`parseSave()`/`migrate()`, and test that an *old* save without the new field still loads.
|
|
- **UI:** render with `renderAll()` and query `dom.window.document`; check phone
|
|
layouts by setting `window.innerWidth = 390` before rendering.
|
|
- Run `npm test`; the whole suite must pass, not just the new test.
|