Updating to SpecFlow 3

IMPORTANT INFORMATION

Changelogs

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 extensin to not update automatically, please enable automatic upgrades once your projects have been migrated to SpecFlow 2.3.2 or higher.

WARNING!
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).

specflow.json

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>