SpecFlow to Reqnroll migration (2026)

TL;DR

Migrate in a small branch: capture a green baseline, replace SpecFlow NuGet packages with matching Reqnroll integrations, rename configuration where needed, regenerate code, and run the same scenarios locally and in CI. Keep feature text and step behavior unchanged until the runner transition is proven.

Key Takeaways

• Capture scenario counts and test evidence before changing packages.
• Migrate one representative project before the full solution.
• Keep feature text and binding behavior stable during the tool transition.
• Verify hooks, dependency injection, tags, reports, and CI separately.
• Remove every direct and transitive SpecFlow dependency after parity.
• Keep a rollback path until repeated Reqnroll runs are trustworthy.

SpecFlow to Reqnroll migration is best approached as an engineering problem with explicit boundaries, fast feedback, and evidence that the result works. A safe migration preserves executable behavior while replacing the unmaintained SpecFlow toolchain with the actively maintained, largely compatible Reqnroll ecosystem. The lowest-risk plan separates package and configuration changes from later refactoring.

This guide turns that goal into a repeatable workflow. It favors maintainable design, observable failures, and examples a working QA or SDET team can adapt without depending on hidden conventions.

TL;DR

Migrate in a small branch: capture a green baseline, replace SpecFlow NuGet packages with matching Reqnroll integrations, rename configuration where needed, regenerate code, and run the same scenarios locally and in CI. Keep feature text and step behavior unchanged until the runner transition is proven.

1. Why Teams Are Moving from SpecFlow to Reqnroll

Reqnroll is an open-source BDD framework for .NET that continues the familiar Gherkin, binding, hook, and runner model. A migration is therefore usually a toolchain replacement rather than a rewrite of business scenarios. That distinction matters: feature files describe behavior and should remain stable while packages, generated code, configuration, and adapters change underneath them.

Begin by stating the objective in operational terms. The new project must discover the same intended scenarios, execute equivalent hooks and bindings, produce usable test results, and behave the same under tags and filters. Do not combine this work with rewriting every scenario or introducing a new assertion library. Those changes hide migration defects in a much larger diff.

The strongest reason to migrate is maintainability. Teams need compatible packages for supported .NET and test platforms, a documented path for issues, and a community that can respond to ecosystem changes. Read the BDD test design guide before changing feature language, but postpone those edits until the runner is stable.

Practice this migration stage on the pilot project before applying it solution-wide. Capture the command, package graph, discovery count, relevant log excerpt, and expected artifact in a short evidence note. Then force one controlled failure related to why teams are moving from specflow to reqnroll and verify that the new runner makes the problem diagnosable. Compare the evidence with the SpecFlow baseline instead of relying on memory. If results differ, classify the difference as intended, compatible, or blocking and assign an owner. This discipline keeps the SpecFlow to Reqnroll migration auditable and prevents a green summary from hiding missing scenarios or broken operational behavior.

2. Inventory the Existing SpecFlow Suite

Create an inventory before editing project files. Record target frameworks, test runner, SpecFlow packages and versions, plugins, generator settings, configuration files, custom dependencies, tag filters, parallelization, and CI commands. Search for SpecFlow namespaces in production and test code because helper libraries can contain binding attributes or runtime abstractions outside the obvious project.

Capture a green baseline with exact scenario totals: discovered, passed, failed, skipped, and pending. Save representative console output and test result files. If the existing suite is not green, classify known failures and make the acceptance criterion equivalence rather than perfection. A migration cannot responsibly claim to fix unrelated flaky tests.

Pay special attention to custom plugins and generator packages. Core APIs have a compatibility path, but third-party plugins may require a Reqnroll build or replacement. List each extension with an owner and disposition: migrate, replace, remove, or temporarily block. This ledger turns surprises into explicit decisions.

Practice this migration stage on the pilot project before applying it solution-wide. Capture the command, package graph, discovery count, relevant log excerpt, and expected artifact in a short evidence note. Then force one controlled failure related to inventory the existing specflow suite and verify that the new runner makes the problem diagnosable. Compare the evidence with the SpecFlow baseline instead of relying on memory. If results differ, classify the difference as intended, compatible, or blocking and assign an owner. This discipline keeps the SpecFlow to Reqnroll migration auditable and prevents a green summary from hiding missing scenarios or broken operational behavior.

3. Create a Safe Migration Branch and Baseline

Use a short-lived branch and keep the first commit mechanical. Restore from a clean package cache when practical, build the solution, and execute tests using the same command CI uses. Commit or archive only relevant test evidence, never generated secrets or machine-specific output.

Select a pilot project that exercises hooks, tables, scenario outlines, dependency injection, tags, and at least one external integration. A tiny smoke project may pass while missing the difficult surfaces. Conversely, migrating the entire solution at once makes package conflicts and discovery failures harder to isolate.

Define rollback before starting. The old branch and pipeline should remain available until the Reqnroll job has produced several trusted runs. Parallel execution for a brief validation window is useful, but avoid keeping two frameworks indefinitely because scenarios and bindings will drift.

Practice this migration stage on the pilot project before applying it solution-wide. Capture the command, package graph, discovery count, relevant log excerpt, and expected artifact in a short evidence note. Then force one controlled failure related to create a safe migration branch and baseline and verify that the new runner makes the problem diagnosable. Compare the evidence with the SpecFlow baseline instead of relying on memory. If results differ, classify the difference as intended, compatible, or blocking and assign an owner. This discipline keeps the SpecFlow to Reqnroll migration auditable and prevents a green summary from hiding missing scenarios or broken operational behavior.

4. Replace NuGet Packages Deliberately

Remove SpecFlow packages and add the Reqnroll equivalents appropriate to the chosen test framework. For NUnit, a typical project uses Reqnroll.NUnit; other runners have their own integration packages. Reqnroll.Tools.MsBuild.Generation supports build-time feature code generation when that model is required. Check the official package documentation for the versions compatible with the repository target framework rather than copying an arbitrary version from a blog.

A minimal SDK-style NUnit project can use package references like the following. Version placeholders are intentional because package versions change; central package management or the repository dependency policy should supply approved versions.

Inspect transitive dependencies after restore. A stale SpecFlow package can remain through a plugin and create ambiguous assemblies or attributes. Use dotnet list package --include-transitive and search lock files. The migration commit should make the ownership of every BDD package obvious.

Practice this migration stage on the pilot project before applying it solution-wide. Capture the command, package graph, discovery count, relevant log excerpt, and expected artifact in a short evidence note. Then force one controlled failure related to replace nuget packages deliberately and verify that the new runner makes the problem diagnosable. Compare the evidence with the SpecFlow baseline instead of relying on memory. If results differ, classify the difference as intended, compatible, or blocking and assign an owner. This discipline keeps the SpecFlow to Reqnroll migration auditable and prevents a green summary from hiding missing scenarios or broken operational behavior.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <IsPackable>false</IsPackable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" />
    <PackageReference Include="NUnit" />
    <PackageReference Include="NUnit3TestAdapter" />
    <PackageReference Include="Reqnroll.NUnit" />
    <PackageReference Include="Reqnroll.Tools.MsBuild.Generation" />
  </ItemGroup>
</Project>

5. Update Namespaces, Configuration, and Generation

Replace SpecFlow namespaces with Reqnroll namespaces where the compatibility guidance requires it. Binding classes commonly move from TechTalk.SpecFlow to Reqnroll. Keep attributes such as Binding, Given, When, Then, BeforeScenario, and AfterScenario semantically unchanged. Compile after namespace changes before modifying binding logic.

Rename or translate configuration using the supported Reqnroll configuration format. Preserve culture, binding culture, trace settings, missing or obsolete behavior, and runtime dependencies that affect results. Do not paste every legacy key without checking support. Configuration that is silently ignored is more dangerous than configuration that fails loudly.

Delete stale generated feature code only when the selected generation model will recreate it. Then run dotnet clean, restore, and build. Confirm generated artifacts are not duplicated and that IDE discovery agrees with command-line discovery. The scalable automation framework structure guide explains why generated output and source ownership should stay separate.

Practice this migration stage on the pilot project before applying it solution-wide. Capture the command, package graph, discovery count, relevant log excerpt, and expected artifact in a short evidence note. Then force one controlled failure related to update namespaces, configuration, and generation and verify that the new runner makes the problem diagnosable. Compare the evidence with the SpecFlow baseline instead of relying on memory. If results differ, classify the difference as intended, compatible, or blocking and assign an owner. This discipline keeps the SpecFlow to Reqnroll migration auditable and prevents a green summary from hiding missing scenarios or broken operational behavior.

6. Verify Bindings, Hooks, Context, and Dependency Injection

Compile errors reveal namespace and API differences, but passing compilation does not prove equivalent lifecycle behavior. Run scenarios that exercise constructor injection, ScenarioContext or FeatureContext access, scoped services, ordered hooks, asynchronous steps, transformations, and table conversion. Verify hook order from observable logs rather than memory.

Avoid service-locator access to context when constructor injection is available. Explicit dependencies make scope and test isolation easier to reason about. If legacy code stores scenario state in static fields, the migration is a good time to document the risk, but fix it in a later commit unless it blocks correct execution.

Check async methods carefully. Step definitions should return Task and await operations instead of using async void or blocking with Result. A runner transition can expose deadlocks or swallowed exceptions that the old environment happened not to reveal. Preserve business assertions while correcting only objectively unsafe execution mechanics.

Practice this migration stage on the pilot project before applying it solution-wide. Capture the command, package graph, discovery count, relevant log excerpt, and expected artifact in a short evidence note. Then force one controlled failure related to verify bindings, hooks, context, and dependency injection and verify that the new runner makes the problem diagnosable. Compare the evidence with the SpecFlow baseline instead of relying on memory. If results differ, classify the difference as intended, compatible, or blocking and assign an owner. This discipline keeps the SpecFlow to Reqnroll migration auditable and prevents a green summary from hiding missing scenarios or broken operational behavior.

using NUnit.Framework;
using Reqnroll;

[Binding]
public sealed class CalculatorSteps
{
    private readonly ScenarioContext _context;

    public CalculatorSteps(ScenarioContext context) => _context = context;

    [Given("the first number is {int}")]
    public void GivenFirstNumber(int value) => _context["first"] = value;

    [When("I add {int}")]
    public void WhenIAdd(int value) => _context["result"] = (int)_context["first"] + value;

    [Then("the result is {int}")]
    public void ThenResultIs(int expected) => Assert.That(_context["result"], Is.EqualTo(expected));
}

7. Validate Tags, Filters, Reports, and CI

Test discovery is the first CI gate. Compare expected scenario counts by assembly and category, not only the final pass percentage. Scenario outlines expand into multiple test cases, so document whether baseline counts refer to examples or scenario definitions. Verify ignored, pending, and undefined scenarios explicitly.

Translate runner filters and pipeline commands without changing their intent. Tags may surface as test categories differently across adapters. Exercise the exact include and exclude expressions used for smoke, regression, and quarantined tests. Confirm test result paths, attachment collection, screenshots, logs, and report publishing still work when a scenario fails.

Run on the same operating systems and containers used in production CI. A local IDE pass can mask case-sensitive paths, missing globalization data, or adapter differences. For broader pipeline design, see the CI testing strategy for automation.

Practice this migration stage on the pilot project before applying it solution-wide. Capture the command, package graph, discovery count, relevant log excerpt, and expected artifact in a short evidence note. Then force one controlled failure related to validate tags, filters, reports, and ci and verify that the new runner makes the problem diagnosable. Compare the evidence with the SpecFlow baseline instead of relying on memory. If results differ, classify the difference as intended, compatible, or blocking and assign an owner. This discipline keeps the SpecFlow to Reqnroll migration auditable and prevents a green summary from hiding missing scenarios or broken operational behavior.

8. Roll Out in Stages and Remove Legacy Debt

After the pilot is stable, migrate remaining projects in small groups. Central package management can enforce a consistent Reqnroll version, but introduce it only if the repository already uses that model or as a separately reviewed improvement. Each batch should show package diff, discovery comparison, execution result, and any approved exception.

Remove SpecFlow configuration, packages, plugins, build targets, and documentation only after searches prove they are unused. Update onboarding instructions, IDE recommendations, CI images, troubleshooting pages, and ownership records. A stale README can cause developers to reinstall old extensions and generate misleading failures.

Close the migration with a lightweight architectural decision record. Include why Reqnroll was chosen, the supported runner, configuration location, package update policy, and how to run targeted tags. This small artifact prevents future contributors from reconstructing key decisions from package history.

Practice this migration stage on the pilot project before applying it solution-wide. Capture the command, package graph, discovery count, relevant log excerpt, and expected artifact in a short evidence note. Then force one controlled failure related to roll out in stages and remove legacy debt and verify that the new runner makes the problem diagnosable. Compare the evidence with the SpecFlow baseline instead of relying on memory. If results differ, classify the difference as intended, compatible, or blocking and assign an owner. This discipline keeps the SpecFlow to Reqnroll migration auditable and prevents a green summary from hiding missing scenarios or broken operational behavior.

9. Acceptance Checklist for SpecFlow to Reqnroll Migration

Acceptance should be evidence based. Confirm clean restore and build, stable discovery counts, passing representative scenarios, expected hook execution, equivalent tag filtering, successful report publication, and no remaining runtime dependency on SpecFlow. Test at least one intentional failure to prove diagnostic output and attachments, not just green behavior.

Review the migration diff for accidental feature-file changes. Whitespace-only changes can be acceptable, but altered steps, examples, or tags require business review. Validate parallel execution if enabled because static state and external test data collisions may appear only under CI concurrency.

Finally, observe several scheduled or regression runs before deleting the rollback path. Track discovery gaps, duration shifts, infrastructure errors, and newly exposed flakes. Avoid presenting normal run-to-run timing variation as a performance regression without repeated measurements.

Practice this migration stage on the pilot project before applying it solution-wide. Capture the command, package graph, discovery count, relevant log excerpt, and expected artifact in a short evidence note. Then force one controlled failure related to acceptance checklist for specflow to reqnroll migration and verify that the new runner makes the problem diagnosable. Compare the evidence with the SpecFlow baseline instead of relying on memory. If results differ, classify the difference as intended, compatible, or blocking and assign an owner. This discipline keeps the SpecFlow to Reqnroll migration auditable and prevents a green summary from hiding missing scenarios or broken operational behavior.

10. How SpecFlow to Reqnroll Migration Affects Test Design

The runner should not dictate business language. Good scenarios remain declarative, focused on observable behavior, and understandable to product stakeholders. Keep page objects, API clients, database helpers, and environment setup below the binding layer. Bindings translate domain phrases into automation; they should not become a second framework.

Migration often exposes duplicated step phrases and overly broad regular expressions. Record ambiguities, then resolve them after parity is achieved with scoped bindings or clearer domain language. Changing phrases during package replacement makes it difficult to know whether a failure came from discovery, matching, or actual behavior.

Use the transition to establish ownership. Product-facing examples need product and QA review, while runner configuration and integration code need SDET review. This split keeps Gherkin valuable as a shared specification instead of a verbose wrapper around UI clicks.

Practice this migration stage on the pilot project before applying it solution-wide. Capture the command, package graph, discovery count, relevant log excerpt, and expected artifact in a short evidence note. Then force one controlled failure related to how specflow to reqnroll migration affects test design and verify that the new runner makes the problem diagnosable. Compare the evidence with the SpecFlow baseline instead of relying on memory. If results differ, classify the difference as intended, compatible, or blocking and assign an owner. This discipline keeps the SpecFlow to Reqnroll migration auditable and prevents a green summary from hiding missing scenarios or broken operational behavior.

Interview Questions and Answers

Q: Why migrate from SpecFlow to Reqnroll?

Reqnroll provides an actively maintained open-source path for .NET BDD while retaining familiar Gherkin and binding concepts. I would justify the move through supportability and ecosystem compatibility, then prove behavior parity rather than treating it as a rewrite.

Q: How would you estimate a migration?

I would inventory projects, runners, plugins, custom generation, hooks, contexts, filters, and CI outputs. I would then pilot a representative project and use its findings to estimate each remaining project and exception.

Q: What is your first technical step?

I capture a reproducible baseline using the exact CI command. Discovery and result counts, configuration, package graph, and artifacts become acceptance evidence.

Q: How do you reduce migration risk?

I separate mechanical dependency and namespace changes from scenario refactoring. I migrate in batches, keep rollback available, and compare old and new execution evidence.

Q: What should be tested beyond green scenarios?

I test intentional failures, undefined and ignored scenarios, attachments, tag filters, hook order, scenario outlines, and report publication. These surfaces reveal false-green pipelines.

Q: How do you handle unsupported plugins?

I classify each plugin as replace, remove, migrate, or block. For a required plugin, I validate an official Reqnroll-compatible alternative or isolate and rewrite the narrow capability.

Q: How do you validate hook behavior?

I use representative scenarios and structured logs to observe order and scope. I check failure paths because teardown and attachment hooks often behave differently when a step throws.

Q: Why avoid feature edits during migration?

Stable features create a behavioral control. If wording and runner change together, a failure cannot be attributed cleanly to binding matching, discovery, or application behavior.

Q: How would you find leftover SpecFlow dependencies?

I search source, project files, lock files, build targets, configuration, and transitive package output. I also inspect CI images and documentation for old tooling.

Q: What does a migration rollback plan contain?

It keeps the last trusted branch and pipeline executable, states the trigger for rollback, and preserves test evidence. It also identifies who decides whether a discovery or infrastructure issue blocks rollout.

Q: How do you manage parallel execution?

I verify scoped context, remove shared mutable static state, allocate unique external test data, and measure behavior under the CI worker model. Parallelism is enabled only after isolation is demonstrated.

Q: What marks migration complete?

Clean restore, expected discovery, equivalent scenario outcomes, working filters and reports, documented commands, no unintended SpecFlow dependency, and several stable CI runs mark completion.

Common Mistakes

• Replacing packages and rewriting scenarios in the same commit, which destroys a clean parity comparison.
• Assuming a successful build means every scenario is discovered and executed.
• Leaving a transitive SpecFlow plugin in the dependency graph.
• Ignoring tag filters, hook order, attachments, and report publication.
• Using static scenario state, then enabling parallel execution without isolation.
• Deleting the rollback pipeline before representative CI runs are stable.

Treat mistakes as signals about system design, not as reasons to add retries blindly. Record the failure mode, improve the narrowest responsible layer, and keep the correction visible in review.

Conclusion

A successful SpecFlow to Reqnroll migration preserves scenario intent, replaces dependencies deliberately, and proves equivalence at discovery, execution, filtering, and reporting layers. Start with one representative workflow, prove it locally and in CI, then expand using the same conventions. That sequence gives the team a trustworthy baseline and makes later improvements measurable.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Add accessibility checks to CI (2026)
• How to Add CI to a test framework (2026)
• How to Add logging to a test framework (2026)
• How to Add parallel execution to a framework (2026)
• How to Add reporting to a test framework (2026)
• How to Scroll to an element in Cypress (2026)