Writing scenarios with Gherkin syntax

Applies to CucumberStudio Cloud, and to Enterprise ver. 3.3 - Last updated on June 28, 2021

CucumberStudio enables you to create executable specifications written in a language called Gherkin.

Gherkin is a plain-text language with a little extra structure. Gherkin is designed to be easy to learn by non-programmers, yet structured enough to allow concise description of examples to illustrate business rules in most real-world domains.

Here is a sample Gherkin document:

Feature: Account Holder withdraws cash
  Scenario: Account has sufficient funds
    Given the account balance is $100
      And the card is valid
      And the machine contains enough money
    When the Account Holder requests $20
    Then the ATM should dispense $20
      And the account balance should be $80
      And the card should be returned

The main keywords in Gherkin are:

  • Feature
  • Scenario
  • Given, When, Then, And, But (Steps)
  • Background
  • Scenario outline
  • Examples

Step 1: Activate the BDD mode

In your project settings panel, activate the BDD mode.

Activate the BDD mode from the project settings

Click the image to enlarge it.

This will enable you to write scenarios using the Gherkin syntax. The step editor in the scenario page will create only action words (reusable steps) and interpret the Gherkin keywords.

Step 2: Create a feature

Your features are managed with folders to better organize your project.

CucumberStudio feature page

Click the image to enlarge it.

A feature has a description that provides the context. It is usually written this way:

As a [role]
I want [feature]
So that [benefit]

A feature contains one or many scenarios that describe its behaviors.

Step 3: Write a scenario with the Given/When/Then syntax

By getting the business users, the analysts, the testers and the developers to adopt this vocabulary of “given/when/then”, lots of ambiguities fall away and conversations become more efficient.

Let’s write our first step: given the account balance is “$100”

CucumberStudio test with Gherkin

Click the image to enlarge it.

CucumberStudio interprets and highlights the keyword Given. It will also consider $100 as a parameter because of the double quotes “my parameter value“. This way you’ll be able to reuse the same step in the future with a different value.

First step of a CucumberStudio test with Gherkin

Click the image to enlarge it.

And after a couple of seconds we get the following scenario.

CucumberStudio scenario

Click the image to enlarge it.

Note: The step editor comes along with a powerful suggestion capability that enables you to reuse existing steps and design scenarios with a consistent business terminology. It’s also possible to use free text parameters in steps.

Step 4: add examples and use scenario outline

Cloning scenarios to use different values can quickly become tedious and repetitive. Scenario outlines allow you to more concisely express these examples through the use of parameters and datatable. Using our previous scenario we can create 3 examples.

Example of a CucumberStudio datatable

Click the image to enlarge it.

When you create a new step, you can directly use the column name between “…” to use it as a parameter:

Add a step with a CucumberStudio variable as a parameter value

Click the image to enlarge it.

After the step validation, you can notice that the character = is automatically set before the column name. This indicates that the word after the = character is a variable that will be replaced by the matching datatable column value.

BDD with CucumberStudio datatable

Click the image to enlarge it.

You can also write an expression as a parameter value. This expression can use the datatable column names. For example, here, the parameter value is the addition of the value of the column x and the column y:

Datatable to use expression in CucumberStudio parameter value

Click the image to enlarge it.

Use expression as argument in CucumberStudio step

Click the image to enlarge it.

After clicking on View tests, you get a preview of your generated tests:

CucumberStudio step with expression interpretation

Click the image to enlarge it.

Now that we have the scenarios completed. Let’s execute them.

See Also

Create scenarios
Use action words
Best practices for scenario writing

Highlight search results