@moku-labs/game 0.0.2 → 0.0.3

package/dist/testing.d.mts

@@ -1,5 +1,8 @@
-import { H as PlayerStateProvider, L as Json, U as ProviderCall, W as SaveDoc, it as FakeClock } from "./types-JNc_UQBo.mjs";
-import { a as createHeadless, i as ReproResult, n as HeadlessGame, o as runRepro, r as Repro, s as stepFrames, t as HeadlessApp } from "./headless-KaSWcd0s.mjs";
+import { At as Json, Dt as Api$2, Ft as PlayerStateProvider, It as ProviderCall, Lt as SaveDoc, Ut as Api$3, Zt as FakeClock, h as Api$1, t as Api } from "./types-Cjf3ywai.mjs";
+import { _ as stepFrames, a as InputOf, d as HeadlessApp, f as HeadlessGame, g as runRepro, h as createHeadless, m as ReproResult, p as Repro, r as ControlApp } from "./types-D0uYTTC3.mjs";
+import { H as InputApi } from "./types-C0SLQsx0.mjs";
+import { b as UiApi, t as AnimApi } from "./types-KlE_GL1z.mjs";
+import { t as commands } from "./commands-BOxqlv7w.mjs";
 
 //#region src/plugins/clock/fake.d.ts
 /**
@@ -70,4 +73,303 @@ declare function memory(fixture?: {
  */
 declare function saveOf(player: Json, seed?: number): SaveDoc;
 //#endregion
-export { type HeadlessApp, type HeadlessGame, type Repro, type ReproResult, createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };
+//#region src/visual/types.d.ts
+/** The base commands of the `/control` door, keyed by their short names. */
+type Catalogue = typeof commands;
+/**
+ * The commands a step may name: the catalogue of `/control` minus `bookmark` (it only reads),
+ * `capture` (the runner captures by itself) and `debug` (debug drawing would enter a baseline). A
+ * command the catalogue gains is a step with no change to the runner.
+ *
+ * @example
+ * ```ts
+ * const name: StepCommand = "tap"; // also "answer", "walk", "step", "reducedMotion", ...
+ * ```
+ */
+type StepCommand = Exclude<keyof Catalogue, "bookmark" | "capture" | "debug">;
+/**
+ * Where a visual test starts: what `game.restore` loads, a repro without its route. The player
+ * is required; the session, the rng and the checkpoint are optional, as in a repro.
+ *
+ * @example
+ * ```ts
+ * // A save with a plank ready for the first order, entered at Home.
+ * const start: VisualStart = { player: { coins: 40, orders: [] }, checkpoint: "home" };
+ * ```
+ */
+type VisualStart = Omit<Repro, "route">;
+/**
+ * One step of a visual test: a `/control` command by its short name with that command's input,
+ * typed from the catalogue, or a checkpoint by its name.
+ *
+ * @example
+ * ```ts
+ * // Tap Play, answer the order on the board, then compare the screen with its baseline.
+ * const steps: VisualStep[] = [
+ *   { tap: { key: "play" } },
+ *   { answer: { intent: "deliver", payload: { orderId: "o1" } } },
+ *   { checkpoint: "open" }
+ * ];
+ * ```
+ */
+type VisualStep = {
+  checkpoint: string;
+} | { [K in StepCommand]: { [P in K]: InputOf<Catalogue[K]["input"]> } }[StepCommand];
+/**
+ * A visual test as `defineVisualTest` answers it: its name, where it starts and its steps.
+ * Frozen data; nothing runs at definition.
+ *
+ * @example
+ * ```ts
+ * const test: VisualTest = defineVisualTest("reward-popup", {
+ *   start: { player: { coins: 40 }, checkpoint: "home" },
+ *   steps: [{ tap: { key: "play" } }, { checkpoint: "board" }]
+ * });
+ * test.name; // "reward-popup"
+ * Object.isFrozen(test.steps); // true
+ * ```
+ */
+type VisualTest = {
+  readonly name: string;
+  readonly start: Readonly<VisualStart>;
+  readonly steps: readonly VisualStep[];
+};
+/**
+ * What the runner needs of an app: the control app, the plugins the base commands act on and
+ * the plugins the readers read. Every app composed with the screen set fits.
+ *
+ * @example
+ * ```ts
+ * const app: VisualApp = createApp({ plugins: [...screen, boardFeature], pluginConfigs });
+ * ```
+ */
+type VisualApp = ControlApp & {
+  readonly anim: AnimApi;
+  readonly ui: UiApi;
+  readonly renderer: Api;
+  readonly world: Api$1;
+  readonly model: Api$2;
+  readonly input: InputApi;
+  readonly lifecycle: Api$3;
+};
+/**
+ * The dev page the browser leg opens: its URL, the viewport width in CSS px (390 by default), the
+ * device scale (2 by default) and which Chrome to launch. The page height follows the inert frame
+ * of the renderer: 520 for a 390 wide portrait game at the default 4:3. Without `browser` the leg
+ * launches Playwright's own Chromium, and the system Chrome when that one is not installed.
+ *
+ * @example
+ * ```ts
+ * // The fixture's dev server, a 390 px wide phone at 2x, the system Chrome.
+ * const page: VisualPage = { url: "http://localhost:3000/", browser: { channel: "chrome" } };
+ * ```
+ */
+type VisualPage = {
+  url: string;
+  width?: number;
+  deviceScaleFactor?: number;
+  browser?: {
+    channel?: string;
+    executablePath?: string;
+  };
+};
+/**
+ * How the runner builds a game: a fresh app per test, not started, with the screen set
+ * composed; the renderer stays inert in Bun. `page` is the dev page of the pixel leg.
+ *
+ * @example
+ * ```ts
+ * // tests/visual/run.ts of a game.
+ * const setup: VisualSetup = { app: () => createScreenGame().app, page: { url: "http://localhost:3000/" } };
+ * ```
+ */
+type VisualSetup = {
+  app: () => VisualApp;
+  page?: VisualPage;
+};
+/**
+ * How far a pixel may differ: `threshold` is the largest channel delta that still counts as the
+ * same pixel, `ratio` the share of differing pixels a checkpoint tolerates.
+ *
+ * @example
+ * ```ts
+ * const tolerance: VisualTolerance = { ratio: 0.001, threshold: 24 }; // the defaults
+ * ```
+ */
+type VisualTolerance = {
+  ratio: number;
+  threshold: number;
+};
+/**
+ * The options of a run. Each one left out comes from the command line (`argv`), then from its
+ * default: `dir` `"tests/visual"`, `update` false, `pixels` true with a `page` on a Mac,
+ * `settleFrames` 600, `tolerance` `{ ratio: 0.001, threshold: 24 }`, `argv`
+ * `process.argv.slice(2)`. An option given here wins over a flag.
+ *
+ * @example
+ * ```ts
+ * // The same as `bun tests/visual/run.ts --only reward-popup --no-pixels`.
+ * const options: VisualOptions = { only: ["reward-popup"], pixels: false };
+ * ```
+ */
+type VisualOptions = {
+  dir?: string;
+  update?: boolean;
+  pixels?: boolean;
+  only?: readonly string[];
+  settleFrames?: number;
+  tolerance?: VisualTolerance;
+  argv?: readonly string[];
+};
+/**
+ * What a comparison with a baseline file found: the same content, a different one, or no
+ * baseline (or `--update`), so the file was written.
+ *
+ * @example
+ * ```ts
+ * const outcome: Outcome = "written"; // the first run of a new checkpoint
+ * ```
+ */
+type Outcome = "same" | "different" | "written";
+/**
+ * The outcome of one checkpoint. `first` is the JSON path of the first difference, the state's
+ * before the describe's. `pixels` is `"skipped"` when the pixel leg did not run; `pixelRatio`
+ * and `verdict` come with a pixel difference.
+ *
+ * @example
+ * ```ts
+ * // The player's coins differ from the baseline; the layout is the same.
+ * const result: CheckpointResult = {
+ *   name: "claimed", state: "different", describe: "same", pixels: "skipped", first: "player.coins"
+ * };
+ * ```
+ */
+type CheckpointResult = {
+  name: string;
+  state: Outcome;
+  describe: Outcome;
+  pixels: Outcome | "skipped";
+  pixelRatio?: number;
+  first?: string;
+  verdict?: "rendering" | "behaviour";
+};
+/**
+ * The outcome of one visual test: every checkpoint it reached, and the error that ended it early.
+ *
+ * @example
+ * ```ts
+ * const result: VisualTestResult = {
+ *   name: "reward-popup",
+ *   checkpoints: [{ name: "open", state: "same", describe: "same", pixels: "skipped" }]
+ * };
+ * ```
+ */
+type VisualTestResult = {
+  name: string;
+  checkpoints: readonly CheckpointResult[];
+  error?: string;
+};
+/**
+ * What `runVisualTests` answers: `ok` is true when no test failed and no outcome is
+ * `"different"`.
+ *
+ * @example
+ * ```ts
+ * const report: VisualReport = await runVisualTests(setup, [rewardPopup], { argv: [] });
+ * process.exitCode = report.ok ? 0 : 1;
+ * ```
+ */
+type VisualReport = {
+  ok: boolean;
+  tests: readonly VisualTestResult[];
+};
+/** What the command line asked for: the flags it carried, nothing else. */
+type VisualFlags = {
+  dir?: string;
+  update?: boolean;
+  pixels?: boolean;
+  only?: readonly string[];
+};
+//#endregion
+//#region src/visual/define.d.ts
+/**
+ * Defines a visual test: where it starts, what `game.restore` loads, and its steps. A step is a
+ * `/control` command by its short name with that command's input, or `{ checkpoint: name }`,
+ * where the runner saves `state.json` and `describe.json` next to the test. `walk` runs fast: a
+ * popup its last node opens never mounts, so the step before a checkpoint that shows a node's
+ * result is `answer` or `tap`. The answer is a frozen copy; nothing runs here.
+ *
+ * @param name - The test name, also its folder: lowercase letters, digits and dashes.
+ * @param test - Where it starts and its steps.
+ * @param test.start - The player, and optionally the session, the rng and the checkpoint.
+ * @param test.steps - The commands and the checkpoints, in order.
+ * @returns The test, frozen.
+ * @throws {Error} When the name or a checkpoint name is not a file name, a checkpoint name is
+ *   used twice, or a step is not one step command.
+ * @example
+ * ```ts
+ * // tests/visual/reward-popup.visual.ts: Play, deliver the first order, claim the reward.
+ * export const rewardPopup = defineVisualTest("reward-popup", {
+ *   start: { player: fixtures.ready, checkpoint: "home" },
+ *   steps: [{ tap: { key: "play" } }, { answer: { intent: "deliver", payload: { orderId: "o1" } } },
+ *     { checkpoint: "open" }, { tap: { key: "claim" } }, { checkpoint: "claimed" }]
+ * });
+ * ```
+ */
+declare function defineVisualTest(name: string, test: {
+  start: VisualStart;
+  steps: readonly VisualStep[];
+}): VisualTest;
+//#endregion
+//#region src/visual/run.d.ts
+/**
+ * Reads the flags of the visual tests from a command line: `--update`, `--no-pixels`,
+ * `--only <name>` (repeatable) and `--dir <path>`. An argument it does not know is left to the
+ * script that got it, so a test runner's own arguments pass through.
+ *
+ * @param argv - The arguments after the script name.
+ * @returns The flags that were given, and nothing else.
+ * @throws {Error} When `--only` or `--dir` has no value.
+ * @example
+ * ```ts
+ * // `bun tests/visual/run.ts --update --only reward-popup`
+ * parseVisualArgv(["--update", "--only", "reward-popup"]); // { update: true, only: ["reward-popup"] }
+ * parseVisualArgv(["--no-pixels", "--dir", "shots"]); // { pixels: false, dir: "shots" }
+ * ```
+ */
+declare function parseVisualArgv(argv: readonly string[]): VisualFlags;
+/**
+ * Runs visual tests: the headless leg over every selected test, then the browser leg over the
+ * same tests when `pixels` is on (by default only with a `page` on a Mac). A checkpoint saves
+ * `state.json` and `describe.json` in `<dir>/<test>/<checkpoint>/`, and the browser leg
+ * `screen.webp`, lossless: a missing file is written, `--update` rewrites every file of the tests
+ * run, a JSON file is compared exactly. The browser leg opens the dev page in Chrome with WebGPU
+ * through `playwright-core`, pauses its game, plays each test there on stepped frames of 1000/60
+ * ms, so two runs see the same game time, checks the page's state against `state.json` and
+ * compares the picture in the page: a pixel differs above `tolerance.threshold`, and the screen
+ * differs when more than `tolerance.ratio` of its pixels do; `screen.actual.webp` and
+ * `screen.diff.webp` are written beside the baseline then. A pixel difference over the same state
+ * and describe is a rendering regression (`verdict: "rendering"`). One line per checkpoint goes
+ * to the branded console; the script sets the exit code from `ok`.
+ *
+ * @param setup - How to build a game: a fresh, unstarted app per test, and the dev page.
+ * @param tests - Every visual test of the game.
+ * @param options - Overrides of the flags of `argv` and of the defaults.
+ * @returns The report: `ok` when no test failed and nothing is `"different"`.
+ * @throws {Error} When a test is not well formed, two tests share a name, `only` names no test,
+ *   a flag misses its value, or the browser leg fails as a whole: no `page`, no
+ *   `playwright-core`, no Chrome, or a page that does not open, expose `game` and `doors`, start,
+ *   draw with WebGPU or stop loading.
+ * @example
+ * ```ts
+ * // tests/visual/run.ts of a game, `bun tests/visual/run.ts --update` on a Mac
+ * const report = await runVisualTests(
+ *   { app: () => createScreenGame().app, page: { url: "http://localhost:3000/" } },
+ *   [rewardPopup]
+ * );
+ * report.tests[0]?.checkpoints[0]; // { name: "open", state: "written", describe: "written", pixels: "written" }
+ * ```
+ */
+declare function runVisualTests(setup: VisualSetup, tests: readonly VisualTest[], options?: VisualOptions): Promise<VisualReport>;
+//#endregion
+export { type CheckpointResult, type HeadlessApp, type HeadlessGame, type Repro, type ReproResult, type VisualApp, type VisualOptions, type VisualPage, type VisualReport, type VisualSetup, type VisualStart, type VisualStep, type VisualTest, type VisualTestResult, type VisualTolerance, createHeadless, defineVisualTest, fakeClock, memory, parseVisualArgv, runRepro, runVisualTests, saveOf, stepFrames };