@moku-labs/game 0.7.0 → 0.8.0

package/dist/visual.d.mts

@@ -0,0 +1,331 @@
+import { F as Api, Z as Api$1 } from "./types-ERb2Y9U5.mjs";
+import { k as Api$3, m as Api$2 } from "./types-BWzCSRM2.mjs";
+import { r as Repro } from "./headless-q98SwADR.mjs";
+import { a as InputOf, r as ControlApp } from "./types-CDSKa0vl.mjs";
+import { H as InputApi } from "./types-DgdMLZnV.mjs";
+import { b as AnimApi, v as UiApi } from "./types-DlgsfOmW.mjs";
+import { t as commands } from "./commands-C1kIfOG5.mjs";
+
+//#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, its steps, and
+ * `webgl`, true when it also runs in the WebGL leg. 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"
+ * test.webgl; // false
+ * Object.isFrozen(test.steps); // true
+ * ```
+ */
+type VisualTest = {
+  readonly name: string;
+  readonly start: Readonly<VisualStart>;
+  readonly steps: readonly VisualStep[];
+  readonly webgl: boolean;
+};
+/**
+ * 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$2;
+  readonly world: Api$3;
+  readonly model: Api;
+  readonly input: InputApi;
+  readonly lifecycle: Api$1;
+};
+/**
+ * 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 backend the browser leg draws with: `"webgpu"`, or `"webgl"` for the WebGL leg.
+ *
+ * @example
+ * ```ts
+ * const renderer: VisualRenderer = "webgl"; // what --webgl asks for
+ * ```
+ */
+type VisualRenderer = "webgpu" | "webgl";
+/**
+ * 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,
+ * `renderer` `"webgpu"`, `settleFrames` 600, `tolerance` `{ ratio: 0.001, threshold: 24 }`,
+ * `argv` `process.argv.slice(2)`. An option given here wins over a flag. `renderer: "webgl"`
+ * runs only the tests with `webgl: true`, on the page with `?renderer=webgl`, and compares their
+ * pictures with `screen.webgl.webp`.
+ *
+ * @example
+ * ```ts
+ * // The same as `bun tests/visual/run.ts --only reward-popup --no-pixels`.
+ * const options: VisualOptions = { only: ["reward-popup"], pixels: false };
+ * // The same as `bun tests/visual/run.ts --webgl`.
+ * const webgl: VisualOptions = { renderer: "webgl" };
+ * ```
+ */
+type VisualOptions = {
+  dir?: string;
+  update?: boolean;
+  pixels?: boolean;
+  renderer?: VisualRenderer;
+  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;
+  renderer?: VisualRenderer;
+  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`. With `webgl: true` the test also runs in the WebGL leg
+ * (`--webgl`), whose pictures go to `screen.webgl.webp`: set it on a screen with a custom filter.
+ * 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, its steps and its WebGL leg.
+ * @param test.start - The player, and optionally the session, the rng and the checkpoint.
+ * @param test.steps - The commands and the checkpoints, in order.
+ * @param test.webgl - True to run the test in the WebGL leg too; false by default.
+ * @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/home.visual.ts: Home with the glowing Play plank, in both legs.
+ * const home = defineVisualTest("home", { start: atHome, steps: [{ checkpoint: "rest" }], webgl: true });
+ * home.webgl; // true
+ * ```
+ */
+declare function defineVisualTest(name: string, test: {
+  start: VisualStart;
+  steps: readonly VisualStep[];
+  webgl?: boolean;
+}): VisualTest;
+//#endregion
+//#region src/visual/run.d.ts
+/**
+ * Reads the flags of the visual tests from a command line: `--update`, `--no-pixels`, `--webgl`,
+ * `--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" }
+ * parseVisualArgv(["--webgl"]); // { renderer: "webgl" }
+ * ```
+ */
+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). With `renderer:
+ * "webgl"` (`--webgl`) only the tests with `webgl: true` run, the page opens with
+ * `?renderer=webgl` and its pictures go to `screen.webgl.webp`; `state.json` and `describe.json`
+ * are shared with the WebGPU leg and compared as always. 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 the requested backend or stop loading. In the WebGL leg, also when `only` names a
+ *   test without `webgl: true`.
+ * @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 VisualApp, type VisualOptions, type VisualPage, type VisualRenderer, type VisualReport, type VisualSetup, type VisualStart, type VisualStep, type VisualTest, type VisualTestResult, type VisualTolerance, defineVisualTest, parseVisualArgv, runVisualTests };