Reqnroll: .NET BDD Testing Getting Started Guide

Reqnroll is an open-source BDD testing framework for .NET, and a direct community fork of SpecFlow. After SpecFlow's commercial pivot in 2023, the Reqnroll project picked up the codebase, removed the licensing restrictions, and continued active development under the Apache 2.0 license. If you know SpecFlow, Reqnroll will feel identical. If you are new to BDD in .NET, this guide gets you from zero to running tests.

What Reqnroll Is

Reqnroll lets you write executable specifications in Gherkin (the plain-language format using Given, When, Then) and bind those steps to C# methods. The framework handles the wiring between .feature files and test logic. It integrates with NUnit, xUnit, and MSTest as the underlying test runner, so existing CI pipelines that know how to run dotnet test work without changes.

Installing Reqnroll

Create a test project targeting .NET 6 or later:

dotnet new classlib -n MyApp.Specs
cd MyApp.Specs

Add the Reqnroll NuGet packages. Choose the one that matches your runner:

# For NUnit
dotnet add package Reqnroll.NUnit

# For xUnit
dotnet add package Reqnroll.xUnit

# For MSTest
dotnet add package Reqnroll.MsTest

You also need the runner itself:

dotnet add package NUnit
dotnet add package NUnit3TestAdapter
dotnet add package Microsoft.NET.Test.Sdk

Your .csproj should look roughly like this:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <IsPackable>false</IsPackable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
    <PackageReference Include="NUnit" Version="4.1.0" />
    <PackageReference Include="NUnit3TestAdapter" Version="4.5.0" />
    <PackageReference Include="Reqnroll.NUnit" Version="2.1.0" />
  </ItemGroup>
</Project>

Writing a Feature File

Add a .feature file to your project. Make sure the build action is set to None and it copies to the output directory, or simply use the Reqnroll Visual Studio extension which handles this automatically.

# Features/Calculator.feature
Feature: Calculator
  Basic arithmetic operations

  Scenario: Add two numbers
    Given I have entered 50 into the calculator
    And I have entered 70 into the calculator
    When I press add
    Then the result should be 120 on the screen

  Scenario: Subtract numbers
    Given I have entered 100 into the calculator
    And I have entered 35 into the calculator
    When I press subtract
    Then the result should be 65 on the screen

Generating Step Bindings

Reqnroll can generate stub methods for unbound steps. In Visual Studio with the Reqnroll extension installed, right-click a step and select "Go to Step Definition" -- if it does not exist, it offers to generate it.

Manually, a step definition file looks like this:

using Reqnroll;

namespace MyApp.Specs.StepDefinitions;

[Binding]
public class CalculatorStepDefinitions
{
    private readonly List<int> _inputs = new();
    private int _result;

    [Given("I have entered {int} into the calculator")]
    public void GivenIHaveEnteredIntoTheCalculator(int number)
    {
        _inputs.Add(number);
    }

    [When("I press add")]
    public void WhenIPressAdd()
    {
        _result = _inputs.Sum();
    }

    [When("I press subtract")]
    public void WhenIPressSubtract()
    {
        _result = _inputs[0] - _inputs[1];
    }

    [Then("the result should be {int} on the screen")]
    public void ThenTheResultShouldBeOnTheScreen(int expected)
    {
        Assert.That(_result, Is.EqualTo(expected));
    }
}

The {int} placeholder is a Cucumber expression. Reqnroll supports both Cucumber expressions and regular expressions in step attributes.

Running Tests

Standard dotnet test works:

dotnet test

To filter by scenario tag:

dotnet test --filter "Category=smoke"

Tags in Gherkin map directly to test categories:

@smoke
Scenario: Add two numbers
  ...

Scenario Outlines

When you need to run the same scenario with multiple input sets, use Scenario Outline:

Scenario Outline: Add two numbers
  Given I have entered <first> into the calculator
  And I have entered <second> into the calculator
  When I press add
  Then the result should be <result> on the screen

  Examples:
    | first | second | result |
    | 10    | 20     | 30     |
    | 50    | 50     | 100    |
    | 0     | 999    | 999    |

Each row becomes an individual test case in the runner output.

IDE Support

The Reqnroll extension for Visual Studio 2022 provides syntax highlighting for .feature files, step navigation, and stub generation. For Rider and VS Code, the Cucumber plugin handles Gherkin highlighting. Step navigation from feature files to C# definitions works via the Reqnroll language server in supported environments.

Add the Reqnroll.VisualStudio extension from the Visual Studio Marketplace to get the full editing experience.

The most immediate next step after setup is organizing your step definitions by feature area rather than putting everything in one file -- Reqnroll resolves steps globally across all [Binding] classes, so splitting them by domain keeps the project maintainable as coverage grows.