/testing

name: pixi-vn-testing
description: Use when an AI agent (or any external script) needs to play-test a running Pixi'VN game end-to-end in a real browser — starting the game, advancing/branching the story, answering input prompts, going back, and reading/writing storage — via `Game.testing`, the opt-in devtools bridge exposed on `window`. Load this before wiring up automated/agent-driven playtesting, not for authoring story content itself (see `pixi-vn-narration`).

Pixi'VN Testing module

When to use this skill

Use this skill when the task is to **play the game from the outside** — driving it like a player would, but from a script or an AI agent evaluating JavaScript in the page, instead of clicking UI. Typical asks this covers: "start the game and play through label X", "verify choice B leads to ending Y", "check that this bug repros after going back three steps", "seed storage with `gold: 100` and confirm the shop unlocks", "run this game headless as a regression test".

This assumes the game's dev server (or a build served on a URL) and a browser are already running/reachable — starting either one is outside this skill; it only covers the game-control API itself. Do not use this skill for writing story content (`pixi-vn-narration`), save-file persistence (`pixi-vn-saves`), or the go-back UI/internals (`pixi-vn-history`) — those are the modules this skill drives, not what it teaches.

1. Why you can't just call `narration.continue({})` from the console

`narration.continue`, `.call`, `.jump`, `narration.choices.select`, and `stepHistory.back` all take a `props` argument typed as `StepLabelProps` — the exact object a real game passes from its UI layer. Most real projects augment `StepLabelProps` (via TS module augmentation, see `pixi-vn`) with app-specific fields: a router `navigate`, an i18n `t`, a `toast`, etc. (the official React template does exactly this — see `pixi-vn-narration` section 9). If a step calls `props.navigate(...)` or `props.t(...)`, passing `{}` from a console/script call throws immediately.

`Game.testing` solves this once: the app pushes its real, live props to it (via `setProps`, see below) wherever it already builds them, and every action it exposes merges those in before delegating — so agent-driven calls behave exactly like a real player action, with no need to reconstruct or fake the app's props shape.

2. Enabling it

`Game.testing` is **opt-in and disabled by default**, and nothing about it depends on any particular bundler (Vite, Webpack, or none at all). Two independent pieces make it work:

• **Turning the `window` bridge on/off** — `Game.testing.enable(options?)` / `.disable()`.
• **Keeping it supplied with live props** — `Game.testing.setProps(props)`.

Turning it on/off

If the project uses `@drincs/pixi-vn/vite`'s `vitePluginPixivn`, this is already handled: its `testing` option **defaults to `true`**, auto-enabling `Game.testing` for as long as `vite dev` keeps running (by injecting a small module into `index.html`) — **never** during `vite build`, regardless of the option. No app code needed for this part:

// vite.config.ts — this is already the default, shown here just to make it explicit
vitePluginPixivn({ testing: true }); // or { testing: { windowKey: "myGameTesting" } }, or false to opt out

Pass `testing: false` if you don't want this — e.g. a dev server shared with other people that you don't want remote-controllable.

Without the Vite plugin (a different bundler, or no bundler-level integration at all), call it yourself, gated behind your own dev-only check:

import { Game } from "@drincs/pixi-vn";

if (import.meta.env.DEV) {
  // or process.env.NODE_ENV !== "production", a Webpack DefinePlugin flag, etc.
  Game.testing.enable();
}

• `options.windowKey` (default `"pixiVN"`) — the property name the API is attached under on `window`.
• Returns the same API object it attaches to `window[windowKey]`, in case you want to keep a direct

reference instead of going through `window`.

• Calling `enable` again (e.g. on hot reload) replaces the previous session instead of stacking.
• `Game.testing.disable()` tears it down (detaches from `window`, stops capturing errors).
• `Game.testing.isEnabled()` reports whether a session is currently active.

**Only enable this when you actually want the game remote-controllable.** It hands out full control over game state (see §4) to anything that can run JavaScript in that page — treat it like any other devtools/debug backdoor.

Keeping it supplied with live props: `setProps`

Call `Game.testing.setProps(props)` **unconditionally**, wherever your app already builds its `StepLabelProps` — it's a cheap assignment, safe to call whether or not testing happens to be enabled right now, and every `Game.testing` action reads through whatever was passed here most recently:

import { Game, type StepLabelProps } from "@drincs/pixi-vn";

function useGameProps(): StepLabelProps {
  // ... build props the same way your app always has ...
  const props = { navigate, t, toast /* ... */ };
  Game.testing.setProps(props); // [!code focus]
  return props;
}

React template convention

The official React template's `useGameProps()` (`src/lib/hooks/props-hooks.ts` — see `pixi-vn-narration` section 9) already ends with exactly that `Game.testing.setProps(props)` call, and `vite.config.ts`'s `vitePluginPixivn(...)` call needs no extra option — `testing` defaults to `true`. Since `useGameProps()` already runs on every render of every component that needs game props, this is the only line the template needs: no dedicated bridge component, no manual `enable()` call.

Routing through the app's own narration functions: `setActions`

Most real apps don't call `narration.continue`/`stepHistory.back`/etc. straight from a "next" button — they wrap them in their own functions that also handle UI-only concerns a test session should trigger too: a loading indicator, refusing to adv