Behaviour-driven development · Rust
Agree what should happen. Write it down. Put it to the test.
rstest-bdd connects plain-language Gherkin scenarios to Rust
functions and rstest fixtures. Every scenario becomes
an ordinary test, and cargo test runs it beside the
rest.
The lantern picnic
Clover plans a picnic. Bobbin builds a lantern trolley. Marrow turns their agreement into something all three can check.
Chapter 01 · Shared understanding
A lantern on the trolley. A ring of the bell. An upright lantern at the picnic table. Three pictures make the promise concrete enough to argue about.
Given a lantern on the trolley
When the departure bell rings
Then the lantern arrives upright
Compiled and run against rstest-bdd 0.6.0.
Chapter 02 · Executable steps
Marrow clips the pictures above the route. Bobbin has already built the mechanism. Clover holds the promised result beside the destination.
#[given("a lantern on the trolley")]
fn load(trolley: &mut Trolley) {
trolley.loaded = true;
trolley.upright = true;
}
Compiled and run against rstest-bdd 0.6.0.
Chapter 03 · The existing test runner
A wheel check, a bell check, and a full rehearsal share the familiar bench. Clover brings another stool. Nobody builds an extension.
$ cargo test lantern_delivery
Chapter 04 · Composable fixtures
Marrow opens the props cupboard. Every rehearsal gets its own freshly reset trolley. The bells have their own muffler.
#[fixture]
fn trolley() -> Trolley {
Trolley::default()
}
Compiled and run against rstest-bdd 0.6.0.
Chapter 05 · Explicit example cases
Once with one lantern. Once with two. Once with none. Marrow gives the empty trolley their full attention. It must not acquire a lantern on the way.
Examples:
| count |
| 1 |
| 2 |
| 0 |
Compiled and run against rstest-bdd 0.6.0.
Chapter 06 · Useful failures
The lantern still glows. It also lies on its side. Marrow holds up the original picture. Nearly right is useful information.
assertion failed: trolley.upright Step failed at index 2: Then the lantern arrives upright - Panic in step 'the lantern arrives upright', function 'check': assertion failed: trolley.upright (feature: tests/features/lantern.feature, scenario: Deliver a lantern)
Chapter 07 · Harness adapters
The strap is fixed. The three carry the trolley towards another stage, ready for a fresh rehearsal.
harness = rstest_bdd_harness_tokio::TokioHarness,
Compiled and run against rstest-bdd 0.6.0.
Chapter 08 · A promise kept
The lanterns stand upright. Clover pours, Bobbin unfolds a napkin, and Marrow puts the clipboard down. One piece of shortbread remains unaccounted for.
running 1 test test lantern_delivery ... ok test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
From the story to the test
A feature file describes the behaviour. Attribute macros connect its lines to ordinary functions. One attribute binds the two into a test.
Start here
Three dev-dependencies. The macros live in their own crate, so
a test imports them from rstest_bdd_macros.
[dev-dependencies]
rstest = "0.26.1"
rstest-bdd = "0.6.0"
rstest-bdd-macros = "0.6.0"
Compiled and run against rstest-bdd 0.6.0.
Feature: Lantern delivery
Scenario: Deliver a lantern
Given a lantern on the trolley
When the departure bell rings
Then the lantern arrives upright
Compiled and run against rstest-bdd 0.6.0.
The scenario states an observable result. Rust supplies the implementation and the assertions.
$ cargo test lantern_delivery
The scenario runs as lantern_delivery, beside the
unit and integration tests. Outline rows run as
case_1, case_2, and so on.
//! One scenario bound to three steps, which share a fixture and change it
//! through `&mut`.
use rstest::fixture;
use rstest_bdd_macros::{given, scenario, then, when};
#[derive(Default)]
struct Trolley {
loaded: bool,
arrived: bool,
upright: bool,
}
#[fixture]
fn trolley() -> Trolley {
Trolley::default()
}
#[given("a lantern on the trolley")]
fn load(trolley: &mut Trolley) {
trolley.loaded = true;
trolley.upright = true;
}
#[when("the departure bell rings")]
fn depart(trolley: &mut Trolley) {
trolley.arrived = true;
}
#[then("the lantern arrives upright")]
fn check(trolley: &Trolley) {
assert!(trolley.loaded);
assert!(trolley.arrived);
assert!(trolley.upright);
}
#[scenario(path = "tests/features/lantern.feature", name = "Deliver a lantern")]
fn lantern_delivery(trolley: Trolley) {
let _ = trolley;
}
Compiled and run against rstest-bdd 0.6.0.
A small in-memory model. In an application’s tests the steps
call the real delivery code. Set
trolley.upright = false; in depart to
watch the promise fail.
Notes from the workbench
BDD works when the examples clarify the domain. The plumbing should get out of the way of that conversation.
Unit, integration, and scenario tests draw on the same rstest fixtures. State lives where rstest puts it, not in a framework-mandated World. Reusing a fixture does not mean sharing a mutable one.
Placeholders such as {count:u32} parse through FromStr before the step runs. An Outline repeats a scenario for each row of its Examples table.
Ordinary assertions check the result. A failure names the step, the function, the feature, and the scenario, so the broken promise is one read away.
Bind and filter scenarios
The same rehearsal, a different stage
Harness adapters supply the environment around a scenario. 0.6.0 ships a standard harness, a Tokio harness, and a GPUI harness, and the interface to write another.
The application code still has to suit the stage it is given. A new stage is not a portability spell.
How harnesses workThe honest small print
Not by default. A missing step fails when its scenario runs,
and the failure names the step, the feature, and the
scenario. Enable
rstest-bdd-macros/strict-compile-time-validation
and the same mistake stops the build, provided every step the
scenario uses is defined in the crate being compiled.
When a team wants readable acceptance scenarios and wants to
keep rstest fixtures and cargo test.
cucumber-rs offers its own runner and a World
model; the right choice depends on the suite.
Background, Scenario Outlines with Examples, data tables, docstrings, tags, and keywords in any language Gherkin supports. The repository runs a Japanese household ledger end to end.
Feature files are read and step definitions registered at
compile time, so there is no dynamic step registration. The
* step keyword is not matched. Async scenarios run
on Tokio’s current-thread runtime.
4 · Time for tea
Start with one behaviour that matters. Give it a readable example and a real assertion.
Marrow has put the clipboard down. Please respect this development.