register-referentie/docs/architecture/adr-0004-bdd-framework.md

ADR-0004: Reqnroll as the BDD acceptance framework

• Status: Accepted
• Date: 2026-06-04
• Deciders: Respellion engineering
• Relates to: S-04 (#5); supports CLAUDE.md §3 (BDD at the use-case level) and §11 (tests pyramid)

Context

CLAUDE.md §11 mandates that each user-visible flow is driven by a Gherkin acceptance scenario living in tests/acceptance/, and §3 names "BDD at the use-case level" as a core engineering principle. The foundational slices (S-00…S-03) added no acceptance layer; S-04 is the first slice with real domain behaviour to drive, so it is where the BDD framework is introduced. We need a .NET tool that:

• parses Gherkin .feature files and binds steps to C#,
• integrates with the existing xUnit test runner (the repo standardises on xUnit), so acceptance tests run under the same dotnet test / make ci gate as everything else,
• is actively maintained on modern .NET (we target net10.0).

Decision

Use Reqnroll (Reqnroll.xUnit) for acceptance tests.

• Reqnroll is the actively-maintained, open-source successor to SpecFlow (which is no longer maintained). It keeps the same Gherkin + [Binding] model, so the knowledge transfers.
• Reqnroll.xUnit generates one xUnit test per scenario, so acceptance tests are discovered and run by the same runner as the unit tests — no second test framework, no extra CI step.
• Acceptance projects live under tests/acceptance/ per the PRD §9 layout. Generated *.feature.cs files are build artefacts and are git-ignored.

Consequences

• Positive: one assertion/runner stack (xUnit) across unit and acceptance tests; scenarios are written in business language (Dutch domain terms inline) and reviewed as the slice's contract; maintained tooling on net10.0.
• Cost: a new dependency (Reqnroll.xUnit) and its xUnit v2 transitive graph. Reqnroll pulls xunit.core but not the assertion library, so the xunit metapackage is referenced explicitly to get Assert.
• Replaceable by: hand-written xUnit "scenario" tests with a Given/When/Then helper, at the cost of losing Gherkin as the shared, readable contract — which is the whole point of §3.
• Follow-ups: the real-OpenZaak integration test (Testcontainers) and the Stryker mutation baseline for S-04 are tracked as their own issues split off #5.

Alternatives considered

• SpecFlow — rejected: unmaintained and without an official net10.0 story; Reqnroll is its drop-in successor.
• Plain xUnit Given/When/Then helpers — rejected for user-visible flows: loses the business-readable Gherkin contract that §3/§11 require. Still fine for unit-level tests.
• Xunit.Gherkin.Quick — rejected: lighter but less featureful (no hooks/scoped contexts, smaller community) than Reqnroll.