BDD 101: The Gherkin Language

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
  • 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
  • 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
  • step to define the preconditions (initial state or context)
  • should put the product under test into the desired state
  • may be parameterized
  • step to define the action to be performed
  • may be parameterized
  • step to define the expected result from the action taken by When
  • may be parameterized
  • 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
  • functions the same as And, but might be easier to read
  • interchangeable with And
  • 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
  • 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.


  1. Hello,I read your new stuff named “BDD 101: The Gherkin Language | Automation Panda” regularly.Your story-telling style is awesome, keep up the good work! And you can look our website about proxy server list.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s