reqnroll-testing
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.
Install with skills.sh (any agent)
npx skills add testland/qa --skill reqnroll-testingreqnroll-testing
Overview
Per reqnroll-home (opens in new window):
"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.'"
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
For SpecFlow-locked legacy projects mid-migration, see specflow-testing.
Worked example
A checkout team adds one BDD scenario, "Apply valid promo," to a new xUnit project.
Step 1 - Install
# 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 filesPer reqnroll-home (opens in new window): "Works across common operating systems and .NET versions (including .NET 8.0)."
Verify: dotnet build succeeds and restores both packages before you author features. If code generation does not run, confirm Reqnroll.Tools.MsBuild.Generation is referenced in the test project.
Step 2 - Author a Feature
# 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 (opens in new window) this is supported.
Step 3 - Step bindings
Write step bindings as [Given/When/Then]-decorated methods in a [Binding] class. Per reqnroll-home (opens in new window): "Supports flexible step definitions using regex or cucumber expressions" - regex is more flexible, cucumber expressions ({int}, {string}, {double}) more readable. Full CartSteps binding class and the cucumber-expression variant: references/bindings-and-hooks.md.
Step 4 - Async support
Per reqnroll-home (opens in new window): "Async step definitions and hooks."
[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
Use [BeforeTestRun], [BeforeScenario] / [AfterScenario], and tag-scoped hooks (e.g. [BeforeScenario("@browser")]) for setup and teardown; wrap each scenario in a transaction and roll back in [AfterScenario] so state does not leak between scenarios. Full hook class: references/bindings-and-hooks.md.
Step 6 - Tags
@critical @regression
Scenario: Apply valid promo
...
@browser @wip
Scenario: New checkout flow
...dotnet test --filter "Category=critical"
dotnet test --filter "Category!=wip"Step 7 - Run
# 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"If a scenario fails or reports an undefined step, fix the matching binding in the [Binding] class and re-run until it turns green.
Step 8 - IDE support
Per reqnroll-home (opens in new window): "IDE support for Visual Studio 2022, VS Code, and Rider."
The Reqnroll plugin enables:
Step 9 - Migrate from SpecFlow
Per reqnroll-home (opens in new window): "Compatible with SpecFlow, allowing quick migration of existing projects."
Migration path:
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
References
Reqnroll step bindings and hooks
View source (opens in new window)Reqnroll step bindings and hooks
Full step-binding and hook examples for reqnroll-testing (opens in new window) (Steps 3 and 5).
Step bindings
// 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 (opens in new window): "Supports flexible step definitions using regex or cucumber expressions." The example uses regex; cucumber expressions are an alternative:
[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.
Hooks
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();
}
}Source
Related skills
acceptance-test-from-criteria
ATDD (Acceptance Test-Driven Development) workflow that generates @AC-N-tagged Gherkin scenarios from a signed-off acceptance-criteria list, scaffolds NotImplementedError step stubs, and produces an AC-to-test traceability table, all before implementation begins, in the team's BDD framework (Cucumber / Behave / Reqnroll). Use when devs are gated on green acceptance tests and failures must map back to a specific criterion. For story-narrative-to-Gherkin without prior ACs, use gherkin-from-stories. For BDD scenario authoring without the ATDD test-first gate, use a general BDD scenario-authoring workflow.
bdd-overview
Teaches behaviour-driven development end to end for a newcomer: what BDD is and how discovery, formulation and automation fit together; a decision table that picks the runner from the project's language and build files (Cucumber-JVM, Cucumber-JS, Cucumber-Ruby, Behave for Python, Reqnroll for .NET, and why SpecFlow is end-of-life); install and first-run commands for each; the declarative-versus-imperative Gherkin discipline with a worked bad-versus-good pair; Background, Scenario Outline and domain-organised step libraries; the traps that make BDD collapse into an expensive UI-automation wrapper; and an honest account of when BDD is not worth adopting. Use when a team is adopting BDD, choosing a Gherkin runner, or a *.feature file needs writing and nobody has settled the conventions.
bdd-step-library-curator
Keeps a BDD step-definition library DRY across a Cucumber / Behave / Reqnroll project - inventories every step definition, detects duplicates (different patterns matching the same intent), recommends canonical consolidations, reorganizes steps by domain, and publishes a step-library README the team greps for "is there already a step for X?" before authoring new ones. Use when a BDD project's step count grows past ~50, on a quarterly step-library review, or when a new engineer cannot find an existing step and is about to write a duplicate.
behave-testing
Configures Behave for Python BDD scenarios - `pip install behave`, authors `.feature` files in Gherkin, writes step implementations in `features/steps/*.py`, configures via `environment.py` for setup/teardown hooks, organizes via tags, runs via `behave`. Use for Python codebases that want Cucumber-family BDD without Cucumber-Ruby / Cucumber-JS.
cucumber-testing
Configures Cucumber for BDD scenarios - Cucumber-JVM (Java/Kotlin via JUnit 5), Cucumber-JS (Node), Cucumber-Ruby. Authors `.feature` files in Gherkin, writes step definitions in the host language, runs via the framework's runner, integrates with JUnit XML reporting. Use when the user mentions Cucumber, Gherkin, `.feature` files, or behavior-driven (BDD) tests in Java, Kotlin, JavaScript, or Ruby, as the canonical wrapper for any of the three official implementations.
gherkin-from-stories
Build-an-X workflow that converts user stories into Gherkin scenarios - extracts the actor / capability / value triple from "As a … I want … so that …", maps acceptance criteria to Scenario blocks, identifies parameterizable axes for Scenario Outlines, and emits a Feature file ready for `bdd-step-library-curator`-curated step definitions. Starts from the story itself rather than from an already-extracted acceptance-criteria list; this skill operates at the user-story layer and produces Gherkin directly. Emits Gherkin only: no step definition stubs and no runner detection. For a full runnable artifact (Feature file plus scaffolded step definitions), follow this skill with step-definition scaffolding for the detected runner. Use when a PM hands over a user story or a backlog of stories and the team's first test artifact is the `.feature` file rather than a separate AC doc.
living-documentation-publisher
Converts passing Cucumber JSON output into stakeholder-facing living documentation: generates HTML reports via multiple-cucumber-html-reporter (Node) or Serenity BDD aggregate (JVM), applies Gherkin tags to drive report sections, and publishes to GitHub/GitLab Pages in CI. Use when BDD scenarios are in use and the team needs an always-current, non-test-engineer-readable document showing which acceptance criteria pass.
manual-step-to-gherkin
Translates an existing manual test step (table row, prose bullet, TestRail/Qase exported step) into a declarative Gherkin Given/When/Then step phrased in business language - strips UI mechanics ("clicks the button", "types in the field"), elevates the user intent ("signs in", "adds the product"), and aligns vocabulary with the project's existing step library. The input is an already-written manual step - not a user story and not an acceptance-criteria list. Use when a team is migrating manual test scripts to BDD, or when a manual tester is handing a script off to an automation engineer.
specflow-testing
Maintains SpecFlow tests on existing .NET projects - authors Gherkin `.feature` files, writes C# `[Binding]` step definitions, runs them via xUnit/NUnit/MsTest, and migrates a project to Reqnroll. SpecFlow is the legacy .NET BDD framework and Reqnroll is its maintained fork. Use only for existing SpecFlow projects, especially mid-migration; new .NET BDD projects use `reqnroll-testing` instead.