Testing - tableverse-kit

Test the executor your game exports. This covers input schemas, validation, execution, stage transitions, events, and visibility together. Add Vitest when you are ready to write engine tests:

npm install --save-dev --workspace=engine vitest
npm pkg set scripts.test="vitest run" --workspace=engine
npm test --workspace=engine

Test one command

import { expect, test } from "vitest";
import { executor } from "../src/game.ts";

test("the active player advances", () => {
  const initial = executor.createInitialState({
    seed: "test-seed",
    players: ["p1", "p2"],
  });

  const result = executor.executeCommand(initial, {
    type: "advance",
    actorId: "p1",
    input: { spaces: 2 },
  });

  expect(result.ok).toBe(true);
  expect(result.state.game.positions.p1).toBe(2);
  expect(initial.game.positions.p1).toBe(0);
});

Use a fixed seed in every test. A failure then reproduces the same shuffles and rolls.

Test rejection

test("a player cannot move out of turn", () => {
  const state = executor.createInitialState({
    seed: "test-seed",
    players: ["p1", "p2"],
  });

  const result = executor.executeCommand(state, {
    type: "advance",
    actorId: "p2",
    input: { spaces: 2 },
  });

  expect(result).toMatchObject({
    ok: false,
    reason: "not_active_player",
    state,
    events: [],
  });
});

Also test every reason returned by your own .validate() callbacks.

Test a complete scenario

runScenario applies a sequence and collects every result:

import { runScenario } from "@tableverse-kit/engine";

const scenario = runScenario(
  executor,
  [
    { type: "advance", actorId: "p1", input: { spaces: 2 } },
    { type: "advance", actorId: "p2", input: { spaces: 1 } },
  ],
  { seed: "scenario-seed", players: ["p1", "p2"] },
);

expect(scenario.results.every((result) => result.ok)).toBe(true);
expect(scenario.finalState.game.positions).toEqual({ p1: 2, p2: 1 });

The argument after the command array is the same init object you pass to createInitialState. Add setup to it when your definition declares setup input.

Test hidden information

Create views for at least the owner, another player, and a spectator:

const forP1 = executor.getView(state, {
  kind: "player",
  playerId: "p1",
});
const forP2 = executor.getView(state, {
  kind: "player",
  playerId: "p2",
});

expect(forP1.game.players.p1?.hand).toEqual([3, 8]);
expect(forP2.game.players.p1?.hand).toEqual({
  __hidden: true,
  value: { count: 2 },
});

Test events and transitions

Successful results include both your domain events and engine stage events:

expect(result.events).toContainEqual({
  category: "domain",
  type: "advanced",
  payload: { actorId: "p1", spaces: 2 },
});

expect(result.state.runtime.progression.currentStage).toMatchObject({
  id: "player_turn",
  kind: "activePlayer",
  activePlayerId: "p2",
});

Prefer assertions about player-visible rules and outcomes. Avoid tests that depend on private builder objects or schema implementation details.

​Test one command

​Test rejection

​Test a complete scenario

​Test hidden information

​Test events and transitions

Test one command

Test rejection

Test a complete scenario

Test hidden information

Test events and transitions