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 @panda 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
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: Andy 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
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.
Automation Panda 
What do you mean by parameterization?
LikeLike
“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.
LikeLike
can i use @parameterize with gherkin to pass multiple variable instead of using examples table
LikeLike
Most BDD frameworks like Cucumber and SpecFlow will not allow you to use a tag to replace examples tables. Examples tables represent a “loop”, repeating the scenario steps once for each row of inputs.
LikeLike
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++?
Thanks in advance,
Jose
LikeLike
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.
LikeLike
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.
LikeLike
Absolutely yes! Check out this page: https://github.com/cucumber/cucumber/wiki/Step-Definitions
LikeLike
Hi Andy,
Thank you, sharing your BDD knowledge with us; highly educational, especially your inclusion of how to add BDD to existing processes!
You say: “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.”
I’m not sure I understand what you are trying to convey. I know the scope difference between the two, but the contrast of “data structures” vs. “parameterization” is lost on me. What am I missing?
Thanks,
Arnoud
LikeLike
Hi Arnoud,
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.
I hope that makes more sense!
Sincerely,
Andy
LikeLike
Hi Andy,
Thanks for the cicatrisation, I was indeed reading more into your comment. You’re expansion us exactly how I was thinking about it.
Arnoud.
LikeLike
That was supposed to say clarification, but my mobile spell checker decided differently. 🙂
Arnoud.
LikeLike
Hi Andy,
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.
Hope that made sense.
LikeLike
If you can describe it, then you can do it! Try writing some scenarios your self and then paste them here, and I can review.
LikeLike
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.
LikeLike
Hey Andy,
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?
LikeLike
You could write it like that, but I’d probably write it like this:
Given the user has filled out the form
When the user clicks “Submit”
And the user clicks “Yes, I’m sure” in the “Are you sure?” modal
Then a confirmation message appears
The “And” step above would make sure the modal appears in addition to clicking the desired choice.
LikeLike
Hello, love these Gerkhin series up to know!
One question: Don’t you have a little mistake in the end of the Scenario Outline section?
“Step tables provide input data structures, whereas Examples tables provide input parameterization.”
Shouldn’t be vice versa? You adding testing data in the Examples table and parametrization is defined in Steps. Or Am I completely wrong?
LikeLike
Thanks for reading, Peter!
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.
LikeLike
Hello. THanks for your great content. I would like to know how you handles login on pages that needs login before access. Thanks in advance.
LikeLike
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”.
LikeLike