Where tests go and how to run them

The long form is docs/book/src/dev/testing.md.

Placement

• A regression test goes into its area's existing test file (booleans, blends, shell, STEP, naming, ...), never a new file named after the bug (#3226).
• Engine tests sit next to the code or in *_tests.rs files, measured against a value you can derive.
• UI scenarios are JSON in crates/ui-egui/tests/scenarios/*.json. Put {"pending": "why"} in a scenario that records a bug before it is fixed, and remove it in the fixing PR.
• Reference tests are tests/oracle/<case>/recipe.json with an expected.json beside it, run by cargo xtask oracle, expected values in closed form (tools/oracle-analytic/) or from FreeCAD as a separate program (tools/freecad-oracle/). A known failure names its issue ("known_failure": "#123"). Never change an expected value to match SolidCraft's output, and never take one from a commercial CAD product.
• Crash fixes: a regression test from the report's design.sc and replay.json (skills/solidcraft-crash-safety/SKILL.md).

Unit test or rig case

• Unit tests assert the code's logic: which edges a chain picks, name resolution, history labels, refusal wording, hostile input, parsing and saving (a_corner_round_wider_than_its_faces_overflows_and_takes_the_corners_other_edges: per-edge radii, which no command takes).
• The rig asserts geometry (exact volumes, shapes, seams, refusals) with a hand-derived answer. A test doing both keeps only its logic. tests/kernel-cases/ only shrinks: kernel cases go to solidcore (CONTRIBUTING.md "Tests"); command, UI and product-rule cases stay here.

A failing test needs its fix

A failing test cannot merge without its fix (it turns main red): include it, or list the test and cause in tests/KNOWN_FAILING_TESTS (cargo xtask known-failing); the fix drops the line.