Invariant-First Testing

The testing philosophy that a test should state the property a system must preserve, not replay the incident that revealed a bug. Now the canonical home of this methodology is the Frontend and Design Skills skill; this page is retained for older backlinks.

Superseded by Frontend and Design Skills. The invariant-first methodology was merged into the /tests skill at skills/engineering/dedalus-tests/SKILL.md (dedalus-labs/dedalus#2119, May 2026). Use Frontend and Design Skills for all new work. The summary below captures the core ideas so existing wiki links remain meaningful. Source: skills/engineering/dedalus-tests/SKILL.md, 2026-05-31

Start with the invariant

The natural sequence after a bug is: reproduce, write a failing test, patch, ship. That yields tests describing what broke once, not what must always be true. Before writing a test, answer "what system property was violated?" and write the test for that property. Source: skills/engineering/dedalus-tests/SKILL.md, 2026-05-31

The name is the contract

A test name should read like a sentence that could appear in an architecture document.

• invariant_*: a property that must always hold (the default prefix)
• design_*: an intentional policy decision that could reasonably go another way
• no prefix for trivial pure-function tests such as round trips or math helpers

If a name contains an HTTP status code, error message, or internal function name, that is a signal to elevate the name to the underlying invariant. Good: invariant_session_survives_guest_env_rejection. Weak: test_issue_123_repro. Source: skills/engineering/dedalus-tests/SKILL.md, 2026-05-31

Smallest honest layer, generalized body

Test at the smallest layer that can still fail for the bug class you care about: unit tests for pure logic, model or property tests for state transitions, the real boundary for interface contracts, and integration or end-to-end tests for user-visible behavior. Exercise the general case, not only the specific trigger; keep the concrete scenario as a comment so the name stays stable. Source: skills/engineering/dedalus-tests/SKILL.md, 2026-05-31

Earn its keep

Keep one reason to fail per test, assert externally visible behavior, and use realistic fakes (a fake that always returns success is not a model). For a bug fix, run the new test red before the fix when feasible and report how many were red before and which command makes them green. Coverage is a map to unvisited code, not proof of correctness. Source: skills/engineering/dedalus-tests/SKILL.md, 2026-05-31

Concept Position

---

Timeline

• 2026-07-01 | Concepts category refresh added this page to the Capability, tool, and skill routing family, linked it to Concept System Map, and kept it standalone because it owns this reusable mental model: The testing philosophy that a test should state the property a system must preserve, not replay the incident that revealed a bug. Now the c... Source: User request, 2026-07-01
• 2026-06-24 | Moved from wiki/skills/ to wiki/concepts/ because it is a superseded methodology page, not an executable skill catalog page. The executable skill remains Frontend and Design Skills. Source: User request, 2026-06-24
• 2026-05-31 | Expanded from a one-line redirect stub into a substantive summary of the invariant-first methodology (start with the invariant, name as contract, smallest honest layer, generalized body, earn-its-keep), while keeping the prominent supersession pointer to Frontend and Design Skills. Source: skills/engineering/dedalus-tests/SKILL.md, 2026-05-31
• 2026-05-22 | Marked superseded by Frontend and Design Skills after the merge into /tests (dedalus-labs/dedalus#2119). Source: skills/engineering/dedalus-tests/SKILL.md, 2026-05-22
• 2026-04-06 | Initial stub created. Source: skills/engineering/dedalus-tests/SKILL.md, 2026-04-06