Core Concepts¶
How it all fits together
The flow is simple: you describe your system → ordeal explores what can go wrong → when something breaks, it shows you the simplest example.
That's it. You tell ordeal how your code works, it tries thousands of ways to break it, and when it finds a problem, it strips away everything that doesn't matter so you can see exactly what went wrong.
Each concept below is one piece of this flow. You don't need to learn them all at once — start with what you need.
Ordeal's design is built on a few key ideas. Each concept has its own deep-dive page.
Understand¶
What do you want to do?
- Want to test your service for failures? → Chaos Testing
- Want to know what properties your code has? → Property Assertions
- Want ordeal to find bugs automatically? → Coverage Guidance
- Want to understand a failure ordeal found? → Shrinking
- Want to inject specific faults? → Fault Injection
-
Chaos Testing — What chaos testing is, how ChaosTest works, the nemesis, swarm mode. The foundation.
-
Property Assertions —
always,sometimes,reachable,unreachable. The Antithesis assertion model: state what must be true, let the machine find violations. -
Fault Injection — External faults (PatchFault) and inline faults (buggify). The FoundationDB model for Python.
-
Coverage Guidance — How the Explorer uses edge hashing, checkpoints, and energy scheduling to find bugs that random testing misses.
-
Shrinking — How ordeal minimizes failures: delta debugging, step elimination, fault simplification. From a 50-step trace to 3.
In plain English
The table below is a cheat sheet. The "Origin" column shows where each idea comes from — industry-proven approaches from teams that build systems where bugs cost millions. Ordeal packages these ideas so you get the benefits without needing to know the history.
You do not need to know those tools. Just use ordeal and the lessons are already built in.
Quick reference¶
| Concept | One-liner | Origin |
|---|---|---|
| ChaosTest | Stateful test with nemesis + swarm | Jepsen + Hypothesis |
| Assertions | Temporal properties across runs | Antithesis |
| Faults | External fault injection via PatchFault | Chaos engineering |
| Buggify | Inline fault gates — no-op in production | FoundationDB |
| Explorer | Coverage-guided exploration with checkpoints | Antithesis + AFL |
| Shrinking | Minimize failing traces to minimal reproduction | Delta debugging |
| QuickCheck | Boundary-biased property testing | Jane Street |
| Invariants | Composable checks: finite & bounded(0, 1) |
— |