Gherkin

How works Cucumber ?#

Gherkin uses a set of special keywords to give structure and meaning to executable specifications. Each keyword is translated to many spoken languages; in this reference we’ll use English.

Most lines in a Gherkin document start with one of the keywords.

Comment lines are allowed anywhere in the file. They begin with zero or more spaces, followed by a hash sign (#) and some text. Comments do have to start on a new line.

Feature: Go back to home
Go back to home from different screen.

    # We can comments scenario/steps with '#' char
    Scenario: Back to home from Fip
        Given i start on "fip" screen
        When i press "home"
        Then "home" screen is displayed
        And "rail" item 0 is focused

    Scenario: Back to home from Live Player
        Given i start on "live player" screen
        When i press "home"
        Then "home" screen is displayed
        And "rail" item 0 is focused

The trailing portion (after the keyword) of each step is matched to a code block, called a step definition.

Keywords#

Each line that isn’t a blank line has to start with a Gherkin keyword, followed by any text you like. The only exceptions are the feature and scenario descriptions.

The primary keywords are:

• Feature
• Scenario
• Given, When, Then, And, But (steps)
• Scenario Outline
• Examples

There are a few secondary keywords as well:

• "" (Doc Strings)
• | (Data Tables)
• @ (Tags)
• # (Comments)

Feature#

The purpose of the Feature keyword is to provide a high-level description of a software feature, and to group related scenarios.

The first primary keyword in a Gherkin document must always be Feature, followed by a : and a short text that describes the feature.

You can add free-form text underneath Feature to add more description.

These description lines are ignored by Cucumber at runtime, but are available for reporting (They are included by default in html reports).

Feature: Go back to home
Go back to home from different screen.

    Scenario: Back to home from Fip

The name and the optional description have no special meaning to Cucumber. Their purpose is to provide a place for you to document important aspects of the feature, such as a brief explanation and a list of business rules (general acceptance criteria).

The free format description for Feature ends when you start a line with the keyword Scenario or Scenario Outline (or their alias keywords).

Descriptions#

Free-form descriptions (as described above for Feature) can also be placed underneath Example/Scenario and Scenario Outline.

You can write anything you like, as long as no line starts with a keyword.

Example#

This is a concrete example that illustrates a business rule. It consists of a list of steps.

The keyword Scenario is a synonym of the keyword Example.

You can have as many steps as you like, but we recommend you keep the number at 3-5 per example. If they become longer than that, they lose their expressive power as specification and documentation.

In addition to being a specification and documentation, an example is also a test. As a whole, your examples are an executable specification of the system.

Examples follow this same pattern:

• Describe an initial context (Given steps)
• Describe an event (When steps)
• Describe an expected outcome (Then steps)

Steps#

Each step starts with Given, When, Then, And, or But.

Cucumber executes each step in a scenario one at a time, in the sequence you’ve written them in. When Cucumber tries to execute a step, it looks for a matching step definition to execute.

Keywords are not taken into account when looking for a step definition. This means you cannot have a Given, When, Then, And, or But step with the same text as another step.

Given#

Given steps are used to describe the initial context of the system - the scene of the scenario. It is typically something that happened in the past.

When Cucumber executes a Given step, it will configure the system to be in a well-defined state, such as creating and configuring objects or adding data to a test database.

The purpose of Given steps is to put the system in a known state before the user (or external system) starts interacting with the system (in the When steps). Avoid talking about user interaction in Given. If you were creating use cases, Given would be your preconditions.

It’s okay to have several Given steps (use And or But for number 2 and upwards to make it more readable).

Examples:

• i start on “my screen” screen

When#

When steps are used to describe an event, or an action. This can be a person interacting with the system, or it can be an event triggered by another system.

Examples:

• i press “OK”
• i press “OK” -screen change-

Then#

Then steps are used to describe an expected outcome, or result.

The step definition of a Then step should use an assertion to compare the actual outcome (what the system actually does) to the expected outcome (what the step says the system is supposed to do).

An observation should be on an observable output. That is, something that comes out of the system (report, user interface, message), and not something deeply buried inside it (like a database).

Examples:

• “list view” item 0 is focused
• “view” is shown

You should only verify outcome that is observable for the user (or external system), and databases usually are not.

And, But#

If you have several Given, When, or Then, you could write:

Example: Multiple Givens
  Given i start on "my screen" screen
  Given "rail" item 0 is focused

Or, you could make it read more fluidly by writing:

Example: Multiple Givens
  Given i start on "my screen" screen
  And "rail" item 0 is focused

Scenario Outline#

The Scenario Outline keyword can be used to run the same Scenario multiple times, with different combinations of values. Copying and pasting scenarios to use different values quickly becomes tedious and repetitive.

Scenario: Display vod rail with movies
  Given i start on "movie vod" screen
  And "rail" item 0 is focused

Scenario: Display vod rail with series
  Given i start on "series vod" screen
  And "rail" item 0 is focused

We can collapse these two similar scenarios into a Scenario Outline.

Scenario outlines allow us to more concisely express these scenarios through the use of a template with < > delimited parameters.

Scenario Outline: Display vod rail
  Given i start on "<vod_type_screen>" screen
  And "rail" item 0 is focused

  Examples:
  | vod_type_screen |
  |       movie vod |
  |      series vod |

A Scenario Outline must contain an Example (or Scenario) section. Its steps are interpreted as a template which is never directly run. Instead, the Scenario Outline is run once for each row in the `Example section beneath it (not counting the first header row).

The steps can use <> delimited parameters that reference headers in the examples table. Cucumber will replace these parameters with values from the table before it tries to match the step against a step definition.