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
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.
The 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. If your Excel table contains merged cells, the first of the merged cells will contain the value; the other merged cells will be empty.
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
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.
You can use Excel formulas anywhere in the document. The plugin uses the result of the formula, so you can use formulas to calculate test data values.
Cell ranges can be used to specify Gherkin tables. These cell ranges must to be “indented” by one column, ie. the first cell has to be left empty.
Gherkin Equivalents in Excel¶
The contents of an Excel file are converted to the Gherkin syntax automatically. The contents of the Excel file are mapped to the Gherkin syntax as follows:
|Feature||Workbook (Excel file) with extension
|Feature title||Defined using the Excel file's Title property (File | Info). If no title has been defined, the file name is used instead.|
|Feature tags||Defined using the Excel file's Keywords property (File | Info, select Advanced Properties from the Properties drop-down list). Separate keywords using whitespace or a comma. The
|Feature language||Defined using the Excel file's Categories property(File | Info). Enter
|Scenario or Scenario Outline||Worksheets (except for those that are ignored and your background)|
|Scenario title||Taken from either the name of the sheet, or can be defined in the first cell (top left) using
|Scenario tags||Defined in one or more lines at the top of the sheet. You need to include the leading
Note: Because Excel interprets the '@' character as indicating a formula, you need to add an apostrophe (') to the start of the cell's contents to indicate the contents are plain text (see the screenshot below).
Tags can be entered in a single cell and separated using whitespace, or entered in multiple cells.
|Scenario steps (Given/When/Then)||Each scenario step must be on a separate row. The step's text can be split over multiple cells or entered in a single cell. Splitting the text over multiple cells allows you to use formulas easily, and generally makes it easier to format the scenario's steps.|
|DataTable step argument||You can define a table argument (called DataTable in Gherkin) for your steps. To define a DataTable, add the rows after the step and indent each row of the DataTable by one column (i.e. the first cell must be empty).|
|DocString step argument||You can add multi-line text arguments (called DocString in Gherkin) to your steps. To do so, leave the first cell empty in the row after a step, and include the DocString parameter in the second cell (including newlines). The DocString argument cannot be split over multiple cells.|
|Background||Add a sheet named
|Scenario Outline||A sheet (like for a Scenario) but with an Examples section.|
|Scenario Outline Examples||To define scenario outline examples, start a row with a cell containing
The example data needs to be indented by one column (i.e. the first cell must be empty) and should contain a header with the names of the placeholders. You can define multiple examples block for a scenario outline.
|Comments||You can explicitly mark a row as a comment by starting the first non-empty cell with