Executable BDD Acceptance Tests

Intent#

This extension adds executable scenarios for critical cross-layer examples. A consumer writes them as Reqnroll Gherkin features with C# step definitions or as LightBDD feature classes. The use-case specification remains the authored behavior source.

Activation#

Activation scope: local.

Applicable specification kinds: use-case, journey.

The consumer enables bdd when a critical example needs business-language review and execution through a public system boundary. Routine unit behavior does not activate it.

A consumer selects one runner for the whole suite and follows the provisions below with either runner.

Runner	A scenario is	It proves a Case with	Its business-readable text is
Reqnroll	A Gherkin scenario in a `.feature` file, bound to step definitions	A `proves:` line under the scenario title	The feature file
LightBDD	A C# method on a feature class, whose steps are calls to step methods	A `/// <proves>` tag on the scenario method	The scenario method, the step method names, and the generated report

LightBDD moves the binding from text matching to the compiler. A step that no longer exists or whose parameters changed fails the build rather than the run. A consumer that generates its API client from the published contract extends the same property to every request a step sends.

Baseline relationship#

This extension replaces no baseline provision. It adds an acceptance test project and the manifest-pinned packages of one runner.

This extension switches on case. Its scenarios prove Case records.

Standards#

Select shared critical examples#

ruleguidance

Requirement A test author MUST create a BDD scenario only when business-language form improves shared understanding of cross-layer behavior.

Rationale A selected scenario gives product, domain, engineering, and testing discussions one executable example.

litespec/backend/dotnet/ext/bdd#select-shared-critical-examples

Avoid routine scenario duplication#

ruleguidance

Requirement A test author MUST NOT duplicate every unit or validation case as a scenario.

Rationale Unit and validation tests retain their narrower feedback and failure location.

litespec/backend/dotnet/ext/bdd#avoid-routine-scenario-duplication

Prove a Case from every scenario#

ruleguidance

Requirement Every BDD scenario MUST carry one proves claim naming its Case, with steps calling the proved use case and asserting its Result.

Rationale A Case pairs one situation with the Result it leads to. The claim, the steps, and the assertion together prove it. A LightBDD scenario carries the claim as a /// <proves> tag on the scenario method. A Reqnroll scenario carries it as a proves: line under its title.

Example /// <proves>case/cancel-order.canceling-twice-is-refused</proves> traces a cancellation scenario to its Case.

litespec/backend/dotnet/ext/bdd#prove-a-case-from-every-scenario

Drive public behavior#

ruleguidance

Requirement A BDD step MUST call the HTTP API or another declared public system boundary.

Rationale Public execution proves behavior without depending on implementation details.

litespec/backend/dotnet/ext/bdd#drive-public-behavior

Assert observable outcomes#

ruleguidance

Requirement A BDD scenario MUST assert a response, later read, durable event, audit record, or other observable outcome.

Rationale Observable results show whether the public boundary achieved the expected behavior.

litespec/backend/dotnet/ext/bdd#assert-observable-outcomes

Limit database assertions#

ruleguidance

Requirement A BDD scenario MUST use direct database assertions only for a documented durable boundary.

Rationale An outbox record is one documented durable boundary with meaningful storage evidence.

litespec/backend/dotnet/ext/bdd#limit-database-assertions

Own scenario data#

ruleguidance

Requirement Each BDD scenario MUST own its identifiers, actor context, requests, responses, and expected state.

Rationale Local scenario data prevents accidental dependence on data prepared elsewhere.

litespec/backend/dotnet/ext/bdd#own-scenario-data

Isolate scenario execution#

ruleguidance

Requirement The acceptance suite MUST reset database state between scenarios and avoid scenario-order dependencies.

Rationale Any scenario can then run alone or in a different order.

litespec/backend/dotnet/ext/bdd#isolate-scenario-execution

Translate business phrases#

ruleguidance

Requirement A BDD step definition MUST translate a business phrase into a typed test-driver call.

Rationale The scenario stays business-readable while the driver owns boundary mechanics.

litespec/backend/dotnet/ext/bdd#translate-business-phrases

Exclude production internals#

ruleguidance

Requirement A BDD step definition MUST NOT resolve repositories, handlers, sessions, or the production service provider.

Rationale Internal resolution bypasses the public behavior that the scenario claims to verify.

litespec/backend/dotnet/ext/bdd#exclude-production-internals

Preserve scenario failures#

ruleguidance

Requirement A BDD hook MUST await asynchronous setup and cleanup without replacing the original scenario failure.

Rationale Scenario reset and actor setup need complete execution and useful failure evidence.

litespec/backend/dotnet/ext/bdd#preserve-scenario-failures

Conventions#

Group feature files by module#

conventionguidance

Default Group feature files or feature classes under module folders in Acceptance.Tests.

Replacement A consumer records a departure from this default as an Exception record with reason and review date.

Rationale Module folders align scenarios with the business vocabulary they exercise.

litespec/backend/dotnet/ext/bdd#group-feature-files-by-module

Keep steps vocabulary-scoped#

conventionguidance

Default Keep step definitions narrow and reusable only within one business vocabulary.

Replacement A consumer records a departure from this default as an Exception record with reason and review date.

Rationale Broad generic steps hide business meaning and create unrelated coupling.

litespec/backend/dotnet/ext/bdd#keep-steps-vocabulary-scoped

Limit scenario context#

conventionguidance

Default Store values for one scenario in a scenario context object.

Replacement A consumer records a departure from this default as an Exception record with reason and review date.

Rationale The context is scenario state rather than a service locator.

litespec/backend/dotnet/ext/bdd#limit-scenario-context

Mark pull-request scenarios#

conventionguidance

Default Mark the small pull-request subset separately from the proves claim: a Reqnroll scenario with the @critical tag, a LightBDD scenario with a critical test trait.

Replacement A consumer records a departure from this default as an Exception record with reason and review date.

Rationale The marking selects fast feedback without altering Case proof. @critical names the scenarios whose failure stops a release, and the project records which ones those are. A marking that every scenario carries selects nothing, so the subset has a stated size bound and an owner who keeps it there.

litespec/backend/dotnet/ext/bdd#mark-pull-request-scenarios

Dependencies#

Reqnroll and Reqnroll.xunit.v3, for Gherkin features
LightBDD.XUnit3 with xunit.v3.mtp-v2, for C# feature classes

LightBDD 3.12 builds against xUnit v3 3.2. Its test project therefore runs the 3.2 line, and other test projects run the current one.

Verification#

ID	Mark	Evidence
litespec/backend/dotnet/ext/bdd#select-shared-critical-examples	guidance	Does the scenario give shared discussions one executable cross-layer example?
litespec/backend/dotnet/ext/bdd#avoid-routine-scenario-duplication	guidance	Does the suite leave unit and validation cases to their narrower tests?
litespec/backend/dotnet/ext/bdd#prove-a-case-from-every-scenario	guidance	Does every scenario carry one proves claim for a Case its steps prove?
litespec/backend/dotnet/ext/bdd#drive-public-behavior	guidance	Do all steps call the HTTP API or another declared public boundary?
litespec/backend/dotnet/ext/bdd#assert-observable-outcomes	guidance	Does each scenario assert a response, read, event, record, or other observable outcome?
litespec/backend/dotnet/ext/bdd#limit-database-assertions	guidance	Does each direct database assertion name its documented durable boundary?
litespec/backend/dotnet/ext/bdd#own-scenario-data	guidance	Does each scenario own its identifiers, actor context, requests, responses, and expected state?
litespec/backend/dotnet/ext/bdd#isolate-scenario-execution	guidance	Does the suite reset state between scenarios and avoid order dependence?
litespec/backend/dotnet/ext/bdd#translate-business-phrases	guidance	Do step definitions delegate business phrases to typed driver calls?
litespec/backend/dotnet/ext/bdd#exclude-production-internals	guidance	Is the suite free of Domain repository, handler, session, and provider resolution?
litespec/backend/dotnet/ext/bdd#preserve-scenario-failures	guidance	Do hooks await setup and cleanup without replacing the scenario failure?
litespec/backend/dotnet/ext/bdd#group-feature-files-by-module	guidance	Do feature files follow the module folders or a recorded Exception?
litespec/backend/dotnet/ext/bdd#keep-steps-vocabulary-scoped	guidance	Does each reusable step set serve one business vocabulary or a recorded Exception?
litespec/backend/dotnet/ext/bdd#limit-scenario-context	guidance	Does the scenario context hold state only, or is there a recorded Exception?
litespec/backend/dotnet/ext/bdd#mark-pull-request-scenarios	guidance	Does the pull-request subset stay small, owned, and separate from Case proof?