The Gherkin Language: An Overview

Gherkin is a human-readable, domain-specific, business-oriented language that Cucumber interprets. Similar to other programming languages, Gherkin too uses a set of reserved keywords to give structure and meaning to Scenarios. In Cucumber, a Feature file is responsible for holding all the tests (Scenarios), wherein each line within it has to start with these keywords. The keywords are:

• Feature

• Background

• Scenario / Scenario Outline with Examples

• Given, When, Then, And, But (actual steps)

Before we begin understanding the above keywords in depth, please note that this blog is a continuation of our blog series on Behat.

Feature

Every feature file starts with the keyword Feature: This section serves the purpose of describing one of the many features of the application. The name and description of the feature are ignored by Cucumber at runtime and should be used for describing business rules, Acceptance Criteria and important information related to the feature. Cucumber will ignore all the lines after Feature: until it locates the first Scenario. 

Example of a Feature section

Background

This is an optional section in a feature file. A Background is used whenever all the scenarios in a feature file begin with the same set of step(s). By defining a Background section, not only does the Feature file look cleaner, but also the maintenance part becomes easier. If there are any changes to a feature that is common across all the scenarios, you just need to modify the Background steps and the change would reflect in all scenarios. A Background is run once before every Scenario and runs after @BeforeScenario hook if any.

Example of a Background section

Scenario

Scenarios are a way of defining multiple Business rules related to a feature, this is how it can also serve as project specification and documentation. Each feature file consists of multiple scenarios and each Scenario consists of multiple steps. Scenarios are nothing but tests in terms of Automated testing.

Example of a Scenario section

Scenario Outline

Scenario Outline is a Scenario which runs the same set of steps against multiple combinations. So, in terms of testing, it is a test which is executed several times with different inputs. It has an Examples section which is used to list all the different inputs to be consumed by the Scenario Outline. For instance, if we take the example listed in the Background section of this blog, the Scenario Outline would look like:

Example of a Scenario Outline

We have just one parameter in our example. However, a Scenario Outline can have multiple parameters too.

Steps

Each step in Gherkin starts with either Given, When, Then, And or But. Once the keyword Scenario is identified, Behat executes all the steps in sequence for that scenario. The keywords Given, When, Then, And or But have been added only for improving readability and are not considered by Cucumber while running the Scenario. To elaborate, step Given I am on the homepage and When I am on the homepage, both mean the same since it is going to try to match the step definition to its regular expression defined in the corresponding PHP file (which is part of the Behat library.)

Below are a few tips on when and how to use these keywords in a scenario:

1. Given statements are generally used to define the initial context of a system. For example, if you want to test a checkout scenario, you can write: 

   "Given a product has been added to cart"

2. When statements are used to describe an event or an action. For example, again to test the same checkout scenario for a logged-in user, the steps can be:

   Given I am an authenticated user
   When I add a product to cart

3. Then steps generally describe the desired outcome or result. In terms of automation, Then statements are assertions. Without assertions, the test doesn't really make much sense. For example:

   Given I am an authenticated user
   When I add a product to cart
   Then I should be able to successfully checkout

4. And and But steps compliment any additional requirements. For example: On the checkout page, the user is able to view offers related to his City selected in the default address. However, the user should not be able to see offers related to other cities.

   Given I am an authenticated user
   And I go to product listing page
   When I add an in-stock product to cart
   Then I should be able to successfully checkout
   And I should be able to see offers related to my city
   But I should not be able to discounts offered for other cities

How does it work?

Now that we have understood Gherkin well enough, let us see how Gherkin statements are interpreted by any tool. Consider one of the Login scenarios that was written in Part 2 chapter of this blog series, which goes as:

In this instance we are using Behat as our tool. So, when the Behat runner reaches the first step of the scenario which is "Given I am on homepage" in this case, it looks for a matching pattern in a PHP file (MinkContext.php) and executes the method which is associated with that regular expression. For instance, the regular expression for the first step is defined as :
@Given /^(?:|I )am on (?:|the )homepage$/

@When /^(?:|I )go to (?:|the )homepage$/

where, it means that "Given am on homepage", "Given I am on homepage", "Given I am on the homepage", "When I go to homepage" and "When I go to the homepage", all these steps will execute the same method iAmOnHomepage() defined in MinkContext.php.

Below is a list of common ready-to-use steps (in-built methods) that come with Mink extension:

1. Visit Homepage / Any page

2. Reload current page

3. Move backward one page

4. Move forward one page

5. Press a button

6. Click a link

7. Fill value in a field

8. Fill values in multiple fields

9. Select a value from the list

10. Select a second value from the same list

11. Check a checkbox

12. Uncheck a checkbox

13. Attach a file to a field

14. Verify page address

15. Verify URL

16. Verify Response Status Code is / not

17. Verify page contains / Does not contain a specific text

18. Verify a Checkbox is checked / unchecked

NOTE: The above list is not exhaustive and all the ready-to-use step definitions can be found in the MinkContext.php file or by typing the command vendor\bin\behat -dl in the command line from your Behat setup. The output of this command should look similar to the screenshot below (I have a few extra steps because of the Drupal extension.)

In the next chapter of this series, we will understand how to write custom step definitions like inserting wait statements, better assertions using the FeatureContext.php file.