@eigeninteractive/testkit 0.5.1 → 0.6.0

package/dist/twin-fixtures.d.ts

@@ -1,145 +0,0 @@
-/**
- * Twin-drift fixture runner: the TS half of the shared JSON fixtures that
- * keep a version unit's TS and Dart `GameRules` twins in sync. The JSON
- * fixture format is shared verbatim with the Dart runner
- * (`lib/testing/twin_fixtures.dart`): one file, two consumers.
- *
- * One fixture file per concern lives beside the version units at
- * `<fixturesRoot>/v<N>/*.json` and is consumed by BOTH sides: this module
- * runs each case against the TS unit (schemas + `applyAction` +
- * `computeObservation` + the two predicates), while the Dart runner runs the
- * same file against the Dart twin (generated payload parsing,
- * `isValidAction`, `previewAction`, predicate twins). A behavioral divergence
- * then fails one side's CI instead of degrading UX in production.
- *
- * ## Fixture file format
- *
- * ```jsonc
- * {
- *   "schemaVersion": 1,
- *   "cases": [
- *     {
- *       "kind": "action",
- *       "name": "seat 0 marks an empty cell",
- *       "config": {},
- *       "state": { ... },            // TS: applyAction input
- *       "obs": { ... },              // Dart-only; defaults to `state`
- *       "pending": [0],
- *       "playerIndex": 0,
- *       "participantCount": 2,       // optional, default 2
- *       "rngSeed": "any string",     // optional, default "twin-fixtures"
- *       "action": { ... },
- *       "expected": {
- *         "valid": true,             // false ⇒ TS IllegalMoveError,
- *                                    //         Dart isValidAction false
- *         "state": { ... },          // optional, TS envelope.state
- *         "pending": [1],            // optional, TS envelope.pendingPlayers
- *         "outcome": [ ... ],        // optional, TS envelope.outcome
- *                                    //   (null asserts the game is ongoing)
- *         "observation": { ... }     // optional, the actor's post-action
- *                                    //   view: TS computeObservation slice
- *                                    //   data; Dart previewAction (when the
- *                                    //   game implements optimism)
- *       }
- *     },
- *     { "kind": "playerLimits", "name": "...", "config": {},
- *       "expected": { "minPlayers": 2, "maxPlayers": 2 } },
- *     { "kind": "ratingPool",  "name": "...", "access": "public",
- *       "minPlayers": 2, "maxPlayers": 2, "config": {}, "expected": "blitz" },
- *     { "kind": "botSeatable", "name": "...", "gameConfig": {},
- *       "botConfig": {}, "expected": false }
- *   ]
- * }
- * ```
- *
- * The `state`/`obs` split exists for hidden-info games (a seat's observation
- * is not the state); perfect-info games omit `obs`. `expected.observation` is
- * the shared behavioral anchor: the TS side must project the post-action
- * state to it, and a Dart `previewAction` that returns non-null must predict
- * it, so the two sides are compared through one recorded value.
- *
- * Wire it up in a game-owned test file running under plain-Node vitest:
- *
- * ```ts
- * import { twinFixtureTests } from "@eigeninteractive/testkit";
- * import gameModule from "../src/module/index.js";
- *
- * twinFixtureTests(gameModule, new URL("../src/module/fixtures/", import.meta.url));
- * ```
- */
-import { type GameAccess, type GameModule, type GameRules, type Json, type JsonObject, type OutcomeEntry } from "@eigeninteractive/rules";
-/** One fixture file: cases targeting one `schemaVersion` unit. */
-export interface TwinFixtureFile {
-    schemaVersion: number;
-    cases: TwinFixtureCase[];
-}
-/** A game-action case: exercises schemas, `applyAction`, and (through
- * `expected.observation`) `computeObservation` for the acting seat. */
-export interface ActionCase {
-    kind: "action";
-    name: string;
-    config: JsonObject;
-    state: JsonObject;
-    /** Dart-side observation payload; unused here (defaults to `state`). */
-    obs?: JsonObject;
-    pending: number[];
-    playerIndex: number;
-    participantCount?: number;
-    rngSeed?: string;
-    action: JsonObject;
-    expected: {
-        valid: boolean;
-        state?: JsonObject;
-        pending?: number[];
-        outcome?: OutcomeEntry[] | null;
-        observation?: JsonObject;
-    };
-}
-/** A `ratingPool` predicate case. Omitted timing fields mean null. */
-export interface RatingPoolCase {
-    kind: "ratingPool";
-    name: string;
-    access: GameAccess;
-    turnSeconds?: number | null;
-    budgetSeconds?: number | null;
-    incrementSeconds?: number | null;
-    minPlayers: number;
-    maxPlayers: number;
-    config: JsonObject;
-    expected: string | null;
-}
-/** A `playerLimits` case: the seats one config may be played with. */
-export interface PlayerLimitsCase {
-    kind: "playerLimits";
-    name: string;
-    config: JsonObject;
-    expected: {
-        minPlayers: number;
-        maxPlayers: number;
-    };
-}
-/** A `botSeatable` predicate case. */
-export interface BotSeatableCase {
-    kind: "botSeatable";
-    name: string;
-    gameConfig: JsonObject;
-    botConfig: JsonObject;
-    expected: boolean;
-}
-export type TwinFixtureCase = ActionCase | PlayerLimitsCase | RatingPoolCase | BotSeatableCase;
-/** Validate one fixture file's parsed JSON, or throw naming the offending
- * file, case, and field. Exported so a repo can lint its fixtures without
- * running them. */
-export declare function parseTwinFixtureFile(path: string, json: unknown): TwinFixtureFile;
-/** Run one fixture case against a rules unit, returning failure descriptions
- * (empty ⇒ the case passes). Pure; the file-reading test registrar is
- * {@link twinFixtureTests}. */
-export declare function evaluateTwinCase(rules: GameRules, kase: TwinFixtureCase): string[];
-/** Register one vitest test per fixture case found under `fixturesRoot`
- * (layout: `<root>/v<N>/*.json`). Call at the top level of a test module
- * running in a Node environment. */
-export declare function twinFixtureTests(gameModule: GameModule, fixturesRoot: string | URL): void;
-/** Structural JSON equality. Object keys with `undefined` values count as
- * absent (matching how schema libraries model optional fields); array order
- * matters. */
-export declare function deepEquals(a: Json | undefined, b: Json | undefined): boolean;