@dreamboard-games/testing 0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dreamboard-games/testing",
+  "version": "0.1.0",
+  "description": "Dreamboard authored testing helpers and reducer-native UI test runtime",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint 'src/**/*.ts'",
+    "test": "bun test"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@dreamboard/api-client": "npm:@dreamboard-games/api-client@0.1.0",
+    "@dreamboard/app-sdk": "npm:@dreamboard-games/app-sdk@0.0.41",
+    "@dreamboard/reducer-contract": "npm:@dreamboard-games/reducer-contract@7.0.0",
+    "@dreamboard/ui-sdk": "npm:@dreamboard-games/ui-sdk@0.0.41",
+    "zustand": "^5.0.4"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dreamboard-games/dreamboard.git"
+  },
+  "homepage": "http://dreamboard.games/",
+  "bugs": {
+    "url": "https://github.com/dreamboard-games/dreamboard/issues"
+  }
+}

package/src/create-expect-api.test.ts

@@ -0,0 +1,259 @@
+import { describe, expect, test } from "bun:test";
+import { createExpectApi } from "./create-expect-api.ts";
+import type { InteractionDescriptorLike } from "./definitions.ts";
+
+function makeDescriptor(
+  descriptor: Partial<InteractionDescriptorLike>,
+): InteractionDescriptorLike {
+  return {
+    interactionId: "placeThingCard",
+    available: true,
+    kind: "choose-zone",
+    surface: "board",
+    context: { to: "player-1" },
+    ...descriptor,
+  };
+}
+
+describe("createExpectApi — value matchers", () => {
+  const expectFn = createExpectApi();
+
+  test("toBe passes on strict equality and throws otherwise", () => {
+    expectFn(1).toBe(1);
+    expect(() => expectFn(1).toBe(2)).toThrow();
+  });
+
+  test("toEqual performs deep equality", () => {
+    expectFn({ a: 1, b: [2, 3] }).toEqual({ a: 1, b: [2, 3] });
+    expect(() => expectFn({ a: 1 }).toEqual({ a: 2 })).toThrow();
+  });
+
+  test("toMatchObject allows partial matches", () => {
+    expectFn({ a: 1, b: 2, nested: { c: 3 } }).toMatchObject({
+      a: 1,
+      nested: { c: 3 },
+    });
+    expect(() => expectFn({ a: 1 }).toMatchObject({ a: 2 })).toThrow();
+    expect(() => expectFn({ a: 1 }).toMatchObject({ b: 1 })).toThrow();
+  });
+
+  test("toBeDefined / toBeUndefined / toBeNull", () => {
+    expectFn(1).toBeDefined();
+    expectFn(undefined).toBeUndefined();
+    expectFn(null).toBeNull();
+    expect(() => expectFn(undefined).toBeDefined()).toThrow();
+    expect(() => expectFn(1).toBeUndefined()).toThrow();
+    expect(() => expectFn(1).toBeNull()).toThrow();
+  });
+
+  test("toContain works for arrays and strings", () => {
+    expectFn([1, 2, 3]).toContain(2);
+    expectFn("hello world").toContain("world");
+    expect(() => expectFn([1, 2, 3]).toContain(4)).toThrow();
+    expect(() => expectFn("hello").toContain("world")).toThrow();
+    expect(() => expectFn(42 as unknown).toContain(1)).toThrow();
+  });
+
+  test("toContainEqual checks deep equality in arrays", () => {
+    expectFn([{ id: "a" }, { id: "b" }]).toContainEqual({ id: "a" });
+    expect(() => expectFn([{ id: "a" }]).toContainEqual({ id: "b" })).toThrow();
+  });
+
+  test("toHaveLength checks numeric length", () => {
+    expectFn([1, 2, 3]).toHaveLength(3);
+    expectFn("abcd").toHaveLength(4);
+    expect(() => expectFn([1]).toHaveLength(2)).toThrow();
+    expect(() => expectFn(42 as unknown).toHaveLength(0)).toThrow();
+  });
+
+  test("toBeGreaterThanOrEqual checks numeric ordering", () => {
+    expectFn(5).toBeGreaterThanOrEqual(5);
+    expectFn(6).toBeGreaterThanOrEqual(5);
+    expect(() => expectFn(4).toBeGreaterThanOrEqual(5)).toThrow();
+    expect(() =>
+      expectFn("five" as unknown).toBeGreaterThanOrEqual(1),
+    ).toThrow();
+  });
+
+  test("toThrow with predicate variants", () => {
+    expectFn(() => {
+      throw new Error("boom");
+    }).toThrow();
+    expectFn(() => {
+      throw new Error("boom");
+    }).toThrow("boom");
+    expectFn(() => {
+      throw new Error("boom");
+    }).toThrow(/bo/);
+    expectFn(() => {
+      throw new Error("boom");
+    }).toThrow((error) => error.message.startsWith("boo"));
+    expect(() => expectFn(() => undefined).toThrow()).toThrow();
+    expect(() =>
+      expectFn(() => {
+        throw new Error("boom");
+      }).toThrow("baz"),
+    ).toThrow();
+  });
+});
+
+describe("createExpectApi — rejection matcher", () => {
+  const expectFn = createExpectApi();
+
+  function makeError(errorCode: string, message = "rejected"): Error {
+    const err = new Error(message);
+    (err as Error & { errorCode?: string }).errorCode = errorCode;
+    return err;
+  }
+
+  test("toRejectWith passes when errorCode matches", async () => {
+    await expectFn(async () => {
+      throw makeError("CARD_NOT_IN_HAND");
+    }).toRejectWith({ errorCode: "CARD_NOT_IN_HAND" });
+  });
+
+  test("toRejectWith fails when the function resolves", async () => {
+    let threw = false;
+    try {
+      await expectFn(async () => undefined).toRejectWith({
+        errorCode: "ANY",
+      });
+    } catch {
+      threw = true;
+    }
+    expect(threw).toBe(true);
+  });
+
+  test("toRejectWith fails when errorCode mismatches", async () => {
+    let threw = false;
+    try {
+      await expectFn(async () => {
+        throw makeError("OTHER");
+      }).toRejectWith({ errorCode: "EXPECTED" });
+    } catch {
+      threw = true;
+    }
+    expect(threw).toBe(true);
+  });
+
+  test("toRejectWith supports regex messages", async () => {
+    await expectFn(async () => {
+      throw makeError("X", "boom happened");
+    }).toRejectWith({ message: /boom/ });
+  });
+});
+
+describe("createExpectApi — descriptor matchers", () => {
+  const expectFn = createExpectApi();
+
+  test("toHaveInteraction finds a descriptor by interactionId", () => {
+    const descriptors = [
+      makeDescriptor({ interactionId: "placeThingCard" }),
+      makeDescriptor({ interactionId: "judgeCard" }),
+    ];
+    expectFn(descriptors).toHaveInteraction("placeThingCard");
+    expect(() => expectFn(descriptors).toHaveInteraction("unknown")).toThrow();
+  });
+
+  test("toHaveInteraction supports partial descriptor matching", () => {
+    const descriptors = [
+      makeDescriptor({
+        interactionId: "placeThingCard",
+        available: true,
+      }),
+    ];
+    expectFn(descriptors).toHaveInteraction("placeThingCard", {
+      available: true,
+    });
+    expect(() =>
+      expectFn(descriptors).toHaveInteraction("placeThingCard", {
+        available: false,
+      }),
+    ).toThrow();
+  });
+
+  test("not.toHaveInteraction passes when missing", () => {
+    const descriptors = [makeDescriptor({ interactionId: "placeThingCard" })];
+    expectFn(descriptors).not.toHaveInteraction("missing");
+    expect(() =>
+      expectFn(descriptors).not.toHaveInteraction("placeThingCard"),
+    ).toThrow();
+  });
+
+  test("toBeGatedBy asserts unavailable descriptor with a reason", () => {
+    const descriptor = makeDescriptor({
+      interactionId: "placeThingCard",
+      available: false,
+      unavailableReason: "NOT_YOUR_TURN",
+    });
+    expectFn(descriptor).toBeGatedBy("NOT_YOUR_TURN");
+    expect(() => expectFn(descriptor).toBeGatedBy("OTHER")).toThrow();
+  });
+
+  test("toBeGatedBy on array requires interactionId option", () => {
+    const descriptors = [
+      makeDescriptor({
+        interactionId: "placeThingCard",
+        available: false,
+        unavailableReason: "NOT_YOUR_TURN",
+      }),
+    ];
+    expectFn(descriptors).toBeGatedBy("NOT_YOUR_TURN", {
+      interactionId: "placeThingCard",
+    });
+    expect(() => expectFn(descriptors).toBeGatedBy("NOT_YOUR_TURN")).toThrow();
+  });
+
+  test("toBeActiveFor asserts descriptor targets a player and is available", () => {
+    const descriptor = makeDescriptor({
+      interactionId: "placeThingCard",
+      available: true,
+      context: { to: "player-1" },
+    });
+    expectFn(descriptor).toBeActiveFor("player-1");
+    expect(() => expectFn(descriptor).toBeActiveFor("player-2")).toThrow();
+
+    const unavailable = makeDescriptor({
+      interactionId: "placeThingCard",
+      available: false,
+      context: { to: "player-1" },
+    });
+    expect(() => expectFn(unavailable).toBeActiveFor("player-1")).toThrow();
+  });
+
+  test("toBeActiveFor on array finds by interactionId", () => {
+    const descriptors = [
+      makeDescriptor({
+        interactionId: "placeThingCard",
+        available: true,
+        context: { to: "player-1" },
+      }),
+    ];
+    expectFn(descriptors).toBeActiveFor("player-1", {
+      interactionId: "placeThingCard",
+    });
+    expect(() => expectFn(descriptors).toBeActiveFor("player-1")).toThrow();
+  });
+});
+
+describe("createExpectApi — snapshot matcher", () => {
+  test("toMatchSnapshot delegates to the configured handler", () => {
+    const calls: Array<{ name: string | undefined; actual: unknown }> = [];
+    const expectFn = createExpectApi({
+      matchSnapshot: (name, actual) => {
+        calls.push({ name, actual });
+      },
+    });
+    expectFn({ a: 1 }).toMatchSnapshot();
+    expectFn({ a: 2 }).toMatchSnapshot("seat-1.projection");
+    expect(calls).toEqual([
+      { name: undefined, actual: { a: 1 } },
+      { name: "seat-1.projection", actual: { a: 2 } },
+    ]);
+  });
+
+  test("toMatchSnapshot throws when no handler is configured", () => {
+    const expectFn = createExpectApi();
+    expect(() => expectFn({ a: 1 }).toMatchSnapshot()).toThrow();
+  });
+});

package/src/create-expect-api.ts

@@ -0,0 +1,338 @@
+import { isDeepStrictEqual } from "node:util";
+import type {
+  ExpectFn,
+  ExpectMatchers,
+  InteractionDescriptorLike,
+  RejectionExpectation,
+  SnapshotMatcherHandler,
+} from "./definitions.js";
+
+type CreateExpectApiOptions = {
+  matchSnapshot?: SnapshotMatcherHandler;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function matchPartial(
+  actual: unknown,
+  expected: unknown,
+  path: string = "value",
+): string | null {
+  if (!isRecord(expected)) {
+    return isDeepStrictEqual(actual, expected)
+      ? null
+      : `${path} does not match`;
+  }
+  if (!isRecord(actual)) {
+    return `${path} is not an object`;
+  }
+  for (const [key, expectedValue] of Object.entries(expected)) {
+    const actualValue = actual[key];
+    if (!(key in actual)) {
+      return `${path}.${key} is missing`;
+    }
+    const mismatch = matchPartial(actualValue, expectedValue, `${path}.${key}`);
+    if (mismatch) {
+      return mismatch;
+    }
+  }
+  return null;
+}
+
+function asDescriptorList(actual: unknown): InteractionDescriptorLike[] {
+  if (!Array.isArray(actual)) {
+    throw new Error("Expected interaction descriptor array.");
+  }
+  return actual as InteractionDescriptorLike[];
+}
+
+function findInteraction(
+  descriptors: readonly InteractionDescriptorLike[],
+  interactionId: string,
+): InteractionDescriptorLike | null {
+  return (
+    descriptors.find(
+      (descriptor) => descriptor.interactionId === interactionId,
+    ) ?? null
+  );
+}
+
+function assertDescriptorMatches(
+  descriptor: InteractionDescriptorLike,
+  opts: Partial<InteractionDescriptorLike> | undefined,
+): void {
+  if (!opts) {
+    return;
+  }
+  const mismatch = matchPartial(descriptor, opts, "interaction");
+  if (mismatch) {
+    throw new Error(mismatch);
+  }
+}
+
+function createSubmissionErrorMatcher(
+  actual: unknown,
+  expected: RejectionExpectation,
+): Promise<void> {
+  const resolvePromise = (): Promise<unknown> => {
+    if (typeof actual === "function") {
+      return Promise.resolve().then(() => (actual as () => unknown)());
+    }
+    return Promise.resolve(actual);
+  };
+
+  return resolvePromise()
+    .then(() => {
+      throw new Error("Expected promise to reject.");
+    })
+    .catch((error: unknown) => {
+      if (!(error instanceof Error)) {
+        throw new Error("Expected rejection to be an Error.");
+      }
+      if (
+        expected.errorCode !== undefined &&
+        (error as Error & { errorCode?: string }).errorCode !==
+          expected.errorCode
+      ) {
+        throw new Error(
+          `Expected rejection errorCode '${expected.errorCode}', received '${
+            (error as Error & { errorCode?: string }).errorCode ?? "undefined"
+          }'.`,
+        );
+      }
+      if (
+        typeof expected.message === "string" &&
+        error.message !== expected.message
+      ) {
+        throw new Error(
+          `Expected rejection message '${expected.message}', received '${error.message}'.`,
+        );
+      }
+      if (
+        expected.message instanceof RegExp &&
+        !expected.message.test(error.message)
+      ) {
+        throw new Error(
+          `Expected rejection message '${error.message}' to match ${String(expected.message)}.`,
+        );
+      }
+    });
+}
+
+function assertLength(actual: unknown, expected: number): void {
+  if (
+    actual === null ||
+    actual === undefined ||
+    typeof (actual as { length?: unknown }).length !== "number"
+  ) {
+    throw new Error("toHaveLength expects a value with a numeric length.");
+  }
+  const length = (actual as { length: number }).length;
+  if (length !== expected) {
+    throw new Error(`Expected length ${expected}, received ${length}.`);
+  }
+}
+
+function assertThrown(
+  actual: unknown,
+  predicate?: string | RegExp | ((error: Error) => boolean),
+): void {
+  if (typeof actual !== "function") {
+    throw new Error("toThrow expects a function.");
+  }
+  try {
+    (actual as () => unknown)();
+  } catch (error) {
+    if (!(error instanceof Error)) {
+      throw new Error("Thrown value is not an Error.");
+    }
+    if (predicate === undefined) {
+      return;
+    }
+    if (typeof predicate === "string" && error.message !== predicate) {
+      throw new Error(
+        `Expected thrown message '${predicate}', received '${error.message}'.`,
+      );
+    }
+    if (predicate instanceof RegExp && !predicate.test(error.message)) {
+      throw new Error(
+        `Expected thrown message '${error.message}' to match ${String(predicate)}.`,
+      );
+    }
+    if (typeof predicate === "function" && !predicate(error)) {
+      throw new Error("Thrown error did not satisfy predicate.");
+    }
+    return;
+  }
+  throw new Error("Expected function to throw.");
+}
+
+export function createExpectApi(
+  options: CreateExpectApiOptions = {},
+): ExpectFn {
+  const buildMatchers = (actual: unknown): ExpectMatchers => ({
+    toBe: (expected: unknown) => {
+      if (actual !== expected) {
+        throw new Error(
+          `Expected '${String(actual)}' to be '${String(expected)}'.`,
+        );
+      }
+    },
+    toEqual: (expected: unknown) => {
+      if (!isDeepStrictEqual(actual, expected)) {
+        throw new Error("Expected values to be deeply equal.");
+      }
+    },
+    toMatchObject: (expected: Record<string, unknown>) => {
+      const mismatch = matchPartial(actual, expected);
+      if (mismatch) {
+        throw new Error(mismatch);
+      }
+    },
+    toBeDefined: () => {
+      if (actual === undefined) {
+        throw new Error("Expected value to be defined.");
+      }
+    },
+    toBeUndefined: () => {
+      if (actual !== undefined) {
+        throw new Error(
+          `Expected value to be undefined, but received '${String(actual)}'.`,
+        );
+      }
+    },
+    toBeNull: () => {
+      if (actual !== null) {
+        throw new Error(
+          `Expected value to be null, but received '${String(actual)}'.`,
+        );
+      }
+    },
+    toContain: (expected: unknown) => {
+      if (Array.isArray(actual)) {
+        if (!actual.includes(expected)) {
+          throw new Error("Expected array to contain value.");
+        }
+        return;
+      }
+      if (typeof actual === "string") {
+        if (!actual.includes(String(expected))) {
+          throw new Error("Expected string to contain value.");
+        }
+        return;
+      }
+      throw new Error("toContain expects an array or string actual value.");
+    },
+    toContainEqual: (expected: unknown) => {
+      if (!Array.isArray(actual)) {
+        throw new Error("toContainEqual expects an array actual value.");
+      }
+      if (!actual.some((value) => isDeepStrictEqual(value, expected))) {
+        throw new Error("Expected array to contain an equal value.");
+      }
+    },
+    toHaveLength: (expected: number) => {
+      assertLength(actual, expected);
+    },
+    toBeGreaterThanOrEqual: (expected: number) => {
+      if (typeof actual !== "number") {
+        throw new Error(
+          "toBeGreaterThanOrEqual expects a number actual value.",
+        );
+      }
+      if (actual < expected) {
+        throw new Error(`Expected ${actual} to be >= ${expected}.`);
+      }
+    },
+    toThrow: (predicate) => {
+      assertThrown(actual, predicate);
+    },
+    toMatchSnapshot: (filename) => {
+      if (!options.matchSnapshot) {
+        throw new Error(
+          "Snapshot matching is not configured for this expect API.",
+        );
+      }
+      options.matchSnapshot(filename, actual);
+    },
+    toRejectWith: (expected) => createSubmissionErrorMatcher(actual, expected),
+    toHaveInteraction: (interactionId, opts) => {
+      const descriptors = asDescriptorList(actual);
+      const descriptor = findInteraction(descriptors, interactionId);
+      if (!descriptor) {
+        throw new Error(`Expected interaction '${interactionId}' to exist.`);
+      }
+      assertDescriptorMatches(descriptor, opts);
+    },
+    toBeGatedBy: (reason, opts) => {
+      const descriptor = Array.isArray(actual)
+        ? (() => {
+            if (!opts?.interactionId) {
+              throw new Error(
+                "toBeGatedBy on a descriptor array requires opts.interactionId.",
+              );
+            }
+            return findInteraction(
+              asDescriptorList(actual),
+              opts.interactionId,
+            );
+          })()
+        : (actual as InteractionDescriptorLike | null);
+      if (!descriptor) {
+        throw new Error("Expected interaction descriptor to exist.");
+      }
+      if (descriptor.available !== false) {
+        throw new Error("Expected interaction to be unavailable.");
+      }
+      if (descriptor.unavailableReason !== reason) {
+        throw new Error(
+          `Expected unavailableReason '${reason}', received '${
+            descriptor.unavailableReason ?? "undefined"
+          }'.`,
+        );
+      }
+    },
+    toBeActiveFor: (playerId, opts) => {
+      const descriptor = Array.isArray(actual)
+        ? (() => {
+            if (!opts?.interactionId) {
+              throw new Error(
+                "toBeActiveFor on a descriptor array requires opts.interactionId.",
+              );
+            }
+            return findInteraction(
+              asDescriptorList(actual),
+              opts.interactionId,
+            );
+          })()
+        : (actual as InteractionDescriptorLike | null);
+      if (!descriptor) {
+        throw new Error("Expected interaction descriptor to exist.");
+      }
+      if (descriptor.context?.to !== playerId) {
+        throw new Error(
+          `Expected interaction to target '${playerId}', received '${
+            descriptor.context?.to ?? "undefined"
+          }'.`,
+        );
+      }
+      if (descriptor.available !== true) {
+        throw new Error("Expected interaction to be available.");
+      }
+    },
+    not: {
+      toHaveInteraction: (interactionId) => {
+        const descriptors = asDescriptorList(actual);
+        if (findInteraction(descriptors, interactionId)) {
+          throw new Error(
+            `Expected interaction '${interactionId}' to be absent.`,
+          );
+        }
+      },
+    },
+  });
+
+  return (actual: unknown) => buildMatchers(actual);
+}