SpecFlow Tutorial for .NET Test Automation: Gherkin, Step Definitions, and Reqnroll

SpecFlow-style .NET automation turns behavior written in Gherkin into executable tests. For a new project, the practical current route is Reqnroll, which describes itself as an open-source Cucumber-style BDD framework and a reboot of SpecFlow. Use its current quickstart for exact package IDs and versions; use its migration guide when maintaining an existing SpecFlow suite. This tutorial explains the workflow and the decisions to make without assuming every legacy project migrates unchanged.

How SpecFlow-style behavior-driven testing works

Behavior-driven development (BDD) connects a requirement, a readable example of expected behavior, and an automated test. A feature file records the example in Gherkin; step definitions bind its phrases to code that exercises the application. Reqnroll describes Gherkin feature files as executable specifications. Its overview covers the framework’s concepts and supported integrations.

#	Preview	Product	Price
1		Selenium Testing Tools Cookbook - Second Edition	$28.24	Buy on Amazon

As an Amazon Associate I earn from qualifying purchases.

Given-When-Then gives each scenario a useful shape:

• Given establishes the starting state or context.
• When describes the action being tested.
• Then states an observable outcome that can be asserted.

For example, a small requirement might be: a signed-in shopper can add an available item to a basket and see the updated count.

#1 Best Overall

Sale

Selenium Testing Tools Cookbook - Second Edition

$28.24

Buy on Amazon

Feature: Shopping basket
  A shopper can add an available item to their basket

  Scenario: Add one item
    Given a shopper has an empty basket
    When the shopper adds an available item
    Then the basket contains 1 item

The scenario should describe behavior a user or business stakeholder can understand, while the eventual step implementation interacts with the application’s real interfaces or a deliberate test fixture.

Choose the .NET test integration and runner

Reqnroll’s overview lists MsTest, NUnit, and xUnit integrations. The choice of test framework is separate from the test platform: the framework supplies the test model and APIs, while the platform runs tests and connects them to command-line, IDE, and CI workflows. Microsoft explains those distinctions in its .NET testing overview.

Prefer the framework already used by the project unless there is a concrete reason to change. Before installing anything, confirm the Reqnroll integration package and versions in the current quickstart for the chosen framework and target .NET version. The Visual Studio Marketplace listing also names TUnit, but consult the current framework-specific documentation for its setup rather than assuming the same package arrangement applies to every integration. The extension listing describes its IDE availability.

Reqnroll states support for Windows, Linux, and macOS, and for .NET Framework 4.6.2+ and .NET 8.0. Those project-level statements are not a guarantee for every integration/package combination, so verify the current documentation against your target framework. For runner choice, start with the selected framework’s documented default. Microsoft’s platform guidance notes that native Microsoft.Testing.Platform (MTP) mode for dotnet test is available with the .NET 10 SDK and later. It also says not to mix VSTest-based and MTP-based projects in one solution or run configuration; keep project and CI configuration consistent. See the current MTP overview and test-platform comparison.

Create a project and add a feature

For an existing application, add the BDD test project alongside the application and select the Reqnroll integration documented for its test framework. For a new project, create a test project using the framework’s current .NET template or documented setup. Package identifiers and versions can change; use the current Reqnroll quickstart rather than copying historical SpecFlow package commands.

1. Create or select the .NET test project and choose its test framework.
2. Install the matching Reqnroll integration package and any framework-specific adapter or runner packages the quickstart requires.
3. Add a feature file, for example Features/Basket.feature, containing the Gherkin scenario.
4. Add step definitions in the test project and implement them using the application boundary or fixture under test.
5. Build and run the test project; confirm the scenario is discovered by the selected runner.

Older SpecFlow teaching material documents a package-per-test-framework model, which helps explain why the integration matters, but its 2021 setup instructions should not be treated as current package guidance. The historical lesson slides provide that context.

Write focused, reusable step definitions

A step definition binds a Gherkin phrase to code. Reqnroll supports regular-expression or cucumber-expression definitions and asynchronous steps and hooks, according to its official overview. Keep bindings focused on domain actions and outcomes rather than making each binding a large UI script. Share setup through clear helpers or hooks when that makes scenarios easier to read, and avoid hidden state that makes one scenario depend on another.

This illustrative C# binding shows the shape of the implementation. It assumes the test project provides an application-specific Basket fixture with the indicated members; replace that fixture with the real service, API, or UI boundary your test is meant to exercise. The exact attributes and binding syntax should match the Reqnroll integration and version you install.

using Reqnroll;
using Xunit;

[Binding]
public sealed class BasketSteps
{
    private readonly Basket _basket = new();

    [Given("a shopper has an empty basket")]
    public void GivenAnEmptyBasket()
    {
        _basket.Clear();
    }

    [When("the shopper adds an available item")]
    public void WhenAnAvailableItemIsAdded()
    {
        _basket.Add(new Item("SKU-1", available: true));
    }

    [Then("the basket contains {int} item")]
    public void ThenTheBasketContains(int expectedCount)
    {
        Assert.Equal(expectedCount, _basket.Count);
    }
}

The using Xunit and assertion above are illustrative of an xUnit-based project; use the assertion API belonging to your selected framework. A production binding should obtain application dependencies through the project’s normal test setup instead of constructing a fake application object unless the test is intentionally isolated.

Run scenarios locally and in CI

Microsoft documents dotnet test as the standard command-line route for .NET test projects, alongside test execution in IDEs. Once the framework, runner, and Reqnroll packages are configured, run from the repository root:

dotnet restore
dotnet build
dotnet test

For a particular project, pass its project file to each command, for example dotnet test tests/Store.BddTests/Store.BddTests.csproj. Use the same SDK, package restore inputs, test platform, and relevant environment configuration locally and in CI. A minimal CI job should restore, build, then test the same solution or project that developers run locally; preserve test output and logs so discovery and execution failures can be diagnosed.

Use the IDE test explorer for interactive discovery and debugging, but treat the repository’s documented CLI command as the reproducible baseline. If adopting MTP native dotnet test mode, check the SDK and platform-specific setup in Microsoft’s current documentation and ensure the rest of the solution and run configuration are not VSTest-based.

Migrate an existing SpecFlow suite to Reqnroll

Reqnroll identifies itself as a reboot of SpecFlow and emphasizes compatibility and migration support. Start with its migration documentation and follow the steps for the suite’s actual framework, configuration, and target framework. Do not assume a package swap alone is sufficient or that every legacy project migrates without code changes.

1. Record the current target frameworks, test framework, runner/platform, package references, configuration files, hooks, and custom tooling.
2. Follow the current Reqnroll migration guide to update package references and configuration for the selected integration.
3. Restore packages and build before changing test behavior; resolve compile errors against the migration documentation.
4. Confirm feature scenarios are generated or discovered, then run a representative scenario and the full suite.
5. Run the same commands and configuration in CI, checking logs for runner or discovery differences.

The NuGet listing for SpecFlow 3.9.74 identifies a package version, but a package listing does not establish ongoing maintenance or vendor support terms. The available official project information here also does not establish a definitive SpecFlow end-of-support date. See the listing for package details, and use Reqnroll’s current migration resources for present-day project guidance.

Troubleshoot common setup problems

Package or framework mismatch

Symptom: restore errors, compile failures, or test host failures after adding packages. Cause: the Reqnroll integration, test framework, adapter, target framework, or SDK versions do not match. Fix: compare the project’s package references and target framework with the current integration quickstart; remove incompatible or duplicate runner packages, then restore and build again.

Feature scenarios are not discovered

Symptom: the project builds, but the IDE or dotnet test reports no tests. Cause: the feature file may not be included/configured for the integration, or the test runner adapter/platform is missing or inconsistent. Fix: verify the feature file’s project inclusion and generation/discovery setup, then check the selected framework’s current Reqnroll package and runner instructions. Compare IDE and CLI execution to identify whether the problem is discovery configuration or the feature itself.

A step is unbound

Symptom: a scenario reports an undefined step. Cause: no binding matches the Gherkin wording, or the binding is not compiled into the test project. Fix: check punctuation, parameter patterns, binding assembly inclusion, and the integration’s expression syntax. Keep the feature wording stable and make the binding match its intent.

Tests behave differently locally and in CI

Symptom: scenarios run in one environment but not another, or test execution differs between IDE and command line. Cause: SDK, runner, platform, configuration, or environment differences. Fix: align the project’s documented CLI command and CI configuration, and keep platform selection consistent across the solution. In particular, Microsoft’s guidance says not to combine VSTest-based and MTP-based projects in one solution or run configuration.

Or skip the browser setup

If a scenario needs a website screenshot as test evidence, you can capture it yourself with a browser automation setup or make a single API request instead. ScreenshotNeo is a website screenshot API and MCP server. This cURL request saves a WebP capture; see the API documentation for options and response details.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

• It accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off.
• Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status.
• An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients.
• The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.

Sign up for 1,000 free screenshots a month, with no card required.

Frequently Asked Questions

Can I still use a SpecFlow project?

The available package listing identifies SpecFlow 3.9.74 but does not establish current maintenance or support terms. For current setup or migration guidance, consult Reqnroll’s documentation and evaluate the requirements of your specific legacy project.

Does Reqnroll support TUnit?

Its Visual Studio Marketplace listing names TUnit, while the overview lists MsTest, NUnit, and xUnit. Check the current Reqnroll documentation for the package and setup applicable to TUnit.

Quick Recap

SaleBestseller No. 1

Selenium Testing Tools Cookbook - Second Edition

$28.24

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.