testscribe is a Rust testing framework for stateful systems.
It turns tests into readable domain scenarios — not just a list of ... ok lines.
Tests don’t verify functions. They shape behavior.
Traditional test output tells you that something passed, not what your system does:
test cancel_order_restores_inventory ... ok
test partial_refund_updates_order_state ... ok
test happy_path_checkout_to_delivered ... ok
How many steps are there from checkout to delivery? Are there assertions at every step, or only on the final state? You can't tell without reading the test code.
testscribe output reads like a domain narrative instead:
| 0.013ms|Given value 4 is added to cache
| -| Then it is equal to 4
| 3.581μs| When key is deleted
| -| Then value is equal to None
| 2.950μs| When value is replaced to 5
| -| Then it is equal to 5
| -| And previous_value is equal to 4
- Models real domain events
- Encourages side-effect driven testing
- Builds test trees naturally from behavior — each test reuses its parent's state, so most test code actually tests something instead of setting the stage
- Makes tests understandable beyond developers
→ Read the full story in motivation
testscribe follows a simple workflow:
- Select a single business action
- Hook into existing state
- Assert in natural language
- Probe what changed
- Expand the test tree
This produces structured, event-driven test trees where each node represents a real domain side effect.
→ Read the full philosophy in foundations
Head over to the testscribe crate for a 2-minute quickstart
and the full user documentation, or explore by example:
- features showcase — compact syntax examples for every feature
- checkout domain — a realistic end-to-end example (Postgres via testcontainers)
| Path | Description |
|---|---|
| crates/testscribe | The main crate users depend on; re-exports everything below and ships the user documentation |
| crates/core | Test tree structure, execution logic and assertion/reporting types |
| crates/proc-macros | The #[testscribe] attribute and ParamDisplay derive |
| crates/standalone | Default test runner, integrates with cargo test; also building blocks for custom runners |
| crates/detached | Experimental remote-controlled test runner |
| examples/ | Example projects (not published) |
Point your agent at llms.md — it defines how agents should write idiomatic testscribe tests. These docs are also shipped inside the published crate, so agents can discover them offline.
This repository is also a Claude Code plugin marketplace hosting the testscribe skill, which triggers automatically whenever tests are written in a project that depends on testscribe:
/plugin marketplace add fraillt/testscribe
/plugin install testscribe@testscribe
See the testscribe crate README for a tool-agnostic AGENTS.md snippet as well.
Issues and pull requests are welcome. If you're proposing a larger change, please open an issue first to discuss the direction.
Licensed under the MIT license.
If you find this project useful or interesting, or just want to say thanks, you can buy me a coffee! Your support keeps me motivated to maintaining and improving this project.