Excel Feature File Format

Note: While English Gherkin keywords are used in this documentation, the SpecFlow+ Excel plugin supports all 50+ languages supported by Gherkin itself. You can also use the various variations as well (e.g. Scenario Outline and Scenario Template).

We recommend checking out our sample Excel feature file first to get an idea of how the files are structured.

Naming Feature Files

Excel feature file must have the .feature.xlsx extension, e.g. Calculator.feature.xlsx. SpecFlow's build-time generation can only convert Excel files in your project with this extension.

Cell Content

Cell content in your Excel files is converted by SpecFlow+ Excel using the following rules:
* If a cell contains a formula, the result of the formula is used * Formatting (e.g. currency or date format) is ignored * The binding culture is used to convert cell values to strings for your tests * The binding culture is the default Gherkin language of your project, but can overridden. See SpecFlow documentation for more details.

Note: Gherkin tables do not support merged cells, so merged cells are converted without merging, i.e. the first cell will contain the value and the other cells will be empty.

Ignored Content

Certain content in your Excel files is ignored by SpecFlow+ Excel. You can use this content for comments, helper calculations etc.

The following is ignored: * Data on hidden sheets or sheets whose name begins with an underscore ('_') * Cell values where there are at least 2 empty cells to the immediate left of the cell (i.e. use two empty columns to separate comments from data). This includes rows where the first two cells are empty. * Empty rows

Defining Steps

Each step must be defined on a separate row. The step can be split up over multiple cells in the same row, in which case it is treated as though there is a space between the content of neighbouring cells.

Using Formulas

You can use Excel formulas anywhere in the document. The plugin uses the result of the formula.

Using Tables

Cell ranges can be used to specify Gherkin tables. These cell ranges has to be "indented" by one column, ie. the first cell has to be left empty.

Excel features matching to the Gherkin feature file structure

Gherkin Excel


Workbook (Excel file) with extension .feature.xlsx

Feature title

Title document property, or the file name if empty.

Feature tags

Keywords document property, separated by whitespace or comma. The @ prefix is not required.

Feature language

Put language:lang-code into the Category document property. For SpecFlow, the project defaults are used.

Scenario or Scenario Outline

Worksheets (except ignored or background)

Scenario title

The name of the sheet or a line in the top of the sheet with the first cell as Scenario: or Scenario Outline: and followed by a cell with the title text. The Excel sheet names can contain maximum 31 characters, so for longer scenario titles, you have to use the second option.

Scenario tags

One ore more lines in the tip of the sheet with cells containing tags, including the leading @. The tags can be split to multiple cells or separated with whitespace.

Scenario steps (Given/When/Then)

Rows in the scenario sheet. The step text can be split to multiple cells, but this is optional. The entire step, including the step keyword can be placed into a single cell. By splitting the step text to multiple cells, you can better use formulas inside the step and you can format the scenario better.

DataTable step argument

You can easily provide a table argument (called DataTable in Gherkin) to your steps. To describe the DataTable cells, just add rows after the step row and use the Excel cells. The cells used as DataTable need to be "indented" by one column, ie. the first cell has to be left empty.

DocString step argument

You can add multi-line text argument (called DocString in Gherkin) to your steps. For that, leave the first cell empty in the row below the step row, and include the DocString parameter in the second cell (including newlines). The DocString argument cannot be split to multiple cells currently.


A sheet named Background.

Scenario Outline

A sheet, like for a Scenario, but with an Examples section.

Scenario Outline Examples

Start a line with a cell containing Examples:. You can use the next cell to specify a title for the examples block (optional). You can also add lines with tags directly before this line. The examples table can be specified as Excel cells, but they need to be "indented" by one column, ie. the first cell has to be left empty. You can specify multiple examples block for a scenario outline. Scenario Outline Examples


Although you can put helper calculations and comments to multiple places and sheets (see above), you can also mark an Excel row explicitly as comment, by starting the first non-empty cell with #.