Build with StatpadTestingNFL
Test that your live client gets a real game right
A six-test node:test file sends all 1,277 changes of a recorded NFL game through your change handler and checks what your app would show at the moments that break live clients.
A live client can pass every test you write by hand and still show the wrong thing during a real game. In Bills at Vikings on November 9, 2026, replay reversed a Josh Allen fumble 14 changes after the fumble arrived. James Cook's touchdown came in worth 6 points and came back 5 changes later worth 7. And after the final whistle, the last change rewrote a first-quarter run.
Statpad recorded that game's upstream feed and replayed it through its ingest pipeline, which produced 1,277 changes, in the order the stream sends them. This post turns them into a test file. You send the changes through your own change handler, the way the stream would, and check what your app shows at those moments: one touchdown, the reversed play instead of the fumble, a score that never drops and the right last play. The tests run in a tenth of a second, with no API key and no live game.
What you need
- Node.js 22.18 or later. Run
node --versionto check. - The code. Download journal-client-tests.zip and unzip it. It has no packages to install.
The zip holds the recorded journal as changes.ndjson. It's the same file as statpad.dev/samples/nfl-bills-at-vikings/changes.ndjson.
The journal as stream messages
Each line of changes.ndjson is one change: a seq, an entity type and id, a version and the entity's new payload. The stream sends the same changes inside changes messages. journal.mjs wraps each line in one of those messages and passes it to a handler:
import { readFileSync } from 'node:fs';
export const GAME_ID = '01a1d60f-67be-7bdd-83f4-53286521d9bb';
// Bills at Vikings, November 9, 2026: every change on game:<id>, in seq order.
// The same file is at https://statpad.dev/samples/nfl-bills-at-vikings/changes.ndjson
export const changes = readFileSync(new URL('./changes.ndjson', import.meta.url), 'utf8')
.trim()
.split('\n')
.map((line) => JSON.parse(line));
// Sends the journal to a handler up to seq `through`, one `changes` message per change.
export function play(game, through = Infinity, after = () => {}) {
for (const change of changes) {
if (change.seq > through) break;
game.apply({ type: 'changes', stream: `game:${GAME_ID}`, changes: [change] });
after(change.seq);
}
return game;
}The real stream sends up to 500 changes in one message when a client catches up. Your handler should loop over message.changes either way, so one change per message is enough for the tests.
The handler under test
game.mjs is the handler the tests pass with. It stands in for the part of your app that takes stream messages and keeps the game's state:
// A live game the way an app keeps it: the newest version of every entity, keyed by type and id.
// apply() takes the stream's `changes` messages. view() is what the app shows.
export function createGame() {
let seq = 0;
const latest = new Map();
return {
get seq() {
return seq;
},
apply(message) {
if (message.type !== 'changes') return;
for (const change of message.changes) {
if (change.seq !== seq + 1) throw new Error(`missed a change: expected seq ${seq + 1}, got ${change.seq}`);
seq = change.seq;
const key = `${change.entity_type}:${change.entity_id}`;
if (change.op === 'delete') latest.delete(key);
else latest.set(key, change.payload);
}
},
view() {
const all = (type) => [...latest].filter(([key]) => key.startsWith(`${type}:`)).map(([, payload]) => payload);
const game = all('game')[0];
const plays = all('play').sort((a, b) => a.sequence - b.sequence);
return {
status: game?.status,
score: { away: game?.away_score ?? 0, home: game?.home_score ?? 0 },
plays,
lastPlay: plays.at(-1) ?? null,
};
},
};
}Four choices in it decide whether the tests pass:
- It keeps one copy of each entity, keyed by type and id. When a play changes, Statpad sends the same id again with a higher
version, so replacing by id keeps one copy of the newest version. In this game, 83 of the 270 play changes rewrite a play that had already arrived. - It orders plays by
sequence, not by arrival. A play can arrive after the plays that follow it. At seq 1243 a Max Brosmer pass arrives for the first time, after the two-minute warning that comes after it in the game. - It takes the score from the game record. Every play carries the score as it stood after that play, and a rewrite of an old play brings back that old score.
- It checks that each change follows the last. The stream's seqs have no gaps, so a seq that skips one means your client missed a change.
The tests
test/game.test.mjs has six tests. Each one names the seqs it checks. These three are the reversed fumble, the score and the last play:
test('the reversed fumble replaces the fumble', () => {
const [fumble] = shown(at(507), ALLEN_FUMBLE);
assert.match(fumble.description, /RECOVERED by MIN/);
const reversed = shown(at(520), ALLEN_FUMBLE);
assert.equal(reversed.length, 1, 'seq 520: the fumble and its reversal are both shown');
assert.match(reversed[0].description, /the play was REVERSED/);
assert.equal(reversed[0].football.is_turnover, false);
});
test('the score never goes backwards', () => {
// No points came off the board in this game, so a score that drops is a bug.
const game = createGame();
let last = { away: 0, home: 0 };
play(game, Infinity, (seq) => {
const { score } = game.view();
assert.ok(score.away >= last.away && score.home >= last.home, `seq ${seq}: ${last.away}-${last.home} became ${score.away}-${score.home}`);
last = score;
});
});
test('the final shows the last play of the game, once per play', () => {
// The last change, seq 1277, rewrites a first-quarter play after the final whistle.
const final = at(Infinity);
assert.equal(final.lastPlay.description, 'END GAME', `the last play shown is "${final.lastPlay.description}"`);
assert.equal(final.status, 'complete');
assert.deepEqual(final.score, { away: 23, home: 6 });
assert.equal(new Set(final.plays.map((p) => p.id)).size, final.plays.length, 'a play is shown more than once');
// A Brosmer pass first arrives at seq 1243, after the two-minute warning that follows it.
assert.ok(final.plays.every((p, i) => i === 0 || final.plays[i - 1].sequence < p.sequence), 'plays are not in game order');
assert.equal(final.plays.length, 187);
});The other three check the Cook touchdown at seqs 1106 and 1111, a Carson Wentz pass that Buffalo's challenge turned into a fumble at seq 199, and what happens when seq 12 arrives right after seq 10.
✔ the Cook touchdown shows once and gains its extra point (6.16683ms)
✔ the reversed fumble replaces the fumble (2.238123ms)
✔ the challenged pass becomes a Buffalo recovery (0.56901ms)
✔ the score never goes backwards (37.339094ms)
✔ the final shows the last play of the game, once per play (2.444315ms)
✔ a missed change is caught (0.343631ms)
ℹ tests 6
ℹ suites 0
ℹ pass 6
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 126.265478What the shortcuts look like
naive.mjs has the same interface as game.mjs and takes two shortcuts that show up in a lot of first live clients. It appends each play as it arrives, and it shows the score from the newest play:
// The same interface, written with two common shortcuts: plays are appended as they arrive,
// and the score comes from the newest play.
export function createGame() {
let status;
let score = { away: 0, home: 0 };
const plays = [];
return {
apply(message) {
for (const change of message.changes ?? []) {
if (change.entity_type === 'game') status = change.payload.status;
if (change.entity_type !== 'play') continue;
plays.push(change.payload);
score = { away: change.payload.away_score, home: change.payload.home_score };
}
},
view: () => ({ status, score, plays, lastPlay: plays.at(-1) ?? null }),
};
}Run the tests against it with HANDLER:
HANDLER=./naive.mjs npm test✖ the Cook touchdown shows once and gains its extra point
AssertionError [ERR_ASSERTION]: seq 1111: the touchdown is shown more than once
✖ the reversed fumble replaces the fumble
AssertionError [ERR_ASSERTION]: seq 520: the fumble and its reversal are both shown
✖ the challenged pass becomes a Buffalo recovery
AssertionError [ERR_ASSERTION]: seq 199: the pass and the ruling are both shown
✖ the score never goes backwards
AssertionError [ERR_ASSERTION]: seq 270: 3-0 became 0-0
✖ the final shows the last play of the game, once per play
AssertionError [ERR_ASSERTION]: the last play shown is "J.Cook left end to MIN 21 for -2 yards (E.Wilson).Penalty on BUF-T.Grable, Offensive Holding, declined."
✖ a missed change is caught
AssertionError [ERR_ASSERTION]: Missing expected exception: seq 12 arrived after seq 10 and nothing noticed
ℹ tests 6
ℹ pass 0
ℹ fail 6Every failure names a real moment. At seq 270 a first-quarter Cook run comes back as version 4 with the score it had when he ran it, 0–0, so a 3–0 game shows 0–0. At seq 1277 the last change rewrites another first-quarter run, and the final score shows as 0–0. The chart at the top of this post plots Buffalo's score from each handler after every change.
Test your own handler
Write a small module that exports createGame() and wraps your own code. apply(message) passes the message to your handler. view() reads your app's state and returns { status, score: { away, home }, plays, lastPlay }. Then point the tests at it:
HANDLER=./my-app.mjs npm testIf your app keeps state in a store or a UI framework, have view() read from the store, not from the messages. The tests should check what your app would show.
Follow a live game with the same handler
live.mjs connects game.mjs to the stream. It subscribes to one game and always resumes from the last seq it applied, so after a dropped connection it gets exactly the changes it missed. On the first connection that seq is 0, so the handler sees every change of the game, as it does in the tests.
import { createGame } from './game.mjs';
// Follows one game on the stream with the handler the tests check. Needs a key on Pro or Business.
const [gameId] = process.argv.slice(2);
const key = process.env.STATPAD_API_KEY;
if (!gameId || !key) {
console.error('usage: STATPAD_API_KEY=sporty_... node live.mjs <game id>');
process.exit(1);
}
const url = process.env.STATPAD_STREAM_URL ?? 'wss://stream.statpad.dev/v1/stream';
const stream = `game:${gameId}`;
const game = createGame();
function connect() {
const ws = new WebSocket(url, { headers: { Authorization: `Bearer ${key}` } });
// Resume from the last seq applied: 0 the first time, so the handler sees every change, as in the tests.
const subscribe = () => ws.send(JSON.stringify({ type: 'subscribe', id: 'game', streams: [stream], resume: { [stream]: game.seq } }));
ws.onmessage = ({ data }) => {
const message = JSON.parse(data);
if (message.type === 'welcome') subscribe();
else if (message.type === 'error' && message.code === 'slow_consumer') subscribe();
else if (message.type === 'error') console.error(`${message.code}: ${message.message}`);
else if (message.type === 'changes') {
try {
game.apply(message);
} catch (error) {
console.error(error.message);
return ws.close();
}
const { score, lastPlay } = game.view();
console.log(`seq ${game.seq} ${score.away}-${score.home} ${lastPlay?.description ?? ''}`);
}
};
let retrying = false;
const retry = (why) => {
if (retrying) return;
retrying = true;
console.log(`${why}, resuming after seq ${game.seq}`);
setTimeout(connect, 2_000);
};
ws.onerror = () => retry('connection failed');
ws.onclose = ({ code }) => {
if (code === 1008) return console.error('closed 1008: the key is invalid or has no streaming access');
retry(`closed ${code}`);
};
}
connect();STATPAD_API_KEY=sporty_... node live.mjs <game id>Get a game id from GET /v1/nfl/games for today's date. Each message prints the seq, the score and the last play. Streaming needs Pro ($49 a month, 5 WebSocket connections) or Business ($299 a month). Developer ($19 a month) is REST only.
Limits
- The tests use one recorded NFL game. Other games and leagues send other moments, so add tests when you record your own.
- "The score never goes backwards" holds for this game because no points came off the board. In a game where replay takes away a touchdown, the score goes down, and your test should expect that.
live.mjsdoesn't handleresync_required, which the stream sends when a resume point is older than the game's retained history. It prints the error and gets no more changes. Game streams can be resumed for at least 7 days after the game ends.live.mjssends the key in theAuthorizationheader, which Node'sWebSocketallows and a browser's doesn't. Keep the key on a server.live.mjsdoesn't time heartbeats. The stream sends one every 5 seconds and expects a client that misses three to reconnect.live.mjsreconnects only when the socket closes or a connection fails.
Run it
npm test
HANDLER=./naive.mjs npm testThen write the adapter for your own handler and run the tests against it.
More from Build with Statpad
- Ask Claude about an NFL game while it replays on your laptopA small Node server replays the recorded Bills at Vikings game on localhost. Point @statpad/mcp at it, ask Claude who has the ball, then move the game forward and watch the answer change when replay overturns a fumble.
- A shot map of Manchester United 4–4 Aston Villa in 125 lines of TypeScriptEvery shot in Statpad's Premier League play-by-play has pitch coordinates. This script turns one 8-goal draw into an SVG shot map and a score timeline, and covers the two coordinate traps.
- A live NFL scoreboard in SwiftUI, and the small server that holds the keyA Node server on @statpad/sdk holds the Statpad key and one stream subscription, and a SwiftUI app resumes from it by seq, tested against a recorded Bills at Vikings game.
- A fantasy football scoreboard for your Discord channelA first project with the Statpad API. One small Node script scores a fantasy matchup from NFL box scores and keeps a single Discord message up to date through a channel webhook.