Skip to content

Commit 47f13a0

Browse files
Timehueclaude
andcommitted
test(runner): name the child-process crash behind a file-level failure
`npm test` intermittently reported `✖ api/player/world-position.integration.test.ts` with the bare error `test failed` at `1:1` while all 23 of its subtests printed ✔. node:test marks a FILE failed when its child process exits non-zero, and the spec reporter prints only that bare string — `error.exitCode` and `error.signal` are dropped. So the one number that says whether a test failed, a late rejection set exit code 1, or the process died natively was never shown. Over 500+ runs under load, instrumented with a preload logging `unhandledRejection`, `uncaughtException` and `exit`, found ZERO unhandled rejections and a clean exit every time but one: that copy died ~300ms after the Socket.IO layer attached with no stderr and no `exit` event — a native crash, not a leaked promise. The fire-and-forget `settleTravelLease(...).catch(...)` path is not at fault. Local Node is 24.15.0 while .nvmrc/Dockerfile/CI pin 22 (nodejs/node#62991 reports 24.15.0-only native crashes on Windows under load; #56645 is a libuv abort at exit). - run-tests.mjs now prints `child process exited with code N (0xHEX)` plus any signal on a file-level fail, and warns when the running Node major != .nvmrc. - The socket test's teardown now disconnects the client and awaits `disconnect` BEFORE closing the Socket.IO and HTTP servers, so nothing is mid-handshake at exit. Hygiene — timing is unchanged against the baseline. - CLAUDE.md documents the signature so the next reader doesn't re-debug the file. No gameplay behavior changes. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent 30c3745 commit 47f13a0

3 files changed

Lines changed: 53 additions & 3 deletions

File tree

‎CLAUDE.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,12 @@ unreachable. `server-routes.test.ts` enforces this both ways
104104
short explicit list at the top of that script — which is why the two repo-root
105105
files (`cpanel-dns.test.cjs`, `server-routes.test.ts`) are listed there. Put new
106106
tests under a scan root, or they silently never run.
107+
- **A test FILE going red with every subtest green** (`✖ api/x.test.ts` + the bare
108+
`'test failed'` at `1:1`) means the child process exited non-zero, not that a test
109+
failed. The runner prints `child process exited with code N (0xHEX)` under it;
110+
a code in the `0xC0000000` range is a native node.exe crash. Traced 2026-09-08 to
111+
running the suite on Node 24.15.0 on Windows (the repo pins 22 in `.nvmrc`) —
112+
run local tests on the pinned major before suspecting the file.
107113
- Frontend conventions (the App.tsx drain rule and its line-budget ratchet) live
108114
in `shinobij.client/CLAUDE.md`, loaded when working under that directory.
109115

‎api/player/world-position.integration.test.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -361,10 +361,19 @@ test('Academy trace sees a settled arrival and ceremony replay cannot teleport t
361361
});
362362

363363
// Includes cold Socket.IO module startup and shutdown alongside the full suite.
364+
// Teardown is fully quiesced before the test ends -- the client disconnects and
365+
// reports it, THEN the Socket.IO server and its HTTP server close -- so the
366+
// process reaches exit with no socket mid-handshake. This is the only file in
367+
// the suite whose child holds live TCP handles, and a file-level 'test failed'
368+
// with every subtest green here is a child-process crash (see the exit-code
369+
// line scripts/run-tests.mjs prints), not a leaked rejection: 300+ instrumented
370+
// runs found no unhandled rejection and no open handle. (2026-09-08)
364371
test('a real socket reconnect discards delayed hydration superseded by HTTP presence', { timeout: 30_000 }, async (t) => {
365372
const sockets = await import('../_realtime/socket.js');
366373
const server = createServer();
367374
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
375+
// Registered first so it runs LAST (hooks run in registration order): the
376+
// client hook below must have disconnected before the server goes away.
368377
t.after(async () => { await sockets.closeSocketServer(); if (server.listening) await new Promise<void>((resolve) => server.close(() => resolve())); });
369378
sockets.attachSocketServer(server);
370379
for (let attempt = 0; !sockets.getIo() && attempt < 200; attempt++) await delay(5);
@@ -374,7 +383,10 @@ test('a real socket reconnect discards delayed hydration superseded by HTTP pres
374383
const { io } = createRequire(resolve('shinobij.client/package.json'))('socket.io-client');
375384
const client = io(`http://127.0.0.1:${address.port}`, { transports: ['websocket'], reconnection: false, autoConnect: false,
376385
auth: { 'x-player-name': PLAYER, 'x-player-token': token } });
377-
t.after(() => client.close());
386+
t.after(async () => {
387+
if (!client.connected) { client.close(); return; }
388+
await new Promise<void>((resolve) => { client.once('disconnect', () => resolve()); client.close(); });
389+
});
378390
await new Promise<void>((resolve, reject) => { client.once('connect', resolve); client.once('connect_error', reject); client.connect(); });
379391
const walked = await import('../_realtime/walked-tile.js');
380392
await walked.noteWalkedTile(kv, PLAYER, 12, 77);

‎scripts/run-tests.mjs‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { readdirSync } from 'node:fs';
1+
import { readdirSync, readFileSync } from 'node:fs';
22
import { join, relative, resolve } from 'node:path';
33
import { run } from 'node:test';
44
import { spec } from 'node:test/reporters';
@@ -49,6 +49,20 @@ if (sharded) {
4949
process.exit(1);
5050
}
5151
}
52+
// The engine this repo targets is pinned in .nvmrc (mirrored by the Dockerfile
53+
// and CI). A different local major is not an error, but it is the first thing
54+
// to suspect when a file goes red at FILE level with every subtest green: that
55+
// is how a native node.exe crash surfaces (see the exit-code logging below),
56+
// and the 2026-09 investigation traced exactly that to Node 24.15.0 on Windows.
57+
const pinnedMajor = (() => {
58+
try { return Number.parseInt(readFileSync(join(root, '.nvmrc'), 'utf8').trim(), 10); } catch { return NaN; }
59+
})();
60+
const runningMajor = Number.parseInt(process.versions.node, 10);
61+
if (Number.isInteger(pinnedMajor) && runningMajor !== pinnedMajor) {
62+
console.error(`[run-tests] warning: running on Node ${process.versions.node}; .nvmrc pins ${pinnedMajor}. ` +
63+
'A file-level failure with every subtest passing is usually a child-process crash, not a test bug.');
64+
}
65+
5266
const tests = run({ cwd: root, files: shardFiles, concurrency: true });
5367

5468
// Do NOT rely on `test:fail` alone to decide the exit code. It misses failure
@@ -63,7 +77,25 @@ let failEvents = 0;
6377
let finalSummary = null;
6478
let streamError = null;
6579

66-
tests.on('test:fail', () => { failEvents++; });
80+
tests.on('test:fail', (event) => {
81+
failEvents++;
82+
// node:test marks a FILE failed when its child process exits non-zero, and the
83+
// spec reporter prints only the bare 'test failed' for it -- the exit code and
84+
// signal live on the error object and are otherwise dropped. Print them, so a
85+
// child that died natively (all subtests green, no stack, no stderr) is
86+
// recognisable as such. Windows reports a native fault as an NTSTATUS in the
87+
// 0xC0000000 range, e.g. 0xC0000409 (libuv fatal abort), 0xC0000374 (heap
88+
// corruption), 0xC0000005 (access violation).
89+
const error = event?.details?.error;
90+
const exitCode = error?.exitCode;
91+
const signal = error?.signal;
92+
if (event?.nesting === 0 && (exitCode != null || signal != null)) {
93+
const hex = typeof exitCode === 'number' ? ` (0x${(exitCode >>> 0).toString(16).toUpperCase().padStart(8, '0')})` : '';
94+
console.error(`\n✖ ${event.file ?? event.name}: child process exited with code ${exitCode}${hex}` +
95+
(signal ? ` signal ${signal}` : '') +
96+
' -- if every subtest above it passed, the process crashed after (or outside) the tests.');
97+
}
98+
});
6799
tests.on('test:summary', (summary) => {
68100
// Per-file summaries carry a `file`; the single run-wide summary does not.
69101
if (!summary.file) finalSummary = summary;

0 commit comments

Comments
 (0)