BDD instructions writing standards

Introduction

This document describes rules for writing BDD instructions. It is used as a guideline for proper stated and formatted instructions. Natural language instructions used for BDD are not absolutely natural language instructions. They're actually "naturalized" form of some specific command with ability to variate some part. So, from the technical side of BDD the strict rules are still necessary to avoid different forms of absolutely the same phrases but with small differences. It's not essential for understanding but it is critical for technical implementation.

This document contains examples of correct and incorrect phrases. If some phrase is described as incorrect it only means that it violates the standards though it can be properly built from the language point of view. These standards do not teach English. They just describe which subset of possible phrases is taken as acceptable.

And again, standards are designed for uniformity only. There's no strict dogmatum in them. If some phrases seem to be more appropriate but they violate the rules it's OK to adjust rules to current needs rather than restrict needs with existing rules. The main thing is that there should be some uniform rule set which is kept within the project. Current document can be a basis for such standards

Terms and Definitions

• Feature file – file containing test definitions written in natural language. Typically it has *.feature extension
• Keyword – fully filled natural language phrase used in feature files
• Given\When\Then statement – the keyword starting with Given, When or Then word correspondingly
• Keyword implementation (implementation) – the actual code written with programming language and containing actions to be done for corresponding keyword
• Keyword binding (binding) – string or regular expression setting correspondence between keyword and it's implementation. Typically it's represented as an attribute (for C# BDD engines) or annotation (for Java BDD engines). The regular expression or string should be unique and match to specific set of keywords.

General rules

Rule 1.1

If there's a sequence of statements starting with the same word (Given\When\Then) only first occurrence should use Given\When\Then. All other phrases in the sequence should start with And or But words.

Examples:

• Incorrect:

  Given I'm logged into the system
  Given all services are up and running
  

  NOTE:
  second Given statement should start with "And"

  
  
• Correct:

  Given I'm logged into the system
  And all services are up and running
  

Rule 1.2

• "And" word is used for phrases in positive forms.
• "But" word is used for negative forms of keywords.
• When the sequence of phrases contains a mix of positive and negative phrases then series of "And" statements should be used prior to negative statement forms.

Examples:

• Incorrect:

  Given I'm logged into the system
  And1 no data is available in the database
  But2 all services are up and running
  And3 debug logging is turned on
  

  NOTE:
  1 - First "And" statement contains negative form. 2 - "But" statement contains positive form of expression. 3 - Second "And" statement goes after "But" statement within the same sequence

  
  
• Correct:

  Given I'm logged into the system
  And all services are up and running
  And debug logging is turned on
  But no data is available in the database
  

Rule 1.3

Keyword can contain varying part which is wildcarded in bindings and parametrized on implementation level.

• If the varying part is a string it MUST be quoted.
• If varying part is the number it MUST be without quotes.

Examples:

• Incorrect:

  Given I'm logged into the system as login/password1
  And I have "5"2 records in the table
  

  NOTE:
  1 - login and password are varying strings so they must be quoted. 2 - Second statement has the numeric value parametrized so no quotes are needed there

  
  
• Correct:

  Given I'm logged into the system as "login"/"password"
  And I have 5 records in the table
  

Rule 1.4

• If table is used for multiple data elements it MUST contain header.
• If data structure is passed via table the field names MUST be placed as table headers.
• Each keyword using array/table MUST end with colon character

Examples:

• Incorrect:

  When I add the following colors 1
  		 2
  	    |Red|
  	    |Green|
  	    |Blue|
  

  NOTE:
  1 - When statement here doesn't end with colon character 2 - Table contain only data without header

  
  
• Correct:

  When I add the following colors:
  	    |Color Name|
  	    |Red|
  	    |Green|
  	    |Blue|
  

Rule 1.5

The same action can be used under different contexts and can have corresponding Given\When\Then statements at the same time. In this case appropriate form MUST be used.

Examples:

• Incorrect:

  Given I should see1 I'm logged into the system
  When I'm logged into2 the system
  Then I make sure3 I'm logged into the system
  

  NOTE:
  1 - First statement fits more to the Then statement 2 - Second statement fits more to Given statement 3 - Third statement is rather applicable for When

  
  
• Correct:

  Given I'm logged into1 I'm logged into the system
  When I make sure2 I'm logged into the system
  Then I should see3 I'm logged into the system
  

Rule 1.6

• All test scenarios MUST fit the following structure:

  <Given block>
  <When-Then blocks sequence>
  

• Given statements MUST go first. There MUST be no When or Then statements prior to Given.
• When-Then blocks sequence represents actual test logic and it reflects the sequence of steps built in the form of "action-verification".
• Each When-Then block MUST be started with When statement.

Examples:

• Incorrect:

  When I log into the system
  Then I should see the home page
  Given I have 2 user accounts in the system1
  

  Given I'm logged into the system
  Then I should see the home page2
  

  NOTE:
  1 - the Given statement goes after When-Then. In this case it's more reasonable to place Given statement as pre-condition prior to When-Then 2 - the Then statement goes right after Given omitting When statement. In this case Given statement can be replaced with corresponding When statement

  
  
• Correct:

  Given I have 2 user accounts in the system
  When I log into the system
  Then I should see the home page
  

  When I log into the system
  Then I should see the home page
  

Given statements

Rule 2.1

Given statements represent initial state of the system and other pre-requisites. It MUST be expressed as state description and MUST be build with any form of verb "to be".

Examples:

• Incorrect:

  Given I log into the system
  

  NOTE:
  Given statement here describes action instead of the state, so it must be re-phrased

  
  
• Correct:

  Given I'm logged into the system
  

Rule 2.2

In case of passing array/table values the Given statement MUST contain phrase "the following"

Examples:

• Incorrect:

  Given there are colors like :
      |Color Name|
      |Red|
      |White|
      |Blue|
  

  NOTE:
  phrase "the following" is missing

  
  
• Correct:

  Given there are the following colors:
      |Color Name|
      |Red|
      |White|
      |Blue|
  

When statements

Rule 3.1

When statement represents actions to do. It MUST use active form of verbs.

Examples:

• Incorrect:

  When I'm logged into the system
  

  NOTE:
  this When statement operates with passive voice and actually describe the state rather than action so it should be re-phrased.

  
  
• Correct:

  When I log into the system
  

Rule 3.2

• When statements describe actions from the first person. Each When statement MUST start with "I" in case "When" word is used.
• In case "And" or "But" words replace "When" (see Rule 1.1.) the "I" word MUST be omitted.
• Keyword binding expression MUST skip "I" part to fit both form of corresponding keyword.

Examples:

• Incorrect:

  When I log into the system
  And I open home page
  

  NOTE:
  repetitive "I" must be removed

  
  
• Correct:

  When I log into the system
  And  open home page
  

Rule 3.3

In some cases the action actually represents some verification to be done prior to further steps and Then statement looks more appropriate here but it violates Rule 1.6. In this case there should be When statement starting with the phrase "I make sure"

Examples:

• Incorrect:

  Given I'm logged into the system
  Then I should see the home page is open
  When I navigate to services page
  

  NOTE:
  Here we make some verifications prior to any actions. "Then" statement here is quite reasonable as it describes verification. But such structure violates rule 1.6 when we MUST do actions prior to verifications. In this case we can re-phrase "Then" statement to describe action

  
  
• Correct:

  Given I'm logged into the system
  When I make sure the home page is open
  And navigate to services page
  

Rule 3.4

If array/table value is passed as a parameter the When statement MUST end with the phrase of the form: "the following " where item description is typically noun (subjects are allowed) describing the meaning of array/table data.

Examples:

• Incorrect:

  When I add   colors:
      |Color Name|
      |Red|
      |White|
      |Blue|
  

  NOTE:
  phrase "the following" is missing

  
  
• Correct:

  When I add the following colors:
      |Color Name|
      |Red|
      |White|
      |Blue|
  

Then statements

Rule 4.1

Then statement represents the expected behavior of the system. Similar to the Given statement it describes the state and it MUST be built with any form of verb "to be".

Examples:

• Incorrect:

  When I log into the system
  Then I open the home page
  

  NOTE:
  Then statement here describes action while it should be phrased as expected state description

  
  
• Correct:

  When I log into the system
  Then I should see the home page is open
  

Rule 4.2

• In case Then statement starts with "Then" word in feature file it MUST be followed with "I should see" phrase or "I shouldn't see" phrase in case of negative form.
• If "And" or "But" words are used (see Rule 1.1) the "I should see" phrase should be skipped.
• In case there's a mix of "And" and "But" statements (see Rule 1.2) the first "But" statement in the sequence MUST contain "I shouldn't see" phrase.

Examples:

• Incorrect:

  Then I should see the home page is open
  And I should see1 the left navigation menu is present
  And2 I should see1 no Admin tab is available
  

  NOTE:
  1 - "I should see" phrase is not needed in second and third lines as they're ambiguous. 2 - The third line contains negative form of expression so "But" statement looks more appropriate here

  
  
• Correct:

  Then I should see the home page is open
  And  the left navigation menu is present
  But  no Admin tab is available
  

Rule 4.3

If array/table value is passed as a parameter the Then statement MUST contain "the following " phrase right after "I should see" phrase (if it is used). The item description here is the noun (subjects are allowed) describing the meaning of array/table data

Examples:

• Incorrect:

  Then I should see the drop down list with the following options:
      |Option Name|
      |Option 1|
      |Option 2|
  

  NOTE:
  despite "the following" phrase is present it is located at the end of keyword

  
  
• Correct:

  Then I should see the following options are available in the drop down list:
      |Option Name|
      |Option 1|
      |Option 2|
  

Conclusion

The list of rules described in this document is not complete and can be updated or detalized according to each specific project needs or some aquired practices. The main aim is to define some baseline which helps identifying whether we write instructions in proper way. Also, strict guidelines help finding existing keywords by using fixed constructions as we know how the phrase we look for should be formulated. Anyway, standards are not a silver bullet but quite helpful guide for effective BDD usage.