@aethervtt/shard-testing 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-testing
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import { type HeadlessProject } from '@aethervtt/shard-node';
+import type { App } from '@aethervtt/shard-runtime';
+export { describe, expect } from 'vitest';
+type Json = Record<string, any>;
+/**
+ * The game under test: a headless app with the project loaded, fixed timestep, fixed seed. Every
+ * method maps to a protocol call, so tests exercise the same surface agents use.
+ */
+export declare class Game {
+    readonly project: HeadlessProject;
+    private nextId;
+    constructor(project: HeadlessProject);
+    get app(): App;
+    /** Any protocol method. Throws the ShardError on failure. */
+    call<T = Json>(method: string, params?: unknown): Promise<T>;
+    /** Loads a scene file, replacing the start scene. */
+    load(scenePath: string): Promise<void>;
+    /** Runs `frames` frames at the fixed timestep. */
+    step(frames?: number): Promise<void>;
+    /** A component's JSON value on the entity at `path` (or id), as the protocol would report it. */
+    get(entity: string | number, component: string): Json;
+    /** All components of an entity as JSON. */
+    entity(entity: string | number): Promise<Json>;
+    patch(entity: string | number, components: Json): Promise<void>;
+    readonly input: {
+        /** Holds an action (`"<map>.<action>"`) or key (`"KeyW"`) until released. */
+        hold: (name: string) => void;
+        release: (name: string) => void;
+        /** Press for one frame. */
+        press: (name: string) => Promise<void>;
+    };
+    /**
+     * Sounds started, stopped, and dropped (audio plugin) from frame `since`, as `audio.log` returns
+     * them: `{ frame, event, clip, entity, path, bus, position, gain, pan, reason }`.
+     */
+    audioLog(since?: number): Promise<Json[]>;
+    /** UI (ui plugin): read the HUD as data and press buttons by path, without pixel coordinates. */
+    readonly ui: {
+        /** `ui.describe`: every tree with rects, text, widget state, focus, and anchors. */
+        describe: () => Promise<Json>;
+        /** One node from `ui.describe` by scene path (or a unique suffix, like "fuel/label"). */
+        node: (path: string) => Promise<Json | undefined>;
+        /** Clicks a button or toggle (`ui.click`); step a frame for systems to see the UiClick. */
+        click: (path: string) => Promise<void>;
+        focus: (path: string | null) => Promise<void>;
+    };
+    /** Navigation (nav plugin): paths and agents as data. */
+    readonly nav: {
+        /** `nav.describe`: grids, navmeshes (tiles, last bake), and agents. */
+        describe: () => Promise<Json>;
+        /** `nav.path` between two world points: `{ status, length, corners }`. */
+        path: (from: [number, number, number], to: [number, number, number]) => Promise<{
+            status: 'complete' | 'partial' | 'none';
+            length: number;
+            corners: number[][];
+        }>;
+        /** One NavAgent from `nav.describe` by scene path (or a unique suffix): status, remaining, route. */
+        agent: (path: string) => Promise<Json | undefined>;
+    };
+    /** Saved games (save plugin): the same calls as save_game and load_game. */
+    readonly saves: {
+        /** Saves the game to a slot; returns `save.describe` of it. */
+        write: (slot: string, meta?: unknown) => Promise<Json>;
+        /** Loads a slot, or a save file (an edited fixture). Returns `{ scenes, spawned, warnings }`. */
+        load: (slot: string | Json) => Promise<Json>;
+        /** A slot's save as JSON, or without a slot the game as it would save now. */
+        read: (slot?: string) => Promise<Json>;
+        describe: (slot?: string) => Promise<Json>;
+    };
+    /** Settings resources (`engine/Settings` by default): read, or set and apply at once. */
+    readonly settings: {
+        get: (name?: string) => Promise<Json>;
+        set: (values: Json, name?: string) => Promise<Json>;
+    };
+    /** Switches the locale (`"pt-BR"`); keyed text updates on the next frame. */
+    locale(tag: string): Promise<void>;
+    /** Saves a PNG of a camera (default: the first) to `.shard/test-results/<name>`. Returns the path. */
+    screenshot(name: string, options?: {
+        camera?: string;
+        width?: number;
+        height?: number;
+    }): Promise<string>;
+    private inject;
+    private resolve;
+}
+/** A gameplay test. Each test gets a fresh game; the GPU is shared across a file. */
+export declare function test(name: string, fn: (ctx: {
+    game: Game;
+}) => Promise<void> | void, timeout?: number): void;
+export declare namespace test {
+    var skip: (name: string, _fn: (ctx: {
+        game: Game;
+    }) => Promise<void> | void) => void;
+}

package/dist/index.js

@@ -0,0 +1,209 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { findComponent, ShardError } from "@aethervtt/shard-core";
+import { createNodeGpuContext } from "@aethervtt/shard-gpu/node";
+import { openProject } from "@aethervtt/shard-node";
+import { findEntityByPath } from "@aethervtt/shard-scene";
+import { afterAll, test as vitestTest } from "vitest";
+import { describe, expect } from "vitest";
+class Game {
+  project;
+  nextId = 1;
+  constructor(project) {
+    this.project = project;
+  }
+  get app() {
+    return this.project.app;
+  }
+  /** Any protocol method. Throws the ShardError on failure. */
+  async call(method, params) {
+    const response = await this.project.server.handle({
+      jsonrpc: "2.0",
+      id: this.nextId++,
+      method,
+      params
+    });
+    if (response.error) {
+      const data = response.error.data;
+      throw new ShardError(data?.code ?? "testing/protocol", response.error.message, {
+        path: data?.path,
+        hint: data?.hint
+      });
+    }
+    return response.result;
+  }
+  /** Loads a scene file, replacing the start scene. */
+  async load(scenePath) {
+    for (const id of await this.call("app.describe").then((d) => d.scenes)) {
+      if (id !== scenePath)
+        await this.call("scene.load", { json: { version: 1, entities: [] }, id });
+    }
+    await this.call("scene.load", { file: scenePath, id: scenePath });
+  }
+  /** Runs `frames` frames at the fixed timestep. */
+  async step(frames = 1) {
+    await this.call("time.step", { frames });
+  }
+  /** A component's JSON value on the entity at `path` (or id), as the protocol would report it. */
+  get(entity, component) {
+    const world = this.app.world;
+    const e = this.resolve(entity);
+    const def = findComponent(component);
+    if (!def || !world.has(e, def)) throw missing(entity, component);
+    return def.serialize(world.get(e, def));
+  }
+  /** All components of an entity as JSON. */
+  async entity(entity) {
+    return (await this.call("entity.get", { entity })).components;
+  }
+  async patch(entity, components) {
+    await this.call("entity.patch", { entity, components });
+  }
+  input = {
+    /** Holds an action (`"<map>.<action>"`) or key (`"KeyW"`) until released. */
+    hold: (name) => this.inject(name, true),
+    release: (name) => this.inject(name, false),
+    /** Press for one frame. */
+    press: async (name) => {
+      this.inject(name, true);
+      await this.step(1);
+      this.inject(name, false);
+    }
+  };
+  /**
+   * Sounds started, stopped, and dropped (audio plugin) from frame `since`, as `audio.log` returns
+   * them: `{ frame, event, clip, entity, path, bus, position, gain, pan, reason }`.
+   */
+  async audioLog(since = 0) {
+    return (await this.call("audio.log", { since })).entries;
+  }
+  /** UI (ui plugin): read the HUD as data and press buttons by path, without pixel coordinates. */
+  ui = {
+    /** `ui.describe`: every tree with rects, text, widget state, focus, and anchors. */
+    describe: async () => this.call("ui.describe"),
+    /** One node from `ui.describe` by scene path (or a unique suffix, like "fuel/label"). */
+    node: async (path) => {
+      const d = await this.call("ui.describe");
+      const find = (n) => {
+        const p = n.path;
+        if (p === path || p?.endsWith(`/${path}`)) return n;
+        for (const c of n.children ?? []) {
+          const hit = find(c);
+          if (hit) return hit;
+        }
+        return void 0;
+      };
+      for (const r of d.roots) {
+        const hit = find(r.tree);
+        if (hit) return hit;
+      }
+      return void 0;
+    },
+    /** Clicks a button or toggle (`ui.click`); step a frame for systems to see the UiClick. */
+    click: async (path) => {
+      await this.call("ui.click", { entity: path });
+    },
+    focus: async (path) => {
+      await this.call("ui.focus", { entity: path });
+    }
+  };
+  /** Navigation (nav plugin): paths and agents as data. */
+  nav = {
+    /** `nav.describe`: grids, navmeshes (tiles, last bake), and agents. */
+    describe: async () => this.call("nav.describe"),
+    /** `nav.path` between two world points: `{ status, length, corners }`. */
+    path: async (from, to) => this.call("nav.path", { from, to }),
+    /** One NavAgent from `nav.describe` by scene path (or a unique suffix): status, remaining, route. */
+    agent: async (path) => {
+      const d = await this.call("nav.describe");
+      return d.agents.find((a) => a.path === path || a.path?.endsWith(`/${path}`));
+    }
+  };
+  /** Saved games (save plugin): the same calls as save_game and load_game. */
+  saves = {
+    /** Saves the game to a slot; returns `save.describe` of it. */
+    write: async (slot, meta) => this.call("save.write", meta === void 0 ? { slot } : { slot, meta }),
+    /** Loads a slot, or a save file (an edited fixture). Returns `{ scenes, spawned, warnings }`. */
+    load: async (slot) => this.call("save.load", typeof slot === "string" ? { slot } : { json: slot }),
+    /** A slot's save as JSON, or without a slot the game as it would save now. */
+    read: async (slot) => this.call("save.read", slot ? { slot } : {}),
+    describe: async (slot) => this.call("save.describe", slot ? { slot } : {})
+  };
+  /** Settings resources (`engine/Settings` by default): read, or set and apply at once. */
+  settings = {
+    get: async (name = "engine/Settings") => (await this.call("settings.get", { name })).settings[name],
+    set: async (values, name = "engine/Settings") => this.call("settings.set", { name, values })
+  };
+  /** Switches the locale (`"pt-BR"`); keyed text updates on the next frame. */
+  async locale(tag) {
+    await this.call("locale.set", { locale: tag });
+  }
+  /** Saves a PNG of a camera (default: the first) to `.shard/test-results/<name>`. Returns the path. */
+  async screenshot(name, options = {}) {
+    const shot = await this.call("render.capture", options);
+    const dir = join(this.project.root, ".shard", "test-results");
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, name);
+    await writeFile(file, Buffer.from(shot.data, "base64"));
+    return file;
+  }
+  inject(name, pressed) {
+    const isAction = name.includes(".");
+    void this.call("input.inject", isAction ? { action: name, pressed } : { key: name, pressed });
+  }
+  resolve(entity) {
+    const world = this.app.world;
+    const e = typeof entity === "number" ? entity : findEntityByPath(world, entity);
+    if (e === void 0 || !world.isAlive(e)) {
+      throw new ShardError("testing/unknown-entity", `No entity ${JSON.stringify(entity)}`, {
+        hint: 'Use a scene path like "ship/camera" or an entity id.'
+      });
+    }
+    return e;
+  }
+}
+function missing(entity, component) {
+  return new ShardError(
+    "testing/missing-component",
+    `${JSON.stringify(entity)} has no "${component}"`
+  );
+}
+let sharedGpu;
+const open = [];
+afterAll(() => {
+  for (const p of open.splice(0)) p.close();
+  sharedGpu?.destroy();
+  sharedGpu = void 0;
+});
+function projectRoot() {
+  return process.env.SHARD_PROJECT_ROOT ?? process.cwd();
+}
+function test(name, fn, timeout = 3e4) {
+  vitestTest(
+    name,
+    async () => {
+      sharedGpu ??= await createNodeGpuContext();
+      const project = await openProject({
+        root: projectRoot(),
+        // Test files import project modules directly; the game must use the same instances.
+        code: "source",
+        gpu: sharedGpu,
+        width: 320,
+        height: 180
+      });
+      open.push(project);
+      await fn({ game: new Game(project) });
+    },
+    timeout
+  );
+}
+test.skip = (name, _fn) => {
+  vitestTest.skip(name, () => {
+  });
+};
+export {
+  Game,
+  describe,
+  expect,
+  test
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@aethervtt/shard-testing",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-core": "0.0.1",
+    "@aethervtt/shard-gpu": "0.0.1",
+    "@aethervtt/shard-node": "0.0.1",
+    "@aethervtt/shard-protocol": "0.0.1",
+    "@aethervtt/shard-runtime": "0.0.1",
+    "vitest": "^5.0.1",
+    "@aethervtt/shard-scene": "0.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/testing"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  }
+}