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 --version to 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:

js
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:

js
// 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:

js
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.

text
✔ 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.265478

What 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:

js
// 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:

sh
HANDLER=./naive.mjs npm test
text
✖ 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 6

Every 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:

sh
HANDLER=./my-app.mjs npm test

If 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.

js
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();
sh
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.mjs doesn't handle resync_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.mjs sends the key in the Authorization header, which Node's WebSocket allows and a browser's doesn't. Keep the key on a server.
  • live.mjs doesn't time heartbeats. The stream sends one every 5 seconds and expects a client that misses three to reconnect. live.mjs reconnects only when the socket closes or a connection fails.

Run it

sh
npm test
HANDLER=./naive.mjs npm test

Then write the adapter for your own handler and run the tests against it.

More from Build with Statpad