# cargo-bdd
*Where Rustaceans send their step library for a health inspection.*
> **TL;DR**: `cargo bdd` is the nosy cousin of `rstest-bdd`. It builds every
> test target with `cargo test --no-run`, reruns the binaries with
> `RSTEST_BDD_DUMP_STEPS=1 --dump-steps`, and reports what your steps get up to.
## Why this subcommand?
- **Keep scenarios honest**: compare what the feature files promise with what
the registry actually exposes.
- **Sniff out dead vines**: `unused` highlights steps that never executed during
that run so you can prune them before they rot.
- **Spot copy-pasta**: `duplicates` groups identical keyword+pattern pairs so
you can refactor instead of playing whack-a-mole.
- **Stay inside `cargo`**: no bespoke runner, no sidecar daemon—just another
subcommand that speaks the same toolchain dialect as the rest of your tests.
Think of it as the kitchen inspector for your courgette-driven development
setup: it will politely tap every saucepan and make sure no scenario is serving
mouldy leftovers.
## Commands on the menu
- `cargo bdd steps` — prints every registered step with its keyword, pattern,
and source location.
- `cargo bdd unused` — lists steps flagged `used = false` in that same process
execution.
- `cargo bdd duplicates` — groups definitions that share both keyword and
pattern, separating each duplicate set with `---`.
The user’s guide showcases invocations such as `cargo bdd unused --quiet` and
`cargo bdd duplicates --json`. Follow your local appetite for formatting when
consuming the raw output.
## How it raids your step stash
1. Ask Cargo for metadata, then build each workspace test target with
`cargo test --no-run --message-format=json --all-features`.
2. Collect every compiled test binary path from the JSON stream.
3. For each binary, run it with `RSTEST_BDD_DUMP_STEPS=1 --dump-steps` to make
it spill a JSON inventory of registered steps.
4. Stitch the responses together and apply whichever subcommand filter you
requested.
Any binary that crashes without recognising `--dump-steps` is politely skipped
(the tool assumes it simply is not an `rstest-bdd` test). Binaries that fail
for other reasons cause the subcommand to error, so you still notice genuinely
broken builds.
## Practical rituals
- Run behavioural tests first if you want accurate `unused` results—the flag is
per-process, so only steps exercised during that diagnostic run count as
“used”.
- Keep `#[scenario]` tests compiling even when you are mid-refactor; the
subcommand leans on `cargo test --no-run`, so red builds mean no diagnostics.
- Pair the tool with CI to catch stale steps: dumping the registry into
artefacts makes it easier to review churn alongside feature changes.
- When the JSON output looks crowded, pipe it into your formatter of choice or
reach for the options highlighted in the user’s guide.
## Troubleshooting
- **“Unknown option '--dump-steps'”** — the binary was not built with
`rstest-bdd` instrumentation; the tool shrugs and moves on.
- **“cargo test failed … skipping”** — the target failed to compile or link.
Fix the test crate before expecting step diagnostics.
- **Empty output** — either the workspace exposes no test targets, or every
target ignored the dump flag. Double-check you imported `rstest-bdd` in the
crate you are probing.
## Further reading
For deeper lore—including how fixtures bind to steps, why the registry cares
about `used`, and the philosophy behind keeping BDD inside the Rust testing
stack—curl up with `docs/users-guide.md`.
Now go forth, interrogate your steps, and may every duplicate be composted into
fresh behaviour.