SpecFlow+ Excel Getting Started (old)

Posted on:

Please visit the SpecFlow+ Excel page for introduction and general information.

For information on using SpecFlow+ Excel with other tools in the Cucumber family (i.e. not SpecFlow), refer to the documentation: Using SpecFlow+ Excel with Cucumber-family tools. This guide focuses using SpecFlow+ Excel with SpecFlow.

To use SpecFlow+ Excel, you need to create a normal SpecFlow project, see SpecFlow – Getting Started for details. Although we recommend using SpecFlow+ Runner (formerly known as SpecRun), this is not required. The Excel plugin works also with other unit test providers.

Once you have created your SpecFlow project, install the SpecFlow+ Excel plugin from NuGet.

PM> Install-Package SpecFlow.Plus.Excel


You can evaluate all the features in SpecFlow+ Excel for free. However in evaluation mode, an extra scenario is generated with title “SpecFlow+ Excel Evaluation Mode”. You can remove this limitation by purchasing a license here. For more details, see SpecFlow+ Evaluation.

This package enables the plugin in the App.config file and configures the project to use SpecFlow’s build-time generation feature by adding an MsBuild target to the project file. This ensures that the tests in the Excel files are re-generated when necessary. The build-time generation works well together with the normal generation process that is triggered by saving feature files in Visual Studio. This has the positive side effect that you no longer need to store the generated files in your source control system! You can configure your source control system to ignore the following patterns (e.g. by adding these lines to .gitignore):

  • *.feature.cs
  • *.feature.xlsx.*

Adding a new Excel feature file

To add a new Excel feature file to your project:

  1. Create an Excel file with the *.feature.xlsx suffix (e.g. Calculator.feature.xlsx). Start describing a scenario using Given/When/Then on the first sheet. You can split the steps over multiple cells and can of course use formulas. Delete the other sheets.
    You can find an example in the docs folder of the NuGet package. See the documentation for detailed description of the Excel feature file format.
  2. Include the Excel file in your project.
  3. Compile the project. This will generate the related code-behind file (Calculator.feature.xlsx.cs) and the related feature file (Calculator.feature.xlsx.feature). You can turn off the generation of the feature file by specifying a “skip-feature-file” tag in the feature Excel.
  4. Include the generated files in your project.
  5. Compile the project again: You are ready to run your tests in the Excel file!
  6. You can optionally mark the generated files as dependent on the Excel file, so that they are displayed as a sub-item in Visual Studio.

Extending Scenario Outline examples with an Excel file

To extend a scenario outline example:
  1. Describe your scenario outline in Gherkin in a normal feature file.
  2. Create an Excel file (e.g. CalculatorExamples.xlsx), and rename a worksheet to the same name as the scenario outline. You can use the same Excel file for multiple scenario outlines. See documentation to find outmore about how to use custom sheet names.
    You can find an example in the docs folder of the NuGet package. See the documentation for a detailed description of the Excel examples file format.
  3. Add the desired example data to the worksheet and save the Excel file.
  4. Include the Excel file in your project.
  5. Tag the Examples section of the scenario outline with @source:CalculatorExamples.xlsx. Optionally, you can also specify the sheet name to be used: @source:CalculatorExamples.xlsx:Sheet1.
  6. Compile the project: The examples in the Excel file will appear as new tests!

Updating Scenarios and Examples in Excel file

You can easily change the examples or scenarios specified in your Excel file:

  1. Open the Excel file and make your changes.
  2. Save the Excel file.
  3. Compile your project: The changes you made in the Excel file are applied to your tests!

Because the build-time generation ensures that the test are always in sync with the feature and Excel files, even testers and product owners can perform these changes. They should just check-in the updated Excel files and the build server will preform the necessary generation steps and will execute the updated tests.