IIBA IIBA-AAC – Techniques on delivery horizon Part 2

3. Gherkin notation

Syntax used for BDD a second scenarios is called Gerkin but it is also often referred to as given when then scenarios. So why is it called Gerkin? It is because of the framework called Cucumber. Cucumber is a test automation tool and framework that understands these gerkin scenarios and maps these scenarios written in plain English or any other language to a set of automation tests so that when the automation test suit is run, it can report back to acceptance criteria and tell you which of the criteria are passed and which of them are not. Let’s have a closer look at how it works. So, imagine you have a user story. As a customer who receives SMS bills, I want to see the due date and payment amount in the SMS so that I know when and how much to pay. This user story may have the following two acceptance criteria due date is present and the payment amount is present in the SMS for the story to be accepted.

 So if your development and testing teams are advanced enough, they may have a set of automated tests written. Those tests will automatically trigger the generation of an SMS and they will check that SMS for presence of the expected data. However, these tests live on their own in their test repository, while your requirements live in the backlog, maybe in tools like Jira or Trello or maybe even on a physical wall. So there is a gap between the two. Cucumber serves as a conduit to bridge this gap. For each test run. It will allow the test framework to go into your user stories and your acceptance criteria, find a corresponding automation test for each criterion and then execute that test. And after the test runs it will record the results of this test and put it against the corresponding acceptance criterion.

So effectively your business will see which of their acceptance criteria are passing and which of them are failing. However, this will work only on one condition that your acceptance criteria are written in a way that Cucumber can understand in a structured way called Gerkin. So let’s have a look at this structure on a very basic level. The Gherkin scenario describes a single interaction and consists of three parts or three steps given when and then given we’ll explain the conditions that must be true for this scenario to start. Then we’ll explain what are the triggers or activities that we need to cater for in our scenario and then we’ll explain what is the expected results that we are planning to check for. This is a very basic construct and if you don’t intend to use automation that is pretty much all you need to do. Just structure your acceptance scenarios in this format. First give the context, explain in. Given these things that must be true for this scenario. Then in then explain the sequence of activities or actions or events that you expect to see in your scenario.

And then in then describe what is the expected output or outcome of this scenario that needs to be tested for. However, if you plan to introduce automated acceptance to your project or if you are planning to use automation testing, there is more you need to learn. Specifically, you need to learn how to construct valid statements that your test automation framework will understand and group them in your file system so that the same framework can pick them up and how you can provide your tests with test data using these scenarios. So a very formal Gerken notation needs to be used then and in the next couple of slides we’ll have a look at formal definition of this notation and how to construct the acceptance scenarios in accordance with that formal notation. So let’s have a look. So, the first keyboard that you have in your Gerken scenarios is Given.

Given puts your system in a known state. It is a set of preconditions that you use for your scenarios something that you believe is true. For this scenario to start, it is important to understand that all these three conditions are assumed to be true during this scenario. So within the scenario itself, you don’t test the Given statements. On the contrary, you use them to enter the state when the system is ready to be tested for a particular scenario. So you use Given to do the following you may use it to explain that a user is in a certain state. For example, given I am logged in as an admin user, or given I am logged in as a non admin user, things like that. You can use it to explain that certain elements are present. For example, given that the user sees a banner on the homepage or given that a user sees an SMS. Or you can use it to assume that another scenario has passed. For example, given I have successfully logged in.

What you don’t use Given for is you don’t use it to describe any active interactions between the user and the system. So given I press the button is wrong way of using Given you need to use when for all the activities and we’ll talk about it in a minute. You also don’t use Given for any third party dependencies that cannot be technically performed by your tester. So for example, given Google is down is something that your testing team is very unlikely to achieve. So you don’t write statements like that. You try to contain your scenarios within the scope of your control so you can execute them reliably. The next keyword is when. When is the key action a user will take? It is the action that leads to an outcome. So this is the main interaction for your scenario. These are the actions that your tester will perform or mimic when executing the scenario and making sure that it works.

Let’s have a look at what do you do with vents you use vents to describe the user interactions or the system interactions, interactions between different systems or the timer events, something that happens on certain dates and time. So an example could be given my bill preference is paper when I log in then I see an option to switch to SMS. You see how it is given to explain what is the precondition, what is my bill preference and then understanding this precondition when I do a certain action I log in then I see some results and we’ll talk about them in a minute. What you don’t do with when is you don’t write static preconditions in your when statements.

So compare this example given I’m logged in when my bill preference is paper then I see an option to switch SMS. Even though this scenario may read as a proper English, it still is not a proper semantically correct Gerken scenario. Because according to the Gerkin notation, your activity, your actions should be in when. So logging in as an action should be written under the when statement.

At the same time your preference is something that assumes to be true for this scenario it needs to go in given there is no interaction there, it’s just a statement of fact that is true for this particular scenario. This is why the scenario on the left is more preferable compared to the scenario on the right. The next keyword is then is the observable outcome. It is what happens after the user performs the action or after an event happens.

This is where the actual check is done. Is your result as expected or is it not? So what do you write in Then statements? You write the observable outcomes that can be reliably validated. You focus on changes in objects state or you focus on objects being present or not present on the screen. You can also focus on certain values being displayed for the user. So an example could be when a certain element is present or when the user sees a certain text field or a certain paragraph of text or a certain number on a page. What you don’t do in Then is you don’t focus on results that are vague and cannot be easily interpreted. So you don’t write things like then the layout looks good because it’s hard to validate and it’s hard to put a yes or no answer against this statement. Now let’s talk about some extra keywords that are available in the Gerkin scenarios. And the first two are and bot. So and Bot are just a human readable way to repeat the previous keyword. It’s as simple as that. Compare this given my preference is paper, given I don’t have a phone number on profile when I click change the SMS bill when I agree to TNC, you see how all these keywords are repeated and it doesn’t read nice.

So instead you could introduce these keywords and then but just compare the two. Given my preference is paper but I don’t have a phone number on profile when I click change the SMS bill and I agree to TNCs and so on and so forth. So technically they do not change the scenario and technically the scenario on the left and the scenario on the right are exactly the same. However, from the human point of view, the scenario on the right is a little bit easier to read and maintain. That is why we tend to write the keyword only once and then connect extra statements using and statement. The next one is scenarios. Now we are getting into the area that is more tailored to automation.

If you don’t automate your test you don’t really need to bother with anything that we are going to talk about now. But if you plan to automate your test now or in the future or if you are interested in how to write a proper structured gerken scenario, please keep watching. So this scenario scenario is a statement that used to group other statements and give them a title. It is a part of your feature or user story. So your user story is likely to consist of multiple scenarios and given each scenario title means that you can easily understand what this scenario is about without reading through all of the given when then statements. Some people follow what is called transformat when given the names to scenarios. So for example scenario can be titled as the one where the user has no mobile number or

the one where the user has a mobile number. So let’s have a look at an example. The first one is scenario when the user has no mobile number and this is your scenario given my preference is paper but I don’t have a phone number and so on and so forth. We’ve already seen this scenario before. What is new here is the keyword scenario followed by a column and followed by a title for this scenario. So when you introduce this statement in your requirements document or requirements file, the system will understand that all the statements given events dance bots ends that go underneath it are a part of one scenario with one title.

The next important concept for automation is feature files. In order for your automated test suit to find the test scenarios, they need to be stored on a file system in files with dot feature extension so the framework can pick them up. Basically a feature file is used to give a title for the whole feature or the whole piece of functionality that you are delivering and a feature will contain a set of scenarios groups by a common solution component. For example, you may have a feature file for your home page and a feature file for your checkout page or a feature file for your makeup booking scenario and then inside that feature file you will have all the test scenarios for this feature. Technically it is just a text file with an extension dot feature. Cucumber will look for these files in your file system and it will pull these scenarios and steps from all the files that have a feature extension.

The next keyword is background. Background sets the context for all scenarios within your feature file. If you find that many of your scenarios have common givens, then you can use a background statement to eliminate this repetition. What happens technically is all the statements written under the background statement will run before each of your scenarios. Your individual scenarios still may have their own given statements to complement the statements written under the background section. So let’s see how it works. In this example we have a background. Given my preference is paper. You see how we edit a new keyword with column after it and then we have a given statement. We could as well have multiple given statements underneath it. And then we have our scenarios the one where the user has no mobile number and the one where the user has a mobile number.

You can see that for both of these scenarios the precondition that the preference is paper should be true. That is why in this case we moved it into the background. Compare it to another option. On the right hand side we have two scenarios where given my preference is paper is a part of each scenario. So from the formal point of view, both ways of writing scenarios is perfectly fine and correct from the reusability point of view and just eliminating the duplicates point of view. The approach on the left is a bit more preferable because you have one definition of the background for all of these scenarios in your feature, so you don’t need to worry about it anymore.

When you write new scenarios inside that feature, you just add some specific events that are very specific to your scenarios that you are writing right now. When working with gerkin scenarios, quite often you will see that you need to have multiple similar scenarios to perform repetitive tasks. In this case, scenario outlines can help you to fight this complexity because they are designed to combine a set of similar scenarios.

This allows you to use placeholders in your step definition so you can provide with a test data that will replace those placeholders when the tests are executed. This means you may have one scenario and a set of test data rather than having multiple very similar scenarios in one file. Therefore, it makes your feature files much more readable. Let’s see what it means. For example, you may have three scenarios like this. All these scenarios, they test very similar interaction.

The user has an account with certain number and they try to find an account by entering another number. So some of these scenarios should return a successful message and some of them should return an error message. Instead of writing these scenarios because you may have few dozens of different combinations to try. You may have just one scenario with a set of data that you need to iterate through to fulfill the same testing. So how you do it is you write it this way you start with a new keyboard. Instead of calling it a scenario, you call it a scenario outline.

Then you give it a title, then you write your scenarios. But in these steps you use the square brackets or these pointy brackets to group the placeholders. And then for each placeholder you provide a set of test data in a table. So to introduce a table you need to introduce another keyword example. After that you can start creating a table looking piece of data where the first draw will be considered to be headers and your headers. In this table they need to match your placeholders. So when this scenario outline is executed and the actual test is executed, the cucumber framework will find a placeholder. Understand that this is a placeholder because you are inside a scenario outline. Try to find an example table under the scenario outline. Then it will try to find the same keyword in one of the columns and then it will pick the value from that column and then it will execute the scenario outlines as many times as many rows you have in your examples table. This way you can condense quite a lot of repetitive scenarios into just one scenario with test data alongside it. Gear can notation also supports for tags.

Tags can be used to group acceptance tests from multiple features or to add extra metadata scenarios to filter them for execution. For example, you may have this acceptance criterion, the one where the user has a mobile number. And then you may want to add extra information to these scenarios such as which Jira ticket it relates to, or which test suit it belongs to, or how important this particular acceptance criterion is. You can do it using tags. You can add a tag for your Jira ticket number, for the tests used title, or for your level of criticality for this scenario. Often you need to send specific test data to your tests and there are multiple ways how you can do it in Gerkinotation. One of them is to use the scenario outlines like in one of the examples before.

But then not all of your tests will require repetition. So you probably don’t want to use scenario outlines all over the place. In this case you can use one of the following options. One is to use strings. Every time a piece of string appears in these inverted commas, it will be considered as a piece of test data and this data will be passed from your requirements. A definition straight into your test execution. Sometimes this is not convenient when your strings are long or they have new lines inside. In this case you can use this notation called PY strings. You add a column and then you insert your text data inside three inverted commas like this. In this case, the whole paragraph of text will be sent to your test execution. And finally, you can use data tables to introduce a data table inside a step. You finish this step with a column and then you type a table underneath the statement.

The cucumber will understand that this table is not a part of examples table so it doesn’t require iteration, but it will be passed as a dictionary to this step. Definition in your test execution. These are the ways you could use your test data inside your test execution. And what is great about it is that it allows you to define the test data in your acceptance scenarios inside your requirement specification and then your automation tests will use the same data that has been communicated to your stakeholders when agreeing on the acceptance criteria for your tickets. All right, this has probably been the most technical video in this course and also probably the longest. So let’s recap. Why do we use Gerkin on our projects? First of all, obviously it supports for automation. But that’s not the only benefit of using Gerkin on your projects. It also helps to structure your thoughts around a very particular way of writing the acceptance scenarios, which makes it more consistent one ticket to another and makes it much easier not to forget to ask certain questions or to onboard new people because they will see the same format all over the place and they’ll get used to it pretty soon. It also makes your requirements less ambiguous because everybody needs to agree to a certain set of very particular examples written down as acceptance scenarios before you start the development.

So it reduces the ambiguity during the development. And finally, it allows for flexibility of documentation by creating a very lightweight and living and breathing document that combines the requirements and the testing documentation in one set in one go. So, depending on your project and your environment and the maturity of your team with test information, you may decide how you’re going to use Gerken. Do you want to just stick to a given when then format of writing your acceptance scenarios or do you want to use use the full scale of a Gerkin scenario syntax to support for your automation? That’s really up to you. But as a bare minimum try to stick to give and when then it’s a really great way of writing down the acceptance scenarios and it should really be your bread and butter when writing the acceptance scenario.