SpecFlow / Reqnroll review: what it is and how to move to Reqnroll

Reqnroll does not run feature files directly. An MSBuild task runs at build time and generates a code-behind file for each feature, a C# class with one test method per scenario and one per Scenario Outline example, decorated with the attributes of the chosen test framework. NUnit, MSTest, xUnit or TUnit then discovers and runs those methods like any other test. That is why scenarios appear in Test Explorer and dotnet test without a special runner, and why a feature edit needs a build before it runs. From v3.3 the generated files can live in the obj folder, which keeps them out of source control and is planned as the default for v4.

Step definitions are public methods on classes marked [Binding], tagged with [Given], [When] or [Then] and an expression. The expression is either a Cucumber Expression such as the client added {int} pcs of {string}, or a regular expression; Reqnroll decides which by its shape, and anchoring with ^ and $ forces a regex. At run time each scenario step is matched against all bindings in the configured assemblies, so step text is a shared vocabulary across the project, as in Cucumber. Hooks such as [BeforeScenario] and [AfterTestRun] are bindings too, and can be scoped to tags.

Reqnroll includes a small dependency injection container, Reqnroll.BoDi, formerly BoDi in SpecFlow. For each scenario it creates binding class instances and any context classes they ask for in their constructors, and disposes them when the scenario ends. ScenarioContext and FeatureContext are injectable the same way, through their interfaces from v3. Plugins exist for Autofac and Microsoft.Extensions.DependencyInjection when the application’s own container should supply services. Because state lives in per-scenario objects rather than statics, scenarios stay isolated, which is also what makes parallel execution safe.

Reqnroll has no runner of its own: scenarios are ordinary tests in the chosen framework, so parallel execution is therefore whatever the chosen framework provides. NUnit, MSTest and TUnit can run individual scenarios in parallel, while xUnit runs features in parallel with scenarios of one feature on the same thread. Reqnroll isolates each thread’s ScenarioContext, but the binding registry and BeforeTestRun hooks are shared, and the documentation advises against relying on FeatureContext and feature hooks when scenarios of one feature can be spread across threads.

There are two documented paths. The quick one replaces every SpecFlow package with its Reqnroll equivalent and adds Reqnroll.SpecFlowCompatibility, which keeps the TechTalk.SpecFlow namespace and even App.config working; the guide says that for most projects this is the only change. The complete one also replaces TechTalk.SpecFlow with Reqnroll across the code, renames ISpecFlowOutputHelper to IReqnrollOutputHelper, and renames specflow.json to reqnroll.json, where stepAssemblies becomes bindingAssemblies. Remove any CucumberExpressions.SpecFlow packages, since Reqnroll supports Cucumber Expressions natively. Projects still on SpecFlow v3 also inherit the v3 to v4 changes, chiefly that some regex step definitions are now read as Cucumber Expressions. Migrate on a branch, run the suite, and compare scenario counts before and after.

Group bindings by domain concept rather than by feature file, because steps are global and a class per feature encourages near-duplicates. Once a scenario uses several binding classes, share state through a context class declared as a constructor parameter: Reqnroll creates one instance per scenario, gives the same instance to every binding class that asks for it, and disposes it if it implements IDisposable. Avoid ScenarioContext.Current and the other static accessors, which do not work with parallel execution, and inject IScenarioContext instead when you need scenario metadata such as tags.

A Reqnroll pipeline is an ordinary dotnet test run. Enable the HTML formatter, either in reqnroll.json or with the REQNROLL_FORMATTERS_HTML environment variable, so every run produces a single-page report next to the test output, and upload it with the test results whether or not the run fails. Filter scenarios by tag through the test framework’s own filter, since Reqnroll turns tags into categories or traits; with NUnit, dotnet test --filter Category=smoke runs the scenarios tagged @smoke. Run a smoke subset on pull requests and the full suite on main or nightly.

Parallelism is configured in the test framework, not in Reqnroll. With NUnit, an assembly-level Parallelizable attribute with ParallelScope.Fixtures runs features in parallel, and ParallelScope.Children runs individual scenarios. MSTest and TUnit also support scenario-level parallelism; xUnit runs features in parallel. Before enabling it, remove static state, stop using ScenarioContext.Current, and make test data unique per scenario. If some features must not run concurrently, the addNonParallelizableMarkerForTags setting in reqnroll.json marks scenarios with chosen tags as non-parallelisable. Start with feature-level parallelism, which keeps FeatureContext and feature hooks predictable, and move to scenario level only once the suite is clean.

The maintenance problems are the same as Cucumber’s. Write declarative steps about business intent, and push clicks, selectors and HTTP calls into page objects or clients that bindings call. Review new steps against the existing vocabulary so the same idea is not phrased five ways. Use REQNROLL_DRY_RUN=true, added in v3, to check quickly that every step has a binding without executing any code. Keep generated code-behind in the obj folder with ReqnrollUseIntermediateOutputPathForCodeBehind, which v4 is planned to make the default. And watch the deprecations: ScenarioContext.Pending and StepIsPending are deprecated for removal in v4, so throw PendingStepException instead.