Excel Feature File Format

General rules

Note: The rule descriptions use English Gherkin keywords, but the SpecFlow+ Excel plugin supports all 50+ languages supported by Gherkin itself. You can also use the different keyword variations as well (like Scenario Outline and Scenario Template).

We recommend checking out our sample Excel feature file before studying the detailed rules.

  • The Excel feature file has to use .feature.xlsx extension, e.g. Calculator.feature.xlsx. The build-time generation of SpecFlow will only convert Excel files in the project with this extension.
  • Consider the general cell conversion rules, especially for non-string cell values.
  • You can use the Excel worksheets and cells for helper calculations and comments that should not be part of the feature file. SpecFlow+ Excel will ignore
    • the hidden sheets or the sheets with name prefixed with underscore (_)
    • the cell values that you put on the right side (separated by at least two empty cells)
    • the rows where the first two cell is empty
  • The step text can be split into multiple cells. The cells are merged with a single space during processing.
  • You can use Excel formulas anywhere in the document. The plugin processes the formula result.
  • 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.
  • The empty Excel rows are ignored.
  • Merged cells: Gherkin tables do not support merged cells, so merged cells are converted without merging, ie. the first cell will contain the value and the other cells will be empty.

Excel features matching to the Gherkin feature file structure

Gherkin Excel

Feature

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.

Background

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

Comments

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 #.