@dreamboard-games/testing 0.1.0

package/src/create-test-runtime.ts

@@ -0,0 +1,516 @@
+import type {
+  HostPlayerGameplayView,
+  HostSessionContext,
+  HostSessionSnapshot,
+  SeatAssignment,
+} from "@dreamboard/api-client";
+import type { ReducerBundleContract } from "@dreamboard/reducer-contract/bundle";
+import type * as Wire from "@dreamboard/reducer-contract/wire";
+import type { PluginStateSnapshot } from "@dreamboard/ui-sdk/reducer";
+import type {
+  PluginSessionState,
+  RuntimeAPI,
+  SubmissionError,
+  ValidationResult,
+} from "@dreamboard/ui-sdk";
+import {
+  createUnifiedSessionStore,
+  type GameplayViewport,
+  type SessionContext,
+  type SSEManagerLike,
+} from "@dreamboard/ui-host-runtime/runtime";
+
+type ReducerStaticProjection = Wire.BoardStaticProjection;
+type ReducerBundleLike = Pick<
+  ReducerBundleContract,
+  "projectSeatsDynamic" | "projectStatic" | "validateInput" | "dispatch"
+>;
+
+type BaseStateArtifact = {
+  snapshot: Wire.ReducerSessionState;
+  fingerprint: {
+    players: number;
+  };
+};
+
+export type CreateTestRuntimeOptions = {
+  baseId: string;
+  baseStates: Record<string, BaseStateArtifact>;
+  bundle: ReducerBundleLike;
+  phase?: string;
+  playerIds?: readonly string[];
+  sessionId?: string;
+  userId?: string | null;
+  gameId?: string;
+  displayNameByPlayerId?: Record<string, string>;
+};
+
+export type CreatedTestRuntime = {
+  runtime: RuntimeAPI & {
+    getSnapshot(): PluginStateSnapshot;
+    subscribeToState(
+      listener: (state: PluginStateSnapshot) => void,
+    ): () => void;
+    _subscribeToSessionState(
+      listener: (state: PluginSessionState) => void,
+    ): () => void;
+  };
+  getSnapshot(): PluginStateSnapshot;
+  players(): readonly string[];
+  seat(index: number): string;
+  submit(
+    playerId: string,
+    interactionId: string,
+    params?: unknown,
+  ): Promise<void>;
+  validate(
+    playerId: string,
+    interactionId: string,
+    params?: unknown,
+  ): Promise<ValidationResult>;
+  setControllingPlayer(playerId: string): void;
+};
+
+function cloneState<T>(value: T): T {
+  return structuredClone(value);
+}
+
+function createSubmissionError(
+  errorCode: string | undefined,
+  message: string | undefined,
+): SubmissionError {
+  const error = new Error(message ?? "Interaction rejected") as SubmissionError;
+  error.name = "SubmissionError";
+  error.errorCode = errorCode;
+  return error;
+}
+
+function readFlowState(state: Wire.ReducerSessionState): {
+  currentPhase: string | null;
+  activePlayers: string[];
+} {
+  const flow = ((
+    state.domain as
+      | { flow?: { currentPhase?: string; activePlayers?: string[] } }
+      | undefined
+  )?.flow ?? {}) as {
+    currentPhase?: string;
+    activePlayers?: string[];
+  };
+  return {
+    currentPhase: flow.currentPhase ?? null,
+    activePlayers: Array.isArray(flow.activePlayers) ? flow.activePlayers : [],
+  };
+}
+
+function buildSeatAssignments(
+  playerIds: readonly string[],
+  userId: string | null,
+  displayNameByPlayerId: Record<string, string> | undefined,
+): SeatAssignment[] {
+  const actor =
+    userId != null ? { kind: "AUTH_USER" as const, id: userId } : undefined;
+  return playerIds.map((playerId) => ({
+    playerId,
+    controllerActor: actor,
+    displayName: displayNameByPlayerId?.[playerId] ?? playerId,
+  }));
+}
+
+function resolvePlayerIds(options: {
+  baseState: BaseStateArtifact;
+  explicitPlayerIds?: readonly string[];
+}): string[] {
+  if (options.explicitPlayerIds && options.explicitPlayerIds.length > 0) {
+    return [...options.explicitPlayerIds];
+  }
+  return Array.from(
+    { length: options.baseState.fingerprint.players },
+    (_, index) => `player-${index + 1}`,
+  );
+}
+
+// Stub SSE manager for the in-memory store. `createTestRuntime` never
+// connects to a live backend; updates are delivered through
+// `applyGameplaySnapshotLocal(...)` instead.
+function createStubSseManager(): SSEManagerLike {
+  return {
+    connect: () => undefined,
+    disconnect: () => undefined,
+    on: () => () => undefined,
+    onAnyMessage: () => () => undefined,
+  };
+}
+
+function buildGameplaySnapshot(options: {
+  state: Wire.ReducerSessionState;
+  bundle: ReducerBundleLike;
+  staticProjection: ReducerStaticProjection | null;
+  playerId: string;
+  version: number;
+  expectedPhase: string | undefined;
+  baseId: string;
+}): HostPlayerGameplayView {
+  const projection = options.bundle.projectSeatsDynamic({
+    state: options.state,
+    playerIds: [options.playerId],
+  });
+
+  const flow = readFlowState(options.state);
+  if (options.expectedPhase && flow.currentPhase !== options.expectedPhase) {
+    throw new Error(
+      `Expected base '${options.baseId}' to be in phase '${options.expectedPhase}', received '${
+        flow.currentPhase ?? "null"
+      }'.`,
+    );
+  }
+
+  const seats = projection.seats ?? {};
+  const seat = seats[options.playerId];
+
+  return {
+    version: options.version,
+    actionSetVersion: `${options.version}:test`,
+    playerId: options.playerId,
+    activePlayers: flow.activePlayers,
+    currentPhase: flow.currentPhase ?? "",
+    currentStage: projection.currentStage ?? "",
+    stageSeats: projection.stageSeats ?? [],
+    view: JSON.stringify(seat?.view ?? null),
+    availableInteractions:
+      (seat?.availableInteractions as HostPlayerGameplayView["availableInteractions"]) ??
+      [],
+    zones: (seat?.zones as HostPlayerGameplayView["zones"]) ?? {},
+    boardStatic: options.staticProjection
+      ? JSON.stringify(options.staticProjection.view)
+      : undefined,
+    boardStaticHash: options.staticProjection?.hash,
+  };
+}
+
+function createHostContext(options: {
+  sessionId: string;
+  userId: string;
+  gameId: string;
+  phase: HostSessionContext["phase"];
+  hostActor: { kind: "AUTH_USER"; id: string };
+  switchablePlayerIds: string[];
+}): HostSessionContext {
+  return {
+    sessionId: options.sessionId,
+    shortCode: options.sessionId,
+    phase: options.phase,
+    status: "active",
+    hostActor: options.hostActor,
+    gameSource: {
+      kind: "USER_COMPILED",
+      ownerUserId: options.userId,
+      gameId: options.gameId,
+      compiledResultId: "00000000-0000-0000-0000-000000000000",
+    },
+    switchablePlayerIds: options.switchablePlayerIds,
+    history: {
+      entries: [],
+      currentIndex: -1,
+      canGoBack: false,
+      canGoForward: false,
+    },
+  };
+}
+
+function createRuntimeSessionContext(options: {
+  sessionId: string;
+  userId: string;
+  gameId: string;
+  hostActor: { kind: "AUTH_USER"; id: string };
+  switchablePlayerIds: string[];
+  seats: SeatAssignment[];
+  canStart: boolean;
+}): SessionContext {
+  return {
+    identity: {
+      sessionId: options.sessionId,
+      shortCode: options.sessionId,
+      gameId: options.gameId,
+    },
+    userId: options.userId,
+    seats: options.seats,
+    canStart: options.canStart,
+    hostActor: options.hostActor,
+    switchablePlayerIds: options.switchablePlayerIds,
+    history: {
+      entries: [],
+      currentIndex: -1,
+      canGoBack: false,
+      canGoForward: false,
+    },
+  };
+}
+
+function gameplayViewportFromSnapshot(
+  snapshot: HostPlayerGameplayView,
+): GameplayViewport {
+  return {
+    version: snapshot.version,
+    actionSetVersion: snapshot.actionSetVersion,
+    activePlayers: snapshot.activePlayers,
+    currentPhase: snapshot.currentPhase,
+    currentStage: snapshot.currentStage,
+    stageSeats: snapshot.stageSeats,
+    simultaneousPhase: snapshot.simultaneousPhase ?? null,
+    view: JSON.parse(snapshot.view) as GameplayViewport["view"],
+    availableInteractions: snapshot.availableInteractions,
+    zones: snapshot.zones,
+    boardStatic: snapshot.boardStatic
+      ? (JSON.parse(snapshot.boardStatic) as Record<string, unknown>)
+      : null,
+    boardStaticHash: snapshot.boardStaticHash ?? null,
+  };
+}
+
+// Reuses `packages/ui-host-runtime`'s unified session store so the
+// `getPluginSnapshot()` projection and `applyGameplaySnapshotLocal(...)`
+// reducer running inside workspace tests are the same code paths
+// running inside the host app. Prevents snapshot-shape drift between
+// host plugin UI and authored UI tests.
+export function createTestRuntime(
+  options: CreateTestRuntimeOptions,
+): CreatedTestRuntime {
+  const baseState = options.baseStates[options.baseId];
+  if (!baseState) {
+    throw new Error(`Unknown test base '${options.baseId}'.`);
+  }
+
+  let currentState = cloneState(baseState.snapshot);
+  const playerIds = resolvePlayerIds({
+    baseState,
+    explicitPlayerIds: options.playerIds,
+  });
+  const userId = options.userId ?? "test-user";
+  const sessionId = options.sessionId ?? "test-session";
+  const gameId = options.gameId ?? "test-game";
+  const seats = buildSeatAssignments(
+    playerIds,
+    userId,
+    options.displayNameByPlayerId,
+  );
+  const storeApi = createUnifiedSessionStore({
+    createSseManager: createStubSseManager,
+    // Test runtimes keep `userId` present so the unified store derives
+    // controllable player ids from seat assignments whenever the
+    // incoming snapshot omits `controllablePlayerIds`.
+    fallbackToAllSeatsWhenUserIdMissing: false,
+  });
+
+  const hostActor = { kind: "AUTH_USER" as const, id: userId };
+  const lobbySnapshot: HostSessionSnapshot = {
+    type: "lobby",
+    context: createHostContext({
+      sessionId,
+      userId,
+      gameId,
+      phase: "lobby",
+      hostActor,
+      switchablePlayerIds: playerIds,
+    }),
+    lobby: {
+      seats,
+      canStart: true,
+      hostActor,
+    },
+  };
+  const setSessionState = (input: {
+    selectedPlayerId: string;
+    gameplay?: HostPlayerGameplayView;
+  }): void => {
+    const context = createRuntimeSessionContext({
+      sessionId,
+      userId,
+      gameId,
+      hostActor,
+      switchablePlayerIds: playerIds,
+      seats,
+      canStart: true,
+    });
+    storeApi.setState((state) => ({
+      ...state,
+      session: input.gameplay
+        ? {
+            type: "gameplay",
+            context,
+            perspective: { playerId: input.selectedPlayerId },
+            gameplay: gameplayViewportFromSnapshot(input.gameplay),
+          }
+        : {
+            type: "lobby",
+            context,
+            preferredPlayerId: input.selectedPlayerId || null,
+          },
+      connection: { ...state.connection, error: null },
+      activity: {
+        ...state.activity,
+        syncId: state.activity.syncId + 1,
+        lastSyncTimestamp: Date.now(),
+      },
+    }));
+  };
+
+  setSessionState({
+    selectedPlayerId: playerIds[0] ?? "",
+  });
+
+  let version = 0;
+  let currentPlayerId = playerIds[0] ?? "";
+  const staticProjection = options.bundle.projectStatic?.() ?? null;
+
+  const applyCurrentState = (): void => {
+    version += 1;
+    const snapshot = buildGameplaySnapshot({
+      state: currentState,
+      bundle: options.bundle,
+      staticProjection,
+      playerId: currentPlayerId,
+      version,
+      expectedPhase: version === 1 ? options.phase : undefined,
+      baseId: options.baseId,
+    });
+    setSessionState({
+      selectedPlayerId: currentPlayerId,
+      gameplay: snapshot,
+    });
+  };
+
+  applyCurrentState();
+
+  const stateListeners = new Set<(state: PluginStateSnapshot) => void>();
+  const sessionListeners = new Set<(state: PluginSessionState) => void>();
+
+  let lastPluginSnapshot = storeApi.getState().getPluginSnapshot();
+  let lastSessionState: PluginSessionState = {
+    ...lastPluginSnapshot.session,
+    status: "ready",
+  };
+
+  storeApi.subscribe((state, previous) => {
+    const nextPluginSnapshot = state.getPluginSnapshot();
+    if (nextPluginSnapshot !== lastPluginSnapshot) {
+      lastPluginSnapshot = nextPluginSnapshot;
+      for (const listener of stateListeners) {
+        listener(nextPluginSnapshot);
+      }
+    }
+    const previousSession = previous.getPluginSnapshot().session;
+    const nextSession = nextPluginSnapshot.session;
+    const controllingPlayerChanged =
+      nextSession.controllingPlayerId !== previousSession.controllingPlayerId;
+    const controllableIdsChanged =
+      nextSession.controllablePlayerIds.join("\0") !==
+      previousSession.controllablePlayerIds.join("\0");
+    if (controllingPlayerChanged || controllableIdsChanged) {
+      lastSessionState = {
+        ...nextPluginSnapshot.session,
+        status: "ready",
+      };
+      for (const listener of sessionListeners) {
+        listener(lastSessionState);
+      }
+    }
+  });
+
+  const validate = async (
+    playerId: string,
+    interactionId: string,
+    params: unknown = {},
+  ): Promise<ValidationResult> => {
+    const result = await options.bundle.validateInput({
+      state: currentState,
+      input: {
+        kind: "interaction",
+        playerId,
+        interactionId,
+        params: params as Wire.JsonValue,
+      },
+    });
+    return {
+      valid: result.valid,
+      errorCode: result.errorCode,
+      message: result.message,
+    };
+  };
+
+  const submit = async (
+    playerId: string,
+    interactionId: string,
+    params: unknown = {},
+  ): Promise<void> => {
+    const validation = await validate(playerId, interactionId, params);
+    if (!validation.valid) {
+      throw createSubmissionError(validation.errorCode, validation.message);
+    }
+    const result = await options.bundle.dispatch({
+      state: currentState,
+      input: {
+        kind: "interaction",
+        playerId,
+        interactionId,
+        params: params as Wire.JsonValue,
+      },
+    });
+    if (result.kind === "reject") {
+      throw createSubmissionError(result.errorCode, result.message);
+    }
+    currentState = cloneState(result.state);
+    applyCurrentState();
+  };
+
+  const setControllingPlayer = (playerId: string): void => {
+    if (!playerIds.includes(playerId)) {
+      throw new Error(`Unknown controlling player '${playerId}'.`);
+    }
+    currentPlayerId = playerId;
+    storeApi.getState().selectPlayer(playerId);
+    applyCurrentState();
+  };
+
+  const runtime = {
+    validateInteraction: validate,
+    submitInteraction: submit,
+    getSessionState: (): PluginSessionState => ({ ...lastSessionState }),
+    disconnect: () => undefined,
+    switchPlayer: (playerId: string) => {
+      setControllingPlayer(playerId);
+    },
+    getSnapshot: (): PluginStateSnapshot => lastPluginSnapshot,
+    subscribeToState: (listener: (state: PluginStateSnapshot) => void) => {
+      stateListeners.add(listener);
+      return () => {
+        stateListeners.delete(listener);
+      };
+    },
+    _subscribeToSessionState: (
+      listener: (state: PluginSessionState) => void,
+    ) => {
+      sessionListeners.add(listener);
+      return () => {
+        sessionListeners.delete(listener);
+      };
+    },
+  };
+
+  return {
+    runtime,
+    getSnapshot: () => lastPluginSnapshot,
+    players: () => [...playerIds],
+    seat: (index: number) => {
+      if (!Number.isInteger(index) || index < 0 || index >= playerIds.length) {
+        throw new Error(
+          `seat(${index}) is out of range; base '${options.baseId}' has ${playerIds.length} player(s).`,
+        );
+      }
+      return playerIds[index]!;
+    },
+    submit,
+    validate,
+    setControllingPlayer,
+  };
+}

package/src/definitions.ts

@@ -0,0 +1,114 @@
+export type TestRunner = "reducer" | "embedded" | "browser";
+
+export type InteractionDescriptorLike = {
+  interactionId?: string;
+  surface?: string;
+  kind?: string;
+  available?: boolean;
+  unavailableReason?: string;
+  context?: {
+    to?: string;
+  };
+} & Record<string, unknown>;
+
+export type SnapshotMatcherHandler = (
+  name: string | undefined,
+  actual: unknown,
+) => void;
+
+export type RejectionExpectation = {
+  errorCode?: string;
+  message?: string | RegExp;
+};
+
+export type ExpectMatchers = {
+  toBe: (expected: unknown) => void;
+  toEqual: (expected: unknown) => void;
+  toMatchObject: (expected: Record<string, unknown>) => void;
+  toBeDefined: () => void;
+  toBeUndefined: () => void;
+  toBeNull: () => void;
+  toContain: (expected: unknown) => void;
+  toContainEqual: (expected: unknown) => void;
+  toHaveLength: (expected: number) => void;
+  toBeGreaterThanOrEqual: (expected: number) => void;
+  toThrow: (predicate?: string | RegExp | ((error: Error) => boolean)) => void;
+  toMatchSnapshot: (filename?: string) => void;
+  toRejectWith: (expected: RejectionExpectation) => Promise<void>;
+  toHaveInteraction: (
+    interactionId: string,
+    opts?: Partial<InteractionDescriptorLike>,
+  ) => void;
+  toBeGatedBy: (reason: string, opts?: { interactionId?: string }) => void;
+  toBeActiveFor: (playerId: string, opts?: { interactionId?: string }) => void;
+  not: {
+    toHaveInteraction: (interactionId: string) => void;
+  };
+};
+
+export type ExpectFn = (actual: unknown) => ExpectMatchers;
+
+export interface BaseContext<PlayerId extends string = string> {
+  game: {
+    start(): Promise<void>;
+    submit(
+      playerId: PlayerId,
+      interactionId: string,
+      params?: unknown,
+    ): Promise<void>;
+  };
+  players(): readonly PlayerId[];
+  seat(index: number): PlayerId;
+}
+
+export interface SharedScenarioContext<
+  PlayerId extends string = string,
+  StateName extends string = string,
+  View = unknown,
+  Descriptor extends InteractionDescriptorLike = InteractionDescriptorLike,
+> extends BaseContext<PlayerId> {
+  state(): StateName;
+  view(playerId: PlayerId): View;
+  interactions(playerId: PlayerId): readonly Descriptor[];
+  expect: ExpectFn;
+}
+
+export interface BaseDefinition {
+  id: string;
+  seed?: number;
+  players?: number;
+  setupProfileId?: string | null;
+  extends?: string;
+  setup: (ctx: BaseContext) => void | Promise<void>;
+}
+
+export interface ScenarioDefinition<
+  Runners extends readonly TestRunner[] = readonly ["reducer"],
+  PhaseName extends string = string,
+  StageName extends string = string,
+> {
+  id: string;
+  description?: string;
+  from: string;
+  runners?: Runners;
+  phase?: PhaseName;
+  stage?: StageName;
+  when: (ctx: SharedScenarioContext) => void | Promise<void>;
+  then: (ctx: SharedScenarioContext) => void | Promise<void>;
+}
+
+export function defineBase<const Definition extends BaseDefinition>(
+  definition: Definition,
+): Definition {
+  return definition;
+}
+
+export function defineScenario<
+  const Runners extends readonly TestRunner[] = readonly ["reducer"],
+  const PhaseName extends string = string,
+  const StageName extends string = string,
+>(
+  definition: ScenarioDefinition<Runners, PhaseName, StageName>,
+): ScenarioDefinition<Runners, PhaseName, StageName> {
+  return definition;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./definitions.js";
+export * from "./create-expect-api.js";
+export * from "./create-test-runtime.js";