BDD Guidelines - writing features - gherkin language

Some of us here are working on the BDD guidelines that should be followed:
Would be interested to hear if anyone has thoughts to share:


  1. Explain in the feature file what the feature is about, just after the “Feature:” before proceeding to the scenarios (preferably in “In order/As a/I want” format).
  2. Write high-level scenario steps by raising the level of abstraction and focus on the “what” rather than the “how”
    • don’t mention UI elements
    • don’t mention ‘click’ or other actions linked to specific UI elements
    • the scenario should remain valid if the UI is replaced with a new UI tomorrow
    • avoid very detailed steps where possible (helps to focus and avoid clutter)
  3. Write scenarios using business language rather than using technical language so that it can be understood by everyone.
  4. Write scenarios from the perspective of the person who will use or needs the feature (not always a member or user). Use 'I' and explain who the 'I' is in 'Given' step. 
  5. Each and every scenario needs to be independent, i.e. scenarios should not depend on other scenarios or data created by other scenarios.
  6. Don't mention features or actions which are not related to the actual feature under test.
    • Example: Scenario is to check the balance is displayed currently in a user account. Before checking the balance, user needs to login to check the balance but Login is not part of the check balance scenario.
  7. Use Scenario Outline when you have several scenarios that follow exactly the same pattern of steps, just with different input values or expected outcomes.
  8. Scenario Outline examples should be easy to understand. Column names should be meaningful (e.g. | Contact Method | Enquiry Type | instead of | value1 | value2 | ), so that the steps are understandable.
  9. Scenarios need to be environment independent.
  10. Write scenarios for testing happy paths and important error cases.
  11. Avoid typos and always use grammatically correct English.


  1. Wherever possible steps should be reused. This can also be achieved by
    • parameterizing (if applicable)
    • keeping it short and simple
  2. Whenever a feature or behaviour changes the existing scenarios needs to be updated (from a latest branch in TFS)
  3. Actions, which are not directly related to the scenario should be handled outside the actual scenario: 
    • Actions like login should be handled part of Background or hooks.
    • Setup and teardown should be part of hooks and should not be part of the scenario.

Bad Example 1

Scenario Outline: Detect agent type based on contract number (single contract found)
Given I am on the "Find me" page
And I have entered a contract number
When I click the "Continue" button
And a contract number match is found
And the agent type is 
Then the contract number field will become uneditable
And the "Back" button will be displayed
And the following  and  will be displayed

| DistributorType | input field type | text                            |
| Broker          | Date of birth    | Please enter your last name     |
| TiedAgent       | Last name        | Please enter your date of birth |

Good Example 1

Same test as in Bad Example 1, but with focus on a single business rule and without UI stuff
Scenario: Customer has a broker policy so DOB is requested
Given I have a "Broker" policy
When I submit my policy number
Then I should be asked for my date of birth

Scenario: Customer has a tied agent policy so last name is requested
Given I have a "TiedAgent" policy
When I submit my policy number
Then I should be asked for my last name

Scenario Outline Example

Scenario Outline: Withdraw fixed amount
Given I have  in my account
When I choose to withdraw the fixed amount of 
Then I should receive  cash
And the balance of my account should be 
| Balance | Withdrawal | Received | Remaining |
| $500    | $50        | $50      | $450      |
| $500    | $100       | $100     | $400      |
| $500    | $200       | $200     | $300      |



Popular posts from this blog

Trim / Remove spaces in Xpath?

Complete list of Serenity properties

XPATH for IE / internet explorer