Testing physics

Skill ferret-physics-testing · download all skills · SKILL.md

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.