reqnroll-testing

reqnroll-testing

Overview

Per reqnroll-home:

"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: "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: "compatible with SpecFlow, allowing quick migration").
• The team needs full Gherkin support including Rule blocks (per reqnroll-home: "Full Gherkin support with tagged Rule blocks").

For SpecFlow-locked legacy projects mid-migration, see specflow-testing.

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 files

Per reqnroll-home: "Works across common operating systems and .NET versions (including .NET 8.0)."

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 this is supported.

Step 3 - 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: "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.

Step 4 - Async support

Per reqnroll-home: "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

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

@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"

Step 8 - IDE support

Per reqnroll-home: "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: "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 - 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.