---
url: /pawn/docs/guide/testing.md
description: >-
  Testing and debugging: seeded random numbers (engine.random), headless test
  helpers from @pawnjs/core/testing, and the Debug overlay with an entity
  inspector.
---

# Testing and debugging

An engine runs headless: without a canvas it skips drawing, and with a
`ManualDriver` time moves only when the code says so. That makes game and
dashboard logic testable with any test runner; [Headless](./headless.md)
shows what runs without a page and how to write a scene for both. Three
things help.

## Random numbers from a seed

`engine.random` gives random numbers from a seed. The same seed gives the
same numbers, so a run with a seed plays out the same way every time: in a
test, a replay or a bug report. Use it instead of `Math.random()` in
systems and behaviors.

```ts
import { Engine } from "@pawnjs/core";

const engine = new Engine({ canvas, seed: 42 });
const { random } = engine;

random.next(); // 0..1, like Math.random()
random.range(-1, 1); // -1 up to (not including) 1
random.int(1, 6); // a die: 1, 2, 3, 4, 5 or 6
random.chance(0.1); // true one time in ten
random.pick(["runner", "tank"]);
random.shuffle([1, 2, 3]);
```

* Without `seed` the engine picks a new one each time; read it back from
  `engine.random.seed`, say to log it with an error and replay the run.
* `random.state` is where the sequence is: save it and set it back to
  repeat the numbers from that point. `random.reseed(seed)` starts over.
* Core behaviors that need chance (`burst`, `SoundOn`'s pitch
  `variation`) use `engine.random`.
* `Random` is also exported on its own: `new Random(seed)`, or
  `new Random()` for a seed from `Random.newSeed()` (`Math.random()`).

## Test helpers

`@pawnjs/core/testing` creates engines for tests and moves them through time.

```ts
import { Position, Velocity } from "@pawnjs/core";
import { createTestEngine, runFor, runUntil } from "@pawnjs/core/testing";

const engine = createTestEngine();
const ball = engine.world.spawn(Position, Velocity({ y: 1 }));

runFor(engine, 2); // two seconds in frames of 1/60 s
ball.get(Position)?.y; // 2

const seconds = runUntil(engine, () => (ball.get(Position)?.y ?? 0) > 5);
engine.dispose();
```

* `createTestEngine(config?)` is a headless engine driven only by
  `engine.step()`, with `engine.random` seeded by `TEST_SEED` (1). Any
  `EngineConfig` goes over these defaults.
* `runFor(engine, seconds, { step })` steps the engine through `seconds`
  in equal frames (`TEST_STEP`, 1/60 s, unless `step` says otherwise) and returns how
  many ran.
* `runUntil(engine, done, { step, timeout })` steps until `done()` is
  true and returns the seconds it took; after `timeout` seconds (60 by
  default) it throws.
* Drive the pointer from code with `Pointer`'s `moveTo`, `press` and
  `release`; see [Input](./input.md).

## Debug overlay and inspector

`Debug` shows what the engine is doing while an app is built: frames a
second, milliseconds spent in each phase's systems, entities in the world
and how many have each trait. Click an entity to inspect it: the panel
lists its traits with their values, and numbers, switches, text and
choices can be changed live.

```ts
import { Debug } from "@pawnjs/core";

engine.use(new Debug({ visible: false })); // e.g. in development builds only

const debug = engine.plugin(Debug);
debug.visible = true; // or press ` (backquote, left of 1)
debug.select(entity);
const { fps, entities, phaseMs } = debug.stats;
```

* `debug.selected` is the entity the inspector shows (`select(undefined)`
  clears it).
* The backquote key shows and hides the overlay; `toggleKey` changes it
  (`""` for none). `visible` sets whether it starts shown.
* Clicking an entity while the overlay is shown selects it, once the
  engine has a `Pointer`; `enablePick: false` turns that off.
* `stats` holds `fps`, `phaseMs` (milliseconds in systems per phase),
  `systemsMs` (all phases), `entities` and `traits` (entities per
  registered trait, most first, without zeros).
* `stats` is averaged over `interval` seconds (0.5 by default) and
  `subscribe(listener)` hears each update and each new selection. Without a
  page (a test, a server), or with `enableOverlay: false`, `Debug` only
  gathers the data.
* `inspect(entity)` returns the entity's traits, their params and values
  as data, for a panel of your own.
* The inspector lists the traits in `engine.traits`: core transforms,
  `Tint`, `Shape`, behaviors, and your own traits from `defineTrait` once
  registered with `engine.traits.register(Trait)`; see
  [Saving scenes](./snapshots.md).
