Despite the current version of Gherkin (v6), the syntax for documenting requirements using the Given-When-Then format has not really changed until recently. Gherkin v6 is backwards compatible, but it introduces a few new features that might be useful for all BDD practitioners. These changes are supported by the new SpecFlow v3.1 release.

Gherkin v6 changes

As I have mentioned, the language syntax has not really changed in the last 8 years and even the changes introduced by Gherkin v6 are rather small. The reason for this is that we would like to keep the Gherkin language as a common platform between the people of different roles and between the tools built on top of that (like SpecFlow). So stability is a key criteria. In Gherkin v6 there are two improvements:

1. Support for “Rule” keyword

Through the years, BDD practitioners have collected more experience on writing better BDD scenarios. One of the key principle for this is that scenarios should focus on illustrating a single business rule (acceptance criterion) only. The scenarios that illustrate multiple rules of a feature become difficult to read and maintain. Moreover, focusing on a single rule also helps identifying how many and which scenarios might be helpful. Practices, like Example Mapping (described by Matt Wynne) use this concept in requirement workshops.

These techniques seemed to be useful for many of us, but in the end, we had to save the scenarios of the different rules into a single feature file and we had to document the rules; their association to the scenarios could be preserved in the file header or as a comment only.

Gherkin v6 introduces a “Rule” keyword that acts as a grouping construct for the scenarios. Every scenario that is after a rule keyword line (e.g. “Rule: my rule”) will logically belong to that rule until the next rule line. The scenarios which are in the top of the file (before the first rule line) will not be associated to any of the rules.

SpecFlow v3.1 now supports this construct, so you can start using it in your projects. The tooling that works on the Gherkin files might need to be adapted too. The picture below is from my new open-source Visual Studio extension called Deveroom.

2. Scenarios can be used as Scenario Outlines

The other change is smaller and might be a bit controversial. Based on the feedback, especially from new users of Gherkin, using different keywords for scenarios and scenario outlines were problematic. For a scenario outline, you anyway need to add an additional “Examples” section, so using a different keyword as well is a kind of redundancy. From Gherkin v6 you can use the “Scenario” and “Scenario Outline” keywords in an interchangeable way: you can turn a scenario to an outline just by adding an “Examples” block to it. Of course you can still use the “Scenario Outline” keyword, like before.

Gherkin versioning

As I have mentioned, the Gherkin syntax has not been changed in the last 8 years. So you probably wonder why it has the version number 6 and not 2?

The Cucumber team versions the Gherkin project (that is embedded into the Cucumber mono-repo) and not the language syntax. This means that even though the language syntax has not changed, the parser that parses the files is continuously improving with fixes or is providing a better interface for the tools that use it. Also from time to time there are changes in the keyword variations, especially for the non-English keywords. So for someone who needs to write scenarios, Gherkin v6 is the key release but the tool vendors must also watch the other releases too. You can find the detailed release history on GitHub.