Skip to content

Gherkin

Gherkin seeks to bridge the ever-present divide from business and technology. It is high-level business language that uses plan English to describe user flows. Following a prescriptive Given / When / Then pattern, any steps can be written to describe actions.

  • Gherkin is a plain English business.
  • Uses a set of special keywords to give structure and meaning to executable specifications.
  • Specific steps map to automation using Cucumber.
  • Serves as living documentation to describe features of the application.

What is a Feature File

A feature file is a collaboration point for conversation and examples. It lives as code and contains Gherkin scenarios. These scenarios serve as living documentation and test automation using Cucumber.

Gherkin Keywords

Although Gherkin uses plain English, there is a small library and minimal syntax to provide meaning and action.

Keyword Description
Feature High-level description the feature of the application. There is one Feature per feature file.
Scenario Describes an explicit user flow that supports the feature.
Given Pre-condition for the scenario
When User action or test flow
Then The expected outcome of the scenario

Sample

Gherkin is really easy to write and understand. The simplicity of the Given/When/Then structure forces common language and understanding across business and technology and abstracts implementation details.

Scenario: Successful withdrawal from an account
    Given I have $100 in my account
    When I request $20
    Then $20 should be dispensed
    And my account balance should be $80

Refactoring

Scenario Outline and Examples

Often teams will want to run the same scenario but use different datasets or slightly alter the user flow. Maintaining multiple scenarios can get very expensive and confusing very quickly. Instead, Gherkin allows you to collapse similar scenarios and parameterize values with a data table.

Scenario Outline: Successful withdrawal from an account
    Given I have |starting| in my account
    When I request |request|
    Then |request| should be dispensed
    And my account balance should be |ending|

Examples:
    | starting | request | ending |
    | 100      | 20      | 80     |
    | 100      | 100     | 0      |
Scenario Outline must be accompanied by an Examples data set and vice versa.

Background

When the same set of steps are used for every scenario in the feature file, the shared steps can be extracted and placed into a setup section to run before each scenario.

Background: login to the application
    Given I am on the login page
    Given I enter username and password credentials

Scenario: I should be able to make a bill payment
    When I pay my bill in full
    Then I should have a balance of 0

Scenario: I should be able to cancel a bill payment
    When I cancel a bill payment
    Then I should see my list of bills due

There can be no more than one Background per feature file

Best Practices

  • Keep feature files readable, understandable, and maintanable
  • Use business domain language
  • Keep scenarios short and focus on acceptance criteria
  • Focus on the What not the How
  • Use backgrounds, but keep them short