Parity and tests
Two checks keep the pixels honest: parity compares ports with pixelfx itself, and the determinism test pins native and wasm builds to one set of frame hashes.
Parity against pixelfx
Parity renders an effect with pixelfx (under Node) and with its pixfx port, then compares every pixel of every frame of both layers. It needs Node and a pixelfx checkout:
git clone https://github.com/patch-gg/pixelfx /tmp/pixelfx
git -C /tmp/pixelfx checkout 044e12a
cargo run -p pixfx-export --example parity -- fire/candle --pixelfx /tmp/pixelfx --out target/parity
Output:
fire/candle: colour 0.00% differ, light 0.00% differ → PASS
- The gate: colour and light each differ on at most 0.5% of pixels. Exit code 0 is PASS, 1 is FAIL, 2 means the comparison could not run.
target/parity/<id>.side.gifshows pixelfx on the left and pixfx on the right.- If the two renders differ in frame count or size, it says so on stderr.
- Without
--pixelfx, it uses$PIXELFX, then./pixelfx.
The reference render comes from tools/pixelfx-ref.mjs, which runs pixelfx's own renderFrames with no backdrop and no stand-in actor, at the effect's default options, edge fade applied.
Current results
Against pixelfx commit 044e12a (version 0.3.1). A later pixelfx may have changed an effect.
| Effect | Colour | Light | Result |
|---|---|---|---|
fire/candle | 0 pixels | 0 pixels | PASS |
fire/campfire | 0 pixels | 0 pixels | PASS |
fire/brazier | 0 pixels | 0 pixels | PASS |
The ledger
An effect that ships below the gate must be listed in parity/LEDGER.md, one line each: <id> · <date> · colour x% light y% · approved by owner, after the owner has approved it by eye. The ledger is empty.
Determinism
Frame hashes of each effect, for seeds 1, 2 and 7 and frames first, second, a quarter, middle and last, are checked against its own entry in crates/pixfx-effects/tests/goldens/frame_hashes.json, natively and in wasm. A hash is FNV-1a 64 over every colour word then every light word. The test is ignored by default; built with one effect's feature it checks that effect alone.
cargo test -p pixfx-effects --no-default-features --features fire-candle --test determinism -- --ignored
cargo test -p pixfx-effects --test determinism -- --ignored
wasm-pack test --node crates/pixfx-effects --test determinism -- --include-ignored
Record new goldens on a native target only, after a deliberate change; effects the build leaves out keep theirs:
PIXFX_BLESS=1 cargo test -p pixfx-effects --test determinism -- --ignored
A failure names each effect that differs, with its hashes and the golden's.
Other tests
| Where | Covers |
|---|---|
crates/pixfx-core/tests | Painter, instances and time steps, compositing, simulation helpers. |
crates/pixfx-effects/tests/fire.rs | Fire effects' behaviour. |
crates/pixfx-export/tests | Sheets, bakes, the parity comparison and its options. |
crates/pixfx-wasm/tests/web.rs | The JS bindings, under wasm-pack test --node. |
crates/pixfx-scene/tests | The scene's decisions: placement, shared frames, the frame budget, the view, hit-stop. |
packages/pixfx-web/tests | The JS runtime under bun test against the real wasm, including frames painted on workers against frames painted on the spot. |
Tests
Each crate and package tests itself, and there is no repo-wide gate: run the tests of what you changed, as its AGENTS.md lists under "Before you finish" (cargo test -p <crate>, bun run check in a package). Working on one effect, build it alone, so nothing else compiles or runs:
cargo test -p pixfx-effects --no-default-features --features fire-candle --all-targets