Find a real failure. Keep it fixed.¶

Ordeal exercises Python code with awkward inputs and realistic failures. When something breaks, it tries to reproduce the same failure and tells you what to do next. You do not need to choose among Ordeal's testing techniques first.

Start here¶

pip install ordeal                  # or: uv tool install ordeal
cd your-project
ordeal scan .                       # auto-detect the package; write nothing

If auto-detection cannot find the package, pass a module or Python file:

ordeal scan myapp.scoring
ordeal scan myapp/scoring.py

A normal scan does not write project artifacts, but it does import and execute target code. Isolate code that can send email, mutate production data, or call live services.

Keep the failure fixed¶

When the first scan finds a useful failure, save it and follow the printed command:

ordeal scan . --save
# fix the product code
ordeal verify <finding-id> --allow-unsafe-artifacts
ordeal verify --ci

This is the core workflow:

scan → save one witness → fix → verify the same witness → guard it in CI

Commit tests/test_ordeal_regressions.py and tests/ordeal-regressions.json. The richer .ordeal/findings/ review history may stay local. The Durable Regression Workflow explains why the generated test must fail before the fix and pass afterward.

Read the result¶

Result	Plain meaning	Next action
`supported`	The same failure matched during immediate replay	Save it, fix it, and verify it
`exploratory`	Interesting signal, but replay evidence is weaker	Investigate; do not treat it as a proven bug
`expected`	The input violated a known precondition	Usually no product fix
`blocked`	Ordeal could not construct enough of the target	Inspect targets and add a test harness

“Supported” is deliberately narrow: the exception type, message, and terminal source location matched. It does not prove the root cause or certify the project.

If the first scan needs help¶

Scan Quickstart — the complete first-run path.
Object Harnesses — methods that need setup or state.
Scan Troubleshooting — blocked, noisy, or slow scans.
Finding Evidence — what a bounded claim establishes.
Evidence Closure — what important failure stories were inferred but not exercised, and the cheapest safe next experiment.

New users can stop here. Everything below is a specialized workflow.

Advanced workflows

### Measure test quality Use `ordeal audit` for a combined generated-check assessment and `ordeal mutate` to judge whether selected existing tests catch deliberate changes. Start with [Test Protection](guides/test-protection.md), then use the [CI policy](guides/test-protection-ci.md) or [FAQ](guides/test-protection-faq.md). ### Exercise a long-lived service Start with the [service evidence loop](concepts/service-evidence-loop.md), then the [Compose quickstart](guides/compose-quickstart.md) and complete [evidence loop](guides/compose-evidence-loop.md). Then [Put real Compose recovery in CI](guides/compose-operations.md). Use [Reliability Coverage](concepts/reliability-coverage.md) to see what ran. ### Validate a refactor or migration - Functions: [Differential Quickstart](guides/differential-quickstart.md) and [Divergence Evidence](concepts/divergence-evidence.md). - Commits: [Revision Diff](guides/revision-diff.md) with [troubleshooting](guides/revision-diff-troubleshooting.md) and its [schema](reference/revision-diff-schema.md). - Stateful workflows: [System Differential Testing](concepts/system-differential.md). - Module replacements: [Safe Migrations](concepts/safe-migrations.md) before the [Migration Workflow](guides/migration-workflow.md). Parity can preserve an old bug. ### Write custom chaos tests [Custom Chaos Tests](getting-started.md) introduces faults, rules, and invariants. Continue with [Writing Tests](guides/writing-tests.md), [Property Assertions](concepts/property-assertions.md), [Fault Injection](concepts/fault-injection.md), and [Coverage Guidance](concepts/coverage-guidance.md). ### Use lower-level tools - [Explorer](guides/explorer.md) — coverage-guided stateful exploration. - [Auto Testing](guides/auto.md) — mining, fuzzing, and programmatic scanning. - [Mutations](guides/mutations.md) — direct mutation testing. - [Simulation](guides/simulate.md) — deterministic clocks and filesystems. - [Integrations](guides/integrations.md) — API and optional engine bridges. - [Philosophy](philosophy.md) and [Core Concepts](core-concepts.md) — the ideas behind the tools.

Reference¶

Full CLI reference — every command and expert flag.
Configuration — ordeal.toml.
API reference — Python functions and types.
Scan evidence schema — finding JSON.
Evidence closure schema — reliability-map JSON.
Durable regression schema — bindings and manifests.
Divergence evidence schema — comparison artifacts.
Test protection schema — audit and mutation evidence.
Troubleshooting — cross-workflow problems.