Using BDD (Gherkin Stories)

Gherkin Editor in Opkey

A typical Gherkin Editor is an editor where users can create their stories, in Opkey, incorporates all the explained features of Gherkin language. The following snapshot gives the overview of the Gherkin feature in Opkey.

Getting Started with BDD in Opkey

In this segment, you will be explained about writing stories and adding steps in Gherkin Feature in Opkey. Please note, Opkey, here, still focuses on Zero – Programming, and you don’t need to code the step definition file for every steps used in Gherkin Feature specified by BDD. Firstly, you need to add Gherkin Feature in your project.

Gherkin syntax begins with ‘Feature'. As soon you start to write ‘Feature’, suggested keywords matching will appear in the dropdown, which you can select through ‘Tab’ key. A brief description of that very key is shown in tooltip box explaining its description and usage. Though adding 'Feature' file is not mandatory to add in your feature file, however it is recommended as it explains the functionality to be tested. After selecting ‘Feature’ you can provide a title and a free-text high level description of the feature of your application that is detailed in the file. Feature’ describes about the feature of a website to be validated.

Now, the next step is write the stories regarding the scenarios or describe the business value due to this feature in your application. Note that the next 3 lines which are ‘In order to’, ‘as a’, ‘I want to’ in the following screenshot aren’t meant to be associated with Function Libraries. These lines makes it more intuitive and provides the context to the people who are reading the feature.As soon as you press ‘Enter’ key, lines ‘In order to’, ‘as a’ ‘I want to’ will appear subsequently upon pressing ‘Enter’ Key. In the following instance, description have been provided against all the three lines

The next step is to add ‘Background’, as described and shown in the tooltip box in the above Pic, it acts like an untitled scenario containing number of steps and during the execution it is run before each of the scenarios. In the above screen shot, ‘Background’ includes steps ‘Given’ & ‘And’. Notice that the line against ‘Given’ & ‘And’ have been underlined, showing that they are not associated. You can associate these lines using Step Associator or ‘Generate All Steps’. Before proceeding further, you should know one of the important part .i.e. Association of steps

Step Association:

In Opkey, Step association refers to associating of line (step with lines) with a predefined or new function library. In function library, user can create their own step definition file for their used steps in the form of functions, which can be associated to the lines used in Gherkin feature. In the previous snapshot pic, user is notified that his lines are not associated with any step definition i.e. function library. To associate the same, user can either right click on the same line or can generate function libraries for all lines which are not associated using Submit 'Create all Statements'

Upon right click, ‘Link to Function Library’ option is enabled and after selecting it ‘Step Associator’ window would open.

Now, to associate the lines, you can either generate or select a previously created function library. The function library corresponding to the line are getting generated using ‘Generate’ button. Notice that after the function library gets generated, the lines appearing previously disappears as soon it gets mapped with newly generated function library.

Using ‘Generate all Steps’ button:

This is mostly used when you have written the stories and steps containing scenarios and conditions in Gherkin Feature, after then you wish to generate all the steps for the preconditions used in it. An ideal example for this is: A business analyst have listed the feature of his application to be checked in various scenarios, he has written it using Gherkin Feature in Opkey and then assigns a test engineer to validate his scenarios.

When you press on ‘Generate all steps’ button, ‘Step Associator’ window would open as in the following screenshot.

After clicking on ‘Generate’ button, function libraries associated with the highlighted steps in Gherkin feature would be created.

In the above snapshot, ‘Step Associator’ window is shown with buttons:

Create a new FL file : This button is used to create new function library with same name of the selected line. For example, statement : ' And User clicks on 'login' link 'will generate a function library of the name ‘User clicks on ‘Login’ link’
Create new folder : This button is used to create a new folder.
Select FL file : This button is used to select the chosen FL file which is enabled only when user selects any existing function library in Step Associator window. On clicking it, would associate that very function library with selected line in Gherkin feature.
Refresh : This button is used to refresh the existing files of Function Library with new changes if done any.
Close : This button is used to close the Step Associator window.

Associated Function Library:

The associated function library contains the step definition file of associated steps of Gherkin Feature. To add steps, go to the associated function library and add corresponding steps to the associated line.

For line "Given user opens the page https://opkey.crestechglobal.com", the associated function library contains step: ‘OpenBrowser’ with arguments as ‘Firefox’ and ‘https://opkey.crestechglobal.com’ for ‘Browser’ and ‘url’ respectively. Similarly for step And user clicks on ‘Login’ page it contains the ‘ClickLink’ keyword mapped to ‘Login’ object as shown below.

Now to add scenario, Press ’Esc’ button, and then Press ‘Enter’ key , ‘Scenario’, ‘Scenario Outline’ , ‘And’ & ‘When’ would appear in the drop down.
Select ‘Scenario’ and add a description against it. Please note that description against ‘Scenario’ is not mandatory but make sure that at least one ‘Scenario’ is included in Gherkin feature or it won’t execute.
In the given screenshot, ‘Scenario’ along with description is included. ‘Scenario’ can be treated as ‘Test Scenarios’ in Gherkin feature too.
Now the next step is to add ‘When’, which describes the action to be performed, following screen shot explains that user wish to enter login credentials and click on submit button
Similarly as explained in the above steps, Generate function library for the above line which would automatically map it.Similarly, add steps to its mapped function library corresponding to that associated line as given below in the screenshot..

In order to complete the scenario, user also needs to click on ‘Submit’ button. So, a new line And user click on submit button is added and subsequently, a new function library is generated using ‘Step Associator’ window. Now as done in previous steps, add definition to its mapped function library using predefined keywords of Opkey, to perform similar action corresponding to its line in Gherkin Feature.
Now comes ‘Then’, which checks the outcome of the actions performed in previous steps, in the following screen shot, it is validated that user should be able to login in his account successfully.
Please keep in mind that it is not mandatory to map the un-associated lines with newly generated function library of same name, it can also be mapped with existing function library whose definitions may not match with lines. Also, ‘Given’, ‘When’ ‘And’ & ‘Then’ can be mapped with any of existing function libraries whose behavior don’t justify the steps written in Gherkin Feature in Opkey, it’s up to user how he maps the lines as per their behavior, action and outcome.
Before ‘Then’ is added, for instance, user has already created a function library ‘login success’ with steps performing validation on the successful login process.
In the above screen shot, user has performed validation using keyword ‘VerifyObjectExists’ with object ‘Logout’, to ensure the scenario of successful login.
Now a line ‘Then user should log in successfully’ is added in the Gherkin Feature and mapped with existing function library ‘login success’ using Step Associator.
Now it can be executed as a scenario is completed, you can also more scenarios similarly. Upon pressing the ‘Run Now’ button ‘Execute Now’ window would appear with settings which user can choose.Using Scenario Outlines.
Scenario Outlines are used to iterate the same scenarios with different values. For instance, in the above example, if user wishes to check the functionality of login page for three un-registered users, he doesn’t need to copy paste the same scenarios every time with different values.
In the following screen shot, user has used ‘Scenario Outlines’ for three users

The Scenario Outline uses placeholders, which are contained within <> in the Scenario Outline’s steps. In the above screenshot user has provided 3 values for username and passwords, which upon execution, would iterate three times for values of each row in ‘Examples’

Please note that, you need to manually create table using ‘|’ as shown above and the table must be within ‘Examples’ section, which must be within ‘Scenario Outline’

Upon execution, only the steps within ‘Scenario Outline’ would iterate as per the rows defined in the table within ‘Examples’It is mandatory that the variable, which needs to be iterated, must be enclosed in placeholders i.e. ‘<>’ as shown in the above image, variables ‘username’ & ‘password’ is included within placeholders ‘<>’.

Similarly, a ‘Scenario Outline’ without table in ‘Examples’ or without ‘Examples’ would show invalid syntax with red underlined lines.

Syntax Errors of Gherkin Feature in OpKey:

Red underlined lines represents that the written text is unsupported in Gherkin feature or a mandatory step is missing.

In the above screenshot, tooltip shows error message “Statement not associated". Placeholder <username> must be defined in the "Examples" table. The green underlined lines shows that the lines are not associated with any function library as shown in given figure

Using Data Repository in Scenario Outlines:

One of the most prominent feature of OpKey i.e mapping of data tables of data repository in Scenario Outline. Using this feature, you don't require to manually create a table, you can use OpKey's inbuilt feature 'Link to Data Repository' which automatically maps the table of Data Repository with the defined rows and columns in 'Examples' in Gherkin Feature.

Here, the red line of the ‘Given’ statement signifies that a specific function library has been mapped with many statements within that project.

If a function library say ‘fl1’ is mapped with statements ‘Given page xyz is opened’ and ‘Given page abc is opened’, then both statements will get get underlined in red which suggests that associated function library is also associated with other statements, a tooltip depicting the same info would also appear.

In the above snapshot, in declaration of 'Examples', the columns name 'email' and 'password are declared and as the tooltip suggests it is mapped with 'valid user1' (data repository) .

The following guidelines will help you mapping a data repository with your statements in your 'Scenario Outline'.

Consider a following scenario as given in the snapshot below:

In the above scenario, a user wants to validate if registered users are able to login and logout successfully, but user has a long list of registered users, so in the scenarios similar to this, first statements are created and associated with respective function libraries. Now as you know it is mandatory to include 'Examples'.

After declaring 'Examples' with name of columns or variables to be iterated, the feature file would appear like in the above snap. Notice that the tool tip suggests 'Examples table not associated' appears which denotes that no data repository have been associated with the table.

You can provide data in two ways -

(1) On the tool tip of project explorer window, opens 'Step Associator' window

(2) You can right click next to 'Examples' section and select 'Link to Data Repository' as shown in the following figure:

After clicking on it, 'Step Associator' window, which is same as the previously explained 'Step Associator' window, opens up. The only difference is the file/folder hierarchy of module which is Data Repository appears. Please refer the following snapshot.

You can either create a folder or file of data repository within root folder of Data Repository or you can select existing data repository.

Click Create. Data repository with the same name as that of Scenario Outline is created within the root folder. You can also create a separate folder by clicking on Create Folder icon. For example, in the following snapshot, data repository 'valid user 1' has been created in the root folder of Data Repository.

After selecting Data Repository, the stories in your feature would appear as shown in the snapshot below:

After creating data repository, input parameters would be created in the associated Function Library. You need to enter value within Input Parameter & then map it with the test step. During test execution of Gherkin feature, that associated data values will be picked. If you are providing data itself from the Example table then you need to remove mapping and provide data in respective format. Ignore the warning message "WARNING: Examples table not associated".

Executing Gherkin Story :

Now you can execute your Gherkin script by using Run/Debug button, on pressing these buttons Execute Now wizard would appear asking you the mandatory fields to be filled and other configurations to be set prior execution. In the above snapshot, manual data table for variable 'email' and 'password' has been created. Observe that irrespective of the of 'Examples', which is not linked to Data Repository, will automatically consider the columns in the manual table and would iterate the values corresponding to the declared columns.

You can execute multiple Gherkin scripts together by adding them within a Suite.

How to skip a particular test scenario during Gherkin file execution?

While working on the Gherkin feature in OpKey, you can skip a particular Gherkin test scenario from the test execution. In order to do that, you need to follow below given instructions:

Write your complete Gherkin Feature test scenarios
Write @Skip as tag above to the Scenario Outline and save the Gherkin file.
Execute this Gherkin Feature file.

Once the test execution of this Gherkin file has completed, you can view the execution result. The desired Gherkin test scenario gets skipped from test execution successfully.
In this scenario, there is only a single test scenario that is to be skipped. It results incomplete test execution, as expected.