reqnroll-testing · git:20260724.d4db756 · 2026-07-24 · sha256 c59e6ef23691bfa1
reqnroll-testing git:20260724.d4db756A
Immutable. This exact content never changes and is served at /api/v1/blob/c59e6ef23691bfa1.
---
name: reqnroll-testing
description: "Configures Reqnroll (the canonical .NET BDD framework) - install via `dotnet add package Reqnroll`, author `.feature` files in Gherkin, write step bindings as `[Given/When/Then]`-decorated methods in any C# class, runs via `dotnet test`. Reqnroll is the SpecFlow successor (originated as a community port off the SpecFlow codebase); new .NET BDD work targets Reqnroll. Use for .NET projects starting BDD or migrating from SpecFlow."
---
# reqnroll-testing
## Overview
Per [reqnroll-home][rh]:
[rh]: https://reqnroll.net/
> "**Reqnroll** is described as 'an open-source Cucumber-style BDD
> test automation framework for .NET. It has been created as a
> reboot of the SpecFlow project.'"
Per [reqnroll-home][rh]: "Compatible with SpecFlow, allowing quick
migration of existing projects."
The "reboot" framing is the key: SpecFlow's maintenance slowed in
2023; the community forked into Reqnroll, which has continued
active development.
## When to use
- A new .NET project starts BDD - pick Reqnroll over SpecFlow.
- An existing SpecFlow project plans to migrate (per
[reqnroll-home][rh]: "compatible with SpecFlow, allowing quick
migration").
- The team needs full Gherkin support including Rule blocks
(per [reqnroll-home][rh]: "Full Gherkin support with tagged
Rule blocks").
For SpecFlow-locked legacy projects mid-migration, see
`specflow-testing`.
## Step 1 - Install
```bash
# In the test project directory
dotnet add package Reqnroll.xUnit # or Reqnroll.NUnit / Reqnroll.MsTest
dotnet add package Reqnroll.Tools.MsBuild.Generation # generates code from .feature files
```
Per [reqnroll-home][rh]: "Works across common operating systems
and .NET versions (including .NET 8.0)."
## Step 2 - Author a Feature
```gherkin
# Features/Cart.feature
Feature: Apply promo code at checkout
Background:
Given a logged-in user with email confirmed
And the cart contains 1 of "BOOK-001" at $24.99
Rule: Promo codes apply only when valid
Scenario: Apply valid promo
When I enter "WELCOME10" in the promo input
And I click "Apply"
Then the subtotal updates to $22.49
Scenario Outline: Reject invalid codes
When I enter "<code>" in the promo input
And I click "Apply"
Then an error appears: "<error>"
Examples:
| code | error |
| EXPIRED50 | This code has expired |
| NOTREAL | Code not found |
```
`Rule:` blocks (Gherkin 6+) group related scenarios; per
[reqnroll-home][rh] this is supported.
## Step 3 - Step bindings
```csharp
// Steps/CartSteps.cs
using Reqnroll;
using Xunit;
[Binding]
public class CartSteps
{
private CheckoutPage _page;
private Cart _cart;
[Given("a logged-in user with email confirmed")]
public async Task GivenLoggedInUser()
{
var user = await TestUsers.LoggedInWithEmailConfirmed();
_page = new CheckoutPage(user);
}
[Given(@"the cart contains (\d+) of ""([^""]*)"" at \$(\d+\.\d+)")]
public void GivenCartContains(int qty, string sku, decimal price)
{
_cart = new Cart();
_cart.AddItem(new Item(sku, qty, price));
_page.SetCart(_cart);
}
[When(@"I enter ""([^""]*)"" in the promo input")]
public async Task WhenIEnter(string code)
{
await _page.EnterPromoAsync(code);
}
[When(@"I click ""([^""]*)""")]
public async Task WhenIClick(string label)
{
await _page.ClickAsync(label);
}
[Then(@"the subtotal updates to \$(\d+\.\d+)")]
public void ThenSubtotalUpdates(decimal expected)
{
Assert.Equal(expected, _page.GetSubtotal(), 2);
}
}
```
Per [reqnroll-home][rh]: "Supports flexible step definitions using
regex or cucumber expressions." The example uses regex; cucumber
expressions are an alternative:
```csharp
[Given("the cart contains {int} of {string} at ${double}")]
public void GivenCartContains(int qty, string sku, double price) { ... }
```
Cucumber expressions are more readable; regex is more flexible.
## Step 4 - Async support
Per [reqnroll-home][rh]: "Async step definitions and hooks."
```csharp
[Then("the order arrives within (\\d+) minutes")]
public async Task ThenOrderArrives(int minutes)
{
await EmailInbox.WaitForOrderConfirmation(TimeSpan.FromMinutes(minutes));
}
```
`async Task` step methods work transparently; no special config.
## Step 5 - Hooks
```csharp
using Reqnroll;
[Binding]
public class TestHooks
{
[BeforeTestRun]
public static async Task BeforeTestRun()
{
// Once per test run
await TestDatabase.Initialize();
}
[BeforeScenario]
public async Task BeforeScenario()
{
// Per-scenario
await TestDatabase.StartTransaction();
}
[AfterScenario]
public async Task AfterScenario(ScenarioContext context)
{
await TestDatabase.Rollback();
if (context.TestError is not null)
{
await ScreenshotCapture.Capture(context.ScenarioInfo.Title);
}
}
[BeforeScenario("@browser")]
public async Task BeforeBrowserScenario()
{
// Tag-scoped hook
await Browser.LaunchAsync();
}
}
```
## Step 6 - Tags
```gherkin
@critical @regression
Scenario: Apply valid promo
...
@browser @wip
Scenario: New checkout flow
...
```
```bash
dotnet test --filter "Category=critical"
dotnet test --filter "Category!=wip"
```
## Step 7 - Run
```bash
# All tests
dotnet test
# Specific feature
dotnet test --filter "FullyQualifiedName~Cart"
# Generate JUnit XML for CI
dotnet test --logger "junit;LogFilePath=reports/test-results.xml"
```
## Step 8 - IDE support
Per [reqnroll-home][rh]: "IDE support for Visual Studio 2022, VS
Code, and Rider."
The Reqnroll plugin enables:
- Step navigation (Gherkin → step binding).
- Scaffolding (auto-generate step from undefined Gherkin line).
- Run/debug per-scenario.
## Step 9 - Migrate from SpecFlow
Per [reqnroll-home][rh]: "Compatible with SpecFlow, allowing quick
migration of existing projects."
Migration path:
1. Replace `SpecFlow.*` NuGet packages with `Reqnroll.*` equivalents.
2. Update `using SpecFlow` → `using Reqnroll` (single find/replace).
3. Update `[Binding]` (compatible) and step decorators (mostly
compatible).
4. Run tests; fix any compatibility issues.
Most SpecFlow projects migrate in <1 day for typical scope.
## Anti-patterns
| Anti-pattern | Why it fails | Fix |
|-----------------------------------------------------------------------|---------------------------------------------------------------------------|-----|
| Starting new .NET BDD with SpecFlow in 2026+ | SpecFlow's maintenance has slowed; Reqnroll is the active fork. | Pick Reqnroll (Step 1). |
| Mixing SpecFlow + Reqnroll in one solution | Two BDD runners; double maintenance. | Migrate everything (Step 9). |
| Regex-only steps when cucumber expressions would work | Less readable; harder to maintain. | Cucumber expressions for typical cases (Step 3). |
| No `[BeforeScenario]` cleanup | State leaks between scenarios. | Per-scenario hook + transaction rollback (Step 5). |
| Sync step methods that block on async | Deadlocks in xUnit / NUnit / MsTest. | `async Task` step methods (Step 4). |
## Limitations
- **Newer than SpecFlow.** Some third-party SpecFlow plugins
haven't been ported yet.
- **Per-test-framework variant.** xUnit / NUnit / MsTest each have
their own Reqnroll package; pin matching versions.
- **Gherkin parser quirks.** Some edge cases differ between
Reqnroll and Cucumber-JVM; cross-port scenarios need verification.
## References
- [rh][rh] - Reqnroll overview: SpecFlow reboot, Gherkin Rule
blocks, SpecFlow-compatible migration, async hooks, IDE support
(VS / VS Code / Rider).
- `specflow-testing` - legacy
SpecFlow support skill.
- `cucumber-testing`,
`behave-testing` - sibling language
wrappers.
- `bdd-step-library-curator` - addresses step proliferation.