Menu

BDD 101: Gherkin By Example

Gherkin is learned best by example. Whereas the previous post in this series focused on Gherkin syntax and semantics, this post will walk through a set of examples that show how to use all of the language parts. The examples cover basic Google searching, which is easy to explain and accessible to all. You can find other good example references from Cucumber and Behat. (Check the Automation Panda BDD page for the full table of contents.)

As a disclaimer, this post will focus entirely upon feature file examples and not upon automation through step definitions. Writing good Gherkin scenarios must come before implementing step definitions. Automation will be covered in future posts. (Note that these examples could easily be automated using Selenium.)

A Simple Feature File

Let’s start with the example from the previous post:

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

This is a complete feature file. It starts with a required Feature section and a description. The description is optional, and it may have as many or as few lines as desired. The description will not affect automation at all – think of it as a comment. As an Agile best practice, it should include the user story for the features under test. This feature file then has one Scenario section with a title and one each of Given–When–Then steps in order. It could have more scenarios, but for simplicity, this example has only one. Each scenario will be run independently of the other scenarios – the output of one scenario has no bearing on the next! The indents and blank lines also make the feature file easy to read.

Notice how concise yet descriptive the scenario is. Any non-technical person can easily understand how Google searches should behave from reading this scenario. “Search for pandas? Get pandas!” The feature’s behavior is clear to the developer, the tester, and the product owner. Thus, this one feature file can be shared by all stakeholders and can dispel misunderstandings.

Another thing to notice is the ability to parameterize steps. Steps should be written for reusability. A step hard-coded to search for pandas is not very reusable, but a step parameterized to search for any phrase is. Parameterization is handled at the level of the step definitions in the automation code, but by convention, it is a best practice to write parameterized values in double-quotes. This makes the parameters easy to identify.

Additional Steps

Not all behaviors can be fully described using only three steps. Thankfully, scenarios can have any number of steps using And and But. Let’s extend the previous example:

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
And the related results include "Panda Express"But the related results do not include "pandemonium"

Now, there are three Then steps to verify the outcome. And and But steps can be attached to any type of step. They are interchangeable and do not have any unique meaning – they exist simply to make scenarios more readable. For example, the scenario above could have been written as Given-When-Then-Then-Then, but Given-When-Then-And-But makes more sense. Furthermore, And and But do not represent any sort of conditional logic. Gherkin steps are entirely sequential and do not branch based on if/else conditions.

Doc Strings

In-line parameters are not the only way to pass inputs to a step. Doc strings can pass larger pieces of text as inputs like this:

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
And the result page displays the text
"""
Scientific name: Ailuropoda melanoleuca
Conservation status: Endangered (Population decreasing)
"""

Doc strings are delimited by three double-quotes ‘”””‘. They may fit onto one line, or they may be multiple lines long. The step definition receives the doc string input as a plain old string. Gherkin doc strings are reminiscent of Python docstrings in format.

Step Tables

Tables are a valuable way to provide data with concise syntax. In Gherkin, a table can be passed into a step as an input. The example above can be rewritten to use a table for related results like this:

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
And the following related results are shown
| related |
| Panda Express |
| giant panda |
| panda videos |

Step tables are delimited by the pipe symbol “|”. They may have as many rows or columns as desired. The first row contains column names and is not treated as input data. The table is passed into the step definition as a data structure native to the language used for automation (such as an array). Step tables may be attached to any step, but they will be connected to that step only. For good formatting, remember to indent the step table and to space the delimiters evenly.

The Background Section

Sometimes, scenarios in a feature file may share common setup steps. Rather than duplicate these steps, they can be put into a Background section:

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

Since each scenario is independent, the steps in the Background section will run before each scenario is run, not once for the whole set. The Background section does not have a title. It can have any type or number of steps, but as a best practice, it should be limited to Given steps.

Scenario Outlines

Scenario outlines bring even more reusability to Gherkin. Notice in the example above that the two scenarios are identical apart from their search terms. They could be combined with a Scenario Outline section:

Feature: Google Searching
As a web surfer, I want to search Google, so that I can learn new things.
Scenario Outline: Simple Google searches
Given a web browser is on the Google page
When the search phrase "<phrase>" is entered
Then results for "<phrase>" are shown
And the related results include "<related>"Examples: Animals
| phrase | related |
| panda | Panda Express |
| elephant | Elephant Man |

Scenario outlines are parameterized using Examples tables. Each Examples table has a title and uses the same format as a step table. Each row in the table represents one test instance for that particular combination of parameters. In the example above, there would be two tests for this Scenario Outline. The table values are substituted into the steps above wherever the column name is surrounded by the “<” “>” symbols.

A Scenario Outline section may have multiple Examples tables. This may make it easier to separate combinations. For example, tables could be added for “Planets” and “Food”. Each Examples table is connected to the Scenario Outline section immediately preceding it. A feature file can have any number of Scenario Outline sections, but make sure to write them well. (See Are Multiple Scenario Outlines in a Feature File Okay?)

Be careful not to confuse step tables with Examples tables! This is a common mistake for Gherkin beginners. Step tables provide input data structures, whereas Examples tables provide input parameterization.

Tags

Tags are a great way to classify scenarios. They can be used to selectively run tests based on tag name, and they can be used to apply before-and-after wrappers around scenarios. Most BDD frameworks support tags. Any scenario can be given tags like this:

Feature: Google Searching
As a web surfer, I want to search Google, so that I can learn new things.
@automated @google @pandaScenario: 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

Tags start with the “@” symbol. Tag names are case-sensitive and whitespace-separated. As a best practice, they should be lowercase and use hyphens (“-“) between separate words. Tags must be put on the line before a Scenario or Scenario Outline section begins. Any number of tags may be used.

Comments

Comments allow the author to add additional information to a feature file. In Gherkin, comments must use a whole line, and each line must start with a hashtag “#”. Comment lines may appear anywhere and are ignored by the automation framework. For example:

Feature: Google Searching
As a web surfer, I want to search Google, so that I can learn new things.
# Test ID: 12345
# Author: AndyScenario: 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

Since Gherkin is very self-documenting, it is a best practice to limit the use of comments in favor of more descriptive steps and titles.

Writing Good Gherkin

This post merely shows how to use the Gherkin syntax. The next post will cover how to write good Gherkin feature files.

35 comments

“Parameterization” is the ability to add parameters (also called “arguments”) to steps. In Gherkin, the best practice I recommend is to surround step parameters with double-quotes (“”).

Look at the first example in this post. The When and Then steps each have a parameter – in this case, the parameter’s value is “panda”. It could have just as easily been something else, like “elephant” or “python” or any other of your favorite animals. Parameterization allows steps to be more reusable. If I hard-coded the word “panda” into the step, then the step would only ever run searches for panda. However, since I parameterized the step to take any search term, I can now write tests that search for anything.

Hi Andy,
I downloaded your Notepad++ UDL for Gherkin and tried out some scenarios using tables. I noticed the row corresponding to the column name does not get highlighted in orange as shown in this post. Which is the expected behavior in Notepad++?

Hi Jose! That is expected behavior for the Notepad++ UDL. Unfortunately, Notepad++’s UDL feature is somewhat limited in how it can identify text for highlighting, so table header titles will not appear orange. I colored them orange in this post to point out how the parameter names are used.

Hi Andy I am new to Gherkin. Is there a way of reading parameters into Code ? I am using Cucumber with Selenium and Ruby. I am trying to find a way of reading the parameters in Gherkin and using them in my code. Thanks for your help.

I’m glad that you appreciate the blog! Please keep reading, and please share it with others!

For your question, don’t overthink it. A step table is just a way to pass a bunch of strings into a step (hence, a “data structure” of string inputs). A scenario outline, however is “parametrized” by its examples tables: each row is a combination of inputs (“parameters”) for the scenario. The scenario outline runs once for each example row.

If we look at the example in your section above labeled “Scenario Outlines”, how would you modify the Gherkin syntax if the business-requirement almost included “typeahead” functionality.

In other words, the business wants the search-results element (e.g. a table, a dropdown, whatever) to update in real-time (i.e. typeahead, predictive search, etc.) as each consecutive character is entered into the search-field. So if you were to enter the characters “re”, the element would show entries that include “are”, “real”, “red”, and so on, but if you then add “a” to the string (so the field now contains “rea”), the element would show only entries containing “rea” like “real” but hide “are” and “red”, etc.

Haven’t forgotten your challenge. Still wracking my brain about how one would write it. It doesn’t seem to be critical / required functionality, so for now I haven’t written anything involving typeahead functionality.

I’m curious how you would write an action in Gherkin that requires multiple steps (e.g., a confirmation modal appears). I’ll write an example in bad Gherkin to give you an idea of what I’m thinking about.

Given the user has filled out the form
When the user clicks “Submit”
Then an “Are you sure?” modal pops up
When the user clicks “Yes, I’m sure”
Then a confirmation message appears

It seems important not to ignore the fact that a modal appears, but it also seems like overkill to give it its own scenario. What do you think?

That’s no mistake. A step table is simply a multidimensional input for a step. It’s not a parametrization. On the other hand, an Examples table is a set of parametrized inputs. A Scenario Outline runs once for each row in the Examples table.

Hi Beto! The simplest way to handle login is with a Given step. If all scenarios in a feature file use it, then you can put it in a Background section. A more advanced way to handle login is to use a “before scenario” automation hook. In that case, you could make the login hook run for any scenarios containing a tag like “@login”.