A new version of SpecFlow+ LivingDoc has been released and is now available from the Visual Studio marketplace.

Important change: The location of SpecFlow+ LivingDoc in Azure DevOps has been changed. SpecFlow+ Living Doc can now be found under Overview | SpecFlow+ LivingDoc. This ensures that all users, including those without a Test Plan license can access the documentation.


  • Updated UI:
    • Moved the location of LivingDoc in Azure DevOps to be under Overview | SpecFlow+ LivingDoc so that all users can access it without needing a Test Plan license
    • Changed the appearance of the feature explorer and search filters
  • View documentation for a specific repository and branch
  • Improved search and filters

New features:

  • Pull requests can now be selected from the list of branches in order to review the documentation for PRs that have not yet been merged

We are happy to announce the release of SpecFlow and SpecFlow+Runner 3.1. This update fixes a lot of smaller issues found by our community members over the last months, but we have also added some bigger features to this release.

What’s new?

1. .NET Core 3.0 Support

With the addition of nullable reference types in C# 8, we needed to make some changes to our binding execution code. These changes have now been implemented, and all our tests for .NET Core 3.0 are successful.

2. Cucumber Messages

The integration of Cucumber messages is a joint effort with the Cucumber community to create a unified protocol for exchanging data between different components of SpecFlow and Cucumber. There will be no longer be a need to implement separate HTML report generators for each Cucumber implementation and SpecFlow. Cucumber messages allow you to use the same HTML report generators for SpecFlow and Cucumber.

SpecFlow 3.1 contains the first set of Cucumber Messages: TestRunStarted, TestCaseStarted, TestCaseFinished and TestRunFinished. We plan on implementing additional messages that allow you to generate different output formats/reports in future releases.

Cucumber messages are currently disabled by default. We plan to enable them by default with SpecFlow 3.2. You can find the current documentation here.

Changes Related to Cucumber Messages

For end users, the introduction of these messages does not bring any changes from previous versions, as we have not changed SpecFlow’s overall behavior.

However, we changed the internal workings of how scenarios are ignored. In the past, we generated the appropriate ignore attribute for the test runner in the code-behind file. But as we now also need to send a cucumber message for skipped scenarios, we no longer generate the ignore attribute and skip the scenario at runtime instead.

3. Docker Support in SpecFlow+Runner

One thing we learned is that just because SpecFlow is compiled and runs with .NET Core, that does not mean it will run on Windows, Linux and Mac OS. Not all aspects of.NET Core are applicable to all 3 operating systems. SpecFlow+Runner 3.1 now uses APIs that also work on Linux and MacOS. All SpecFlow+Runner features should also now work in Docker. If not, please open an issue.

If you want to generate SpecFlow+ Runner reports on non-Windows operating systems, you need to install mono. Details can be found here.

A sample SpecFlow+ Runner project demonstrating support for Docker support can be found here.

4. Gherkin 6 “Rule” Keyword

SpecFlow 3.1 supports the new Gherkin 6 Rule keyword.

However, the Visual Studio Extension does not yet support this keyword. Using it will stop the syntax highlighting from working.

5. Project Template

To make it easier to create new SpecFlow projects, we have created a project template that you can access with dotnet new. You can find more information on installing the template and using it to create new projects here.

Thanks to all our amazing contributors!

Thanks to the following users for their contributions to SpecFlow 3.1:

Detailed Changelogs

Changelog for SpecFlow


  • Support for .NET Core 3.0
  • Cucumber messages:
    • First set of cucumber messages are implemented:
      • TestRunStarted
      • TestCaseStarted
      • TestCaseFinished
      • TestRunFinished
    • Documentation: https://specflow.org/documentation/Cucumber-Messages/
    • Cucumber messages can be enabled via specflow.json and app.config
    • File sinks for Cucumber messages can be configured
  • Support for Gherkin v6 “Rule” keyword
  • Support for discovering step definitions from attributes that are derived from Given, When, Then or StepDefinition attributes (related to Issue 1745)


  • AfterTestRun hook can take longer than 100ms on .NET Core (Issue 1348)
  • Adjust parameter names generation in scenario outlines (Issue 1694)
  • specflow.json can be used in SpecFlow+Runner with Process test thread isolation (Issue 1761)
  • specflow.json is copied to output directory automatically (Issue 315)
  • Step definition method with “object” parameter type might not match

Changelog for SpecFlow+Runner


  • Support for .NET Core 3.0
  • Support for SpecFlow 3.1


  • Test execution in Docker works
  • Improved performance when executing projects with a lot of scenarios (> 10,000)


  • Changed the communication between main process and child processes from named pipes to TCP/IP

This article covers updating existing plugins to work with SpecFlow 3. If you are interested in developing your own plugins, the documentation for SpecFlow plugins is here. This documentation includes links to sample plugins that you can use as a basis for developing your own.


With SpecFlow 3, the plugins you want to use are no longer configured in your app.config file. To use existing plugins with SpecFlow 3, the easiest way is to package your plugin as a NuGet package and edit the .targets and .props files as described below. These files need to have the same name as your NuGet package.

As part of the configuration of your plugin, you also need to determine which plugin assembly to load based on whether you are using Full Framework or .NET Core.

Generator Plugins

To update your generator plugin:

  1. Package your plugin as a NuGet package if you haven’t already.
  2. The actual DLL to reference is determined in the .targets file. You need to load a different version of the plugin depending on which version of MSBuild you are using (Full Framework vs .NET Core). Using the xUnit .targets file as an example (the file is here):
       <_SpecFlow_xUnitGeneratorPlugin Condition=" '$(MSBuildRuntimeType)' == 'Core'" >netstandard2.0</_SpecFlow_xUnitGeneratorPlugin> 
       <_SpecFlow_xUnitGeneratorPlugin Condition=" '$(MSBuildRuntimeType)' != 'Core'" >net471</_SpecFlow_xUnitGeneratorPlugin> 

    Which plugin to use is determined based on the MSBuildRuntimeType (either “Core” or another value). “netstandard2.0” and “net471” are the directories containing the corresponding DLL for each runtime.

  3. Edit the .props file in your package to include your plugin’s path. You need to add an ItemGroup containing the SpecFlowGeneratorPlugins element to this file.
    Using the .props file for the generator plugin for xUnit (located at /Plugins/TechTalk.SpecFlow.xUnit.Generator.SpecFlowPlugin) as an example, the .props file is configured like this:

      <SpecFlowGeneratorPlugins Include="$(_SpecFlow_xUnitGeneratorPluginPath)" />

    This adds the plugin’s fully qualified path to the list of SpecFlowGeneratorPlugins.

Runtime Plugins

Like generator plugins, runtime plugins are also no longer configured in your app.config file. Instead, SpecFlow loads all files ending with .SpecFlowPlugin.dll found in the following locations:

  • The folder containing your TechTalk.SpecFlow.dll file.
  • The current working directory

To update your runtime plugin:

  1. The actual DLL to reference is determined in the .targets file. You need to load a different version of the plugin depending on the target framework of your project (Full Framework vs .NET Core). Using the xUnit .targets file as an example (the file is here):
       <_SpecFlow_xUnitRuntimePlugin Condition=" '$(TargetFrameworkIdentifier)' == '.NETCoreApp' ">netstandard2.0</_SpecFlow_xUnitRuntimePlugin> 
       <_SpecFlow_xUnitRuntimePlugin Condition=" '$(TargetFrameworkIdentifier)' == '.NETFramework' ">net45</_SpecFlow_xUnitRuntimePlugin> 

    Which plugin to use is determined based on the TargetFrameworkIdentifier (either “.NETCoreAPP” or “.NETFramework”). “netstandard2.0” and “net45” are the directories containing the corresponding DLL for each runtime.

  2. Edit the .props file in your package to include your plugin’s path. Because .NET Core does not copy the referenced files to your target directory, you need to add your runtime plugin to the None ItemGroup and set CopyToOuputDirectory to “PreserveNewest” to ensure the plugin is copied.
    Using the props file for the xUnit plugin (located at /Plugins/TechTalk.SpecFlow.xUnit.Generator.SpecFlowPlugin) as an example:

      <None Include="$(_SpecFlow_xUnitRuntimePluginPath)" > 

Plugin Developer Channel

We have set up a Gitter channel for plugin developers here. If you questions regarding the development of plugins for SpecFlow, this is the place to ask them.

We have released a new version of the Visual Studio Extension that adds two new features.

IntelliSense for Table Column Headings

The auto-complete suggestions now also display column names from tables in your feature files:

A bit thanks to slig3 for adding this feature that will surely be appreciate by many users!

Reformatting Feature Files

This feature adds documenting formatting support to the Gherkin editor:

  • Normalise indents with different indentation levels for different sections, and the ability to choose between tabs and spaces
  • Normalise line breaks
  • Format all tables

There are a number of options that configure the behavior under Tools | Options | SpecFlow.

Thanks to claudiobernasconi, littlegenius666 and dreamescaper for adding this feature!

The Visual Studio extension has been updated for SpecFlow 3. The following is a summary of the changes.

Visual Studio 2019 Support

The latest version of the Visual Studio extension is compatible with Visual Studio 2019.

Legacy Single File Generator

We strongly recommend using the MSBuild integration to generate your code behind files. However, when you first install the new Visual Studio extension, it will be set to use the legacy code behind file generation method using SpecFlow’s single file generator.

To use the MSBuild integration, you need to disable this legacy support in the options in Visual Studio. To do so:

  1. Select Tools | Options from the menu in Visual Studio.
  2. Browse to SpecFlow | General in the list on the left (you can use the search field to restrict the options).
  3. Set Enable SpecFlowSingleFileGenerator CustomTool to false under Legacy.
  4. Click OK.

You also need to ensure that SpecFlowSingleFileGenerator is not entered in the Custom Tool field of your feature files.
Custom Tool

If you do not remove this entry, you will receive an error (“SpecFlow designer codebehind generation is not compatible with MSBuild codebehind generation. The custom tool must be removed from the file.”)

Context Menu Options Removed

The following options have been removed from the context menu:

  • Run SpecFlow Scenario
  • Debug SpecFlow Scenario

These options were removed due to the require APIs no longer being available, and due to these options being unreliable and causing a lot of issues.

Renaming Steps

Steps can now be renamed and the changes to the step name are propagated automatically to your code. Big thanks to slig3 for this contribution!

To rename a step:

  1. Open the feature file containing the step.
  2. Right-click on the step you want to rename and select Rename from the context menu.
  3. Enter the new text for the step in the dialog and confirm with OK.
  4. Your bindings and all feature files containing the step are updated.

Note: If the rename function is not affecting your feature files, you may need to restart Visual Studio to flush the cache.



You can find an overview of the new features in SpecFlow and SpecFlow+ Runner here. The full changelog for SpecFlow is here.

More information on using SpecFlow with .NET Core can be found here.

Make a Backup!

Before upgrading to the latest version, ensure you have a backup of your project (either locally or in a source control system).

Visual Studio Integration

The Visual Studio integration for SpecFlow has been updated for SpecFlow 3. You will need to update the extension in order to upgrade. If you previously set the extension to not update automatically, please enable automatic upgrades once your projects have been migrated to SpecFlow 2.3.2 or higher.

The new extension is only compatible with SpecFlow 2.3.2 or higher! Do not upgrade upgrade the SpecFlow Visual Studio integration until you have migrated all your projects to at least SpecFlow 2.3.2, otherwise you will need to switch between Visual Studio extensions whenever you switch between projects.

If you have projects that are using an earlier version of SpecFlow (prior to 2.3.2), you can download previous versions of the extension from this page on GitHub. If you download an earlier version, please make sure you disable the option to update the extension automatically, otherwise it will be automatically updated with the new version again!

To prevent the Visual Studio integration from automatically updating:

  1. Select Tools | Extensions and Updates from the menu in Visual Studio
  2. Locate the SpecFlow extension in the list using the search field on the right, if necessary.
  3. Disable the Automatically update this extension option on the right.
  4. Don’t forget to enable this option again once you have upgraded to SpecFlow 2.3.2 or higher!

App.config Deprecated

Changes to How Unit Test Providers are Configured

In previous versions of SpecFlow, the unit test provider used to execute tests was configured in your app.config file. As of SpecFlow 3, we strongly recommend configuring your unit test provider by installing one of the available packages (see below).


Moving forward, we recommend using specflow.json to configure SpecFlow, rather than app.config. .NET Core projects require specflow.json (app.config is not supported). While using specflow.json is optional for Full Framework projects, we recommend migrating to the new format. For more details, see Configuration in the documentation.

Updating SpecFlow

To upgrade a solution from SpecFlow 2.x to SpecFlow 3:

  1. Open your solution, and check that it compiles, all tests are discovered and that all source files have been committed.
  2. Right-click on your solution and select Manage NuGet Packages for Solution.
  3. Switch to Updates in the list on the left and locate SpecFlow in the list of packages. Use the search box to restrict the listed packages if necessary.
  4. Select the SpecFlow package in the list and click on Update.
  5. Add one of the following packages to your specifications project (the one containing your tests) to select your unit test provider:
    • SpecRun.Runner
    • SpecFlow.xUnit
    • SpecFlow.MsTest
    • SpecFlow.NUnit

    Note: You will receive an error if you add more than one of these packages to your project.

  6. Add the SpecFlow.Tools.MsBuild.Generation NuGet package to your project. This package is used to generate SpecFlow’s code-behind files.
  7. Remove “SpecFlowSingleFileGenerator” from the Custom Tool field in the Properties of your feature files.

Updating SpecFlow and SpecFlow+ Runner

If you want to update both SpecFlow and SpecFlow+ to version 3, the easiest way to do this is to simply upgrade the SpecRun for SpecFlow package. This automatically updates SpecFlow as well.

To update SpecFlow and SpecFlow+:

    1. Open your solution, and check that it compiles, all tests are discovered and that all source files have been committed.
    2. Right-click on your solution and select Manage NuGet Packages for Solution.
    3. Uninstall any SpecRun.SpecFlow packages you have installed.
    4. Install/update the following packages:
      • SpecFlow
      • SpecRun.SpecFlow
      • SpecFlow.Tools.MsBuild.Generation
    5. Remove “SpecFlowSingleFileGenerator” from the Custom Tool field in the Properties of your feature files.

Migrating your License

Prior to SpecFlow 3, licenses were stored in the Windows registry. In order to support .NET Core, the license information is now stored in a file in your local file system. There is also a new licensing tool for .NET Core.

If you have already registered a SpecFlow license, you can migrate your license from the registry to the local file using specrun.exe. Migrate your existing license using the following command:
specrun migrate-license

Information on installing the new licensing tool can be found in the documentation.

Running Tests from the Command Line

The command line tool SpecRun.exe does not work with .NET Core projects. To run your tests, use the following command lines instead (depending on your target framework):

  • dotnet test
    Specify the path to your solution or project, or run the command from that folder. See the documentation here.
  • vstest.console.exe
    Specify the path to your test assembly. See the documentation here.

SpecFlow+ Runner Report Templates

If you have customised the SpecFlow+ runner templates, a small change needs to be made to the template for SpecFlow 3:

  1. Open the CSHTML file in the editor of your choice.
  2. Replace the first line with the following:
    @inherits SpecFlow.Plus.Runner.Reporting.CustomTemplateBase<TestRunResult>

SpecFlow 3 supports .NET Core

Before installing the new version, please read the information on updating to SpecFlow 3. The installation procedure is also covered there.

Information on changes to the Visual Studio extension can be found here.


New features:

  • Support for .NET Core!
  • Separate addition of default and non-default value comparers. ComparisonException indicates which value comparer was used for each difference
  • Uri and Null value retrievers added
  • BoolValueRetriver can now work with 1 and 0
  • Array & List support for any available item value retriever when instantiating class from Specflow table
  • Syntax and structural changes in value retriever/comparer registration
  • Check for non-default constructors using case-insensitive comparison
  • Add utility to get enum field value from TableRow.
  • Gherkin language data is used instead of an obsolete copy
  • Loader exceptions are appended to the exception message
  • Add CreateInstance<T> support to a TableRow


  • Visual Studio change detection integration for Net.SDK style projects via SpecFlow.Tools.MSBuild.Generation


  • Command line options now need to be prefixed with -- (double dash) rather than /

Breaking changes:

  • Registration of value retrievers and comparers has been changed from RegisterValueComparer(___) to ValueComparers.Register(___)
  • Calling CreateInstance on an object with a constructor with default parameters populates the object using the default parameters instead of null values
  • Visual Studio change detection integration for Net.SDK style projects via SpecFlow.Tools.MSBuild.Generation

Known issue:

  • AfterTestRun code fails to complete under certain circumstances, see this GitHub issue for details and possible workarounds.
  • Step bindings from external assembly are not found: set Copy to output directory for specflow.json.


  • The functions provided by specflow.exe (generate all, reports) have been removed completely.

You can find the full changelog here.


New features:

  • Support for .NET 2.0, 2.1, 2.2
  • Added DeleteFolder as a new deployment transformation step


  • Reports: Display the correct success rate for retried scenarios
  • Profile files are no longer duplicated in the solution explorer
  • Display failing scenarios with at least one pending or successful retry as randomly failed


  • Command line options now need to be prefixed with -- (double dash) rather than /

Breaking changes:

  • Report generation has been moved to a separate process
  • The base class for reports has been changed from TechTalk.SpecRun.Framework.Reporting.CustomTemplateBase<TestRunResult> to SpecFlow.Plus.Runner.Reporting.CustomTemplateBase<TestRunResult>
    If you have customized the report templates, you will need to edit the first line of your templates accordingly.


  • Support for combined test executors (e.g. SpecRun+NUnit and SpecRun+MSTest) has been removed as a result of the new plugin infrastructure

Behavioral changes:

  • If CLR 2.0 is specified as the runtime, SpecFlow+ Runner uses the CLR 4.0 executor.



SpecFlow 3 would not have been possible without your contributions. Don’t forget to grab yourself some SpecFlow stickers!


SpecFlow+ LivingDoc 0.2.19 has been released and is available on the Visual Studio marketplace. This version includes the following changes:

  • Changing the build definition/branch selection or selecting a node in the feature tree updates the URL in the address bar
  • Opening a link to LivingDoc containing a feature/scenario now selects the corresponding drop-down entries and opens the feature tree
  • Opening LivingDoc using a URL that does not contain a definition/branch opens the latest selected build definition and most recently selected branch


  • The bottom line of the feature tree is no longer cut off

The new LivingDoc version 0.2.17 is available and it contains the feature of linking feature/scenario tags to certain work items.

This prefix will indicate that the tag marked with it is a special tag that will be connected to the work item.

The way it works is as follows:

  • A prefix for the project should be chosen. This prefix will indicate that the tag marked with it is a special tag that will be connected to the work item.
  • Change the tags in the project’s feature files so that each one contains both the prefix and the id of the related work item (e.g.: if the prefix is @workItem and the id is 3212 the tag should be @workItem3212)
  • In the build, pipeline chooses the LD build step. There’s a new option for setting the prefix. Change it to whatever prefix is set in the project.
  • After a new build is run, the generated LivingDoc will display these connected tags bold, and clicking on them will pop up the related work item in a modal window.

Other things to know:

  • LD only accepts (and matches) a single prefix per project
  • In the project, the tag should consist only of the prefix and the work item number. No separator character is needed nor it is allowed.
  • In the build task where you can define the prefix, it is not obligatory to use ’@’ as a starting character of the prefix, LD will still recognize the prefix in the feature files
  • If there’s a tag in a feature file that is prefixed with this special work item prefix but has no work item number, something that cannot be parsed to a number or a non-existing work item id, the popup window will have no content but will show an error message (e.g. @workItem in itself as a tag would cause such an error message)

As announced here, we need to update the SpecFlow Visual Studio extension (VSIX) for SpecFlow 3. The updates mean the new extension will not be compatible with older versions of SpecFlow ( <2.3.2). We plan to update the SpecFlow Visual Studio extension with the SpecFlow 3-compatible version when SpecFlow 3 is officially released. Note that a preview version of SpecFlow 3 is currently available, more details can be found here.

By default, the extension updates automatically, which will break older projects using versions of SpecFlow prior to 2.3.2. An alternative approach would be to release a dedicated SpecFlow 3 extension. There would then be two separate extensions for SpecFlow, which would avoid the automatic update from breaking old projects. However, we ended up discounting this approach for a number of reasons that are summarised below. Each approach has disadvantages and could potentially cause projects to stop working.

Approach 1: Release a New SpecFlow 3 Extension

In this case, we would release a new VSIX for SpecFlow 3, and leave the current extension online for users of earlier versions.


  • Users of earlier versions do not have to do anything (i.e. disable automatic updates) to prevent their projects from breaking.


  • Having two separate versions of a SpecFlow 3 extension in the gallery will cause confusion. Some users will invariably install the wrong version, increasing the number of support issues. This will persist for as long as both extensions are available, i.e. way past the transition period where most users will have migrated from 2 to 3.
  • There will be conflicts if both extensions are installed. There is no way to guarantee that only one of the extensions is installed.
  • Users suddenly need another extension for what appears to be “no good reason”.
  • Punishes users who consistently update to new versions, as these are the ones who need to jump through hoops to use the new release.

Approach 2: Upgrade the Existing Extension

In this case, we would update the existing VSIX for compatibility with SpecFlow 3.


  • While there may be some short-term confusion and support requests relating to projects suddenly not working (automatic update), these will die down quickly. After ~6 months, the dust will probably have settled.
  • All users will have their extension automatically upgraded to be compatible with the latest version. This is how it has always been.


  • Requires users not interested in Specflow 3 to make changes to their setup to avoid breaking changes. However, this is a one-off and involves clicking a check box.
  • There will invariably be some users who need to continue using SpecFlow <2.3.2 for now, and who will forget that automatic updates need to be enabled when they make the switch to version 3. Again, the number should decrease as time goes on.

With that in mind, we feel that upgrading the existing extension is better approach. It will cause some teething problems for a few months while the switch is made. After a while, the dust will settle. Conversely, we feel that providing two separate extensions runs the risk of causing confusion due to multiple versions of the extension, and the confusion will persist indefinitely. It will not simply die down after a few months if there are two mutually exclusive extensions available for download.

Your thoughts?

If you think we have overlooked some important aspects or have have alternative suggestions on how to improve the upgrade experience, please share them in the discussion here.

If you have reasons for using older versions of SpecFlow and do not want to regularly upgrade, let us know your motivation too. Both approaches will make it difficult to work with older SpecFlow versions and SpecFlow 3 on the same machine; we are not sure to what extent this could be an issue.