---
name: ferret-physics-testing
description: Use to test Ferret physics: a headless world, driving the fixed step by hand, asserting against the laws the capabilities implement (not numbers seen once), golden traces, what determinism promises, and Playwright screenshots for what only eyes can judge.
---

# Testing physics

## When to use
Writing a unit test for a capability or level, or checking that a replay is stable.

## The model
Physics runs headless: no renderer, a world per test, `world.step()` / `world.run(seconds)`. The same inputs through the same build give the same result bit for bit **on the same machine**: fixed step, capabilities in a fixed order (phase, `order`, name), no randomness on the light kernel, `seededRng` where chance is needed.

## Steps
1. Build a test world with the repo's helpers; add the capability under test; `tw.dispose()` after.
2. Assert against a law: Torricelli drain time, `√(g h)` wave speed, `m / (ρ A)` draft, energy balance, `F L / E A` stretch.
3. Golden traces for regressions; compare within a tolerance across machines.
4. Visual checks (a piece rotating the wrong way) need eyes: Playwright runs in `tests/e2e`, one scene per behaviour.
5. Worked examples live in `tests/unit/examples/`.

## Check afterwards
The test fails when the behaviour is broken (try it); it passes alone and in the suite.

## What usually goes wrong
- A test passes alone and fails in the suite: shared state; Havok is one module per file.
- Asserting a number copied from one run.
- Variable `dt`: always the fixed step.
- Expecting identical results across different machines or builds.

## Files

- `reference/testing.md` — Running physics headless, driving the step by hand, asserting against the laws the capabilities implement, golden traces, and what determinism does and does not promise.