As mentioned in the previous post, behavior scenarios are the cornerstone of BDD. Each scenario is the formalized specification of a single behavior of a product or feature. Scenarios are both the requirements for the feature as well as the test cases. This post will show how to write behavior scenarios in Gherkin feature files. (Check the Automation Panda BDD page for the full table of contents.)

Introducing Gherkin

Gherkin is the domain-specific language for writing behavior scenarios. It is a simple programming language, and its “code” is written into feature files (text files with a “.feature” extension). The official Gherkin language standard is maintained by Cucumber, one of the most prevalent BDD automation frameworks. Most other BDD frameworks use Gherkin, but some may not conform 100% to Cucumber’s language standards.

Gherkin scenarios are meant to be short and to sound like plain English. Each scenario has the following structure:

1. Given some initial state
2. When an action is taken
3. Then verify an outcome

A simple feature file example is shown below, with keywords in bold:

Feature: Google Searching
  As a web surfer, I want to search Google, so that I can learn new things.
  
  Scenario: Simple Google search
    Given a web browser is on the Google page
    When the search phrase "panda" is entered
    Then results for "panda" are shown

As you can see, it reads intuitively. Even non-technical people can understand it.

The Feature section has a title and a description, which are both used only for documentation purposes. When the feature is tied to an Agile user story, it is good practice to put the user story in the description. The Feature section has one or more Scenario sections, each with a unique title.

Each scenario is essentially a test case. The Given-When-Then format concisely frames the behavior under test. Each Given, When, or Then line is called a step. Steps must appear in the order of Given->When->Then and are executed sequentially. The Given step sets up the expected state before the main actions take place (like loading the Google home page). The When step contains the actions for exercising the behavior under test (running a Google search), and the Then step verifies that the behavior was successful (seeing the results page). The English-y phrase following the step keyword is a description of what the step will do, written by the test author. This description is linked to a step definition (a method/function that implements the operations for the step) in the automation code base using string or regular expression matching. (Feature files apart from step definitions are basically manual test case procedures.) Good steps are declarative in that they state what should happen at a high level, and not imperative because they shouldn’t focus on direct, low-level instructions.

Gherkin Keywords

Every programming language has its keywords, and Gherkin is no different. The table below explains how each keyword is used in the official Gherkin language. Note that some BDD frameworks may not be fully compliant. Cucumber provides a decent Gherkin language reference for its implementation.

Keyword	Purpose
Feature	section denoting product or feature under test contains a one-line title contains extra lines for description description should include the user story may have one Background section may have multiple Scenario and Scenario Outline sections should be one Feature per feature file
Scenario	section for a specific behavior scenario contains a one-line title contains multiple Given, When, and Then steps each type of step is optional step order matters each scenario runs independently
Given	step to define the preconditions (initial state or context) should put the product under test into the desired state may be parameterized
When	step to define the action to be performed may be parameterized
Then	step to define the expected result from the action taken by When may be parameterized
And	an additional step added to a Given, When, or Then used instead of repeating Given, When, or Then example: Given-Given-When-Then = Given-And-When-Then associated with the immediately preceding step order matters
But	functions the same as And, but might be easier to read interchangeable with And
Background	a section of Given and And statements to run before each scenario does not have a title or description only one Background for each Feature section
Scenario Outline	a templated scenario section uses “<” and “>” to identify parameter names followed by Examples tables that provides parameter values may have more than one Examples tables parameters are substituted when the tests run
Examples	a section to provide a table of parameter values for a Scenario Outline each table row represents a combination of values to test together may have any positive number of rows
|	table delimeter used for Examples tables and step tables use the escape sequence “\|” to use pipe characters as text within a column
“””	doc string delimiter for passing large text into a step doc strings may be multi-line
@	prefix for a tag: @ tags may be placed before Feature or Scenario sections tags are used to filter scenarios
#	prefix for a comment line comments are not read by the Gherkin parser

The next post will walk through several Gherkin examples to show how to write good scenarios.