Executable BDD Acceptance Tests

A scenario costs maintenance on every behavior change, so the suite earns its keep only where business-language form improves shared understanding of cross-layer behavior. Each selected scenario gives product, domain, engineering, and testing discussions one executable example instead of four retellings.

Reviewed forWhich BDD scenarios trace to no cross-layer example the team discusses in business language? Look at each BDD scenario in the acceptance suite.

Marked guidance: a reviewer answers this question.

A unit test fails at the exact rule and runs in milliseconds; the same test duplicated as a BDD scenario fails at a public boundary after a full setup. Duplication slows the suite and moves the failure away from its cause, so routine behavior stays in its narrower tests.

Reviewed forWhich unit or validation tests repeat as a duplicate BDD scenario? Look at the narrower suites beside the acceptance suite.

Marked guidance: a reviewer answers this question.

A scenario pairs one given situation and when action with the then result they lead to, and the proves claim is what ties the BDD scenario to that record. The claim names it, the steps call the proved use case, and the assertion checks its result; without the claim, the model builder cannot tell which scenario the BDD scenario proves. A LightBDD scenario carries the claim as a proves mark on the scenario method, in the style the project declares, and a Reqnroll scenario as a proves: line under its title.

/// <proves>scenario/cancel-order.canceling-twice-is-refused</proves> traces a cancellation BDD scenario to its scenario record.

Reviewed forWhich BDD scenarios lack one proves claim naming their scenario? Look at each BDD scenario in the acceptance suite.

Marked guidance: a reviewer answers this question.

A step that calls the HTTP API or another declared public boundary proves what a caller can observe. A step that reaches past the boundary depends on implementation details, so a refactoring breaks the scenario without breaking the behavior.

Reviewed forWhich step definitions call outside the HTTP API and the declared public boundaries? Look at each step definition in the acceptance suite.

Marked guidance: a reviewer answers this question.

A scenario that runs requests without asserting proves only that nothing threw. Asserting a response, a later read, a durable event, an audit record, or another observable outcome shows the public boundary achieved the expected behavior.

Reviewed forWhich BDD scenarios assert no response, read, event, record, or other observable outcome? Look at each BDD scenario in the acceptance suite.

Marked guidance: a reviewer answers this question.

The database is an implementation detail, so asserting its rows couples the scenario to storage shapes. A direct assertion is allowed only for a documented durable boundary, such as an outbox record, where the stored row is itself the promised evidence.

Reviewed forWhich direct database assertions name no documented durable boundary? Look at each direct database assertion in the acceptance suite.

Marked guidance: a reviewer answers this question.

A scenario that borrows identifiers or state prepared elsewhere breaks when that other setup changes. Owning its identifiers, actor context, requests, responses, and expected state keeps each scenario self-contained and runnable alone.

Reviewed forWhich BDD scenarios borrow identifiers, actor context, requests, responses, or expected state? Look at each BDD scenario in the acceptance suite.

Marked guidance: a reviewer answers this question.

State left by one scenario becomes a hidden precondition of the next, and the suite passes only in one order. Resetting database state between scenarios removes that coupling, so any scenario runs alone or in any order.

Reviewed forWhich scenarios fail alone or in another order, or which runs skip the state reset? Look at the acceptance suite runs.

Marked guidance: a reviewer answers this question.

HTTP calls, JSON shapes, and assertion mechanics in a step definition hide the business phrase the scenario promises. Translating each phrase into a typed test-driver call keeps the scenario readable while the driver owns the boundary mechanics.

Reviewed forWhich step definitions skip the typed test-driver call? Look at each step definition in the acceptance suite.

Marked guidance: a reviewer answers this question.

Resolving a repository, handler, session, or the production service provider runs the behavior without the boundary the scenario claims to verify. The scenario then passes while the public path stays untested, so step definitions resolve none of them.

Reviewed forWhich step definitions resolve a repository, handler, session, or the production service provider? Look at each step definition in the acceptance suite.

Marked guidance: a reviewer answers this question.

Setup and cleanup are asynchronous, and an unawaited hook leaves the next scenario running against a half-reset database. A hook that throws during cleanup can also replace the scenario's own failure, hiding the real cause. Awaiting both without replacing the original failure keeps the evidence trustworthy.

Reviewed forWhich hooks skip awaiting setup or cleanup, or replace the original scenario failure? Look at each hook in the acceptance suite.

Marked guidance: a reviewer answers this question.