Working with Gherkin scenario outlines

In this article we are going to look at one of the more advanced features of Gherkin, scenario outlines. When used correctly, this can be an extremely useful tool in illustrating examples. By the end you’ll know what scenario outlines are, when to use them and how to create them within Behave Pro.

What are scenario outlines?

Imagine you’re sitting in a collaborative session and you’ve described a series of examples around a feature that checks if your username is unique during an account registration process. You and your team have managed to capture:

• Entering a username that is not taken

• Entering a username that is taken

• Entering an invalid username

The resulting Gherkin scenarios that you capture for each of the examples are:

Scenario: Valid and available username   
Given there is an account already registered under the username “Mark” 
And I am on the account registration page   
When I look up the username “Mike”   
Then I receive a message saying “Username available”  

Scenario: Valid but unavailable username   
Given there is an account already registered under the username “Mark” 
And I am on the account registration page   
When I look up the username “Mark”   
Then I receive a message saying “Username not available”  

Scenario: Invalid username   
Given there is an account already registered under the username “Mark” 
And I am on the account registration page   
When I look up the username “-123”   
Then I receive a message saying “Username invalid”

As we can see those three scenarios are almost identical. Each of the scenarios has the same wording but slightly different values for usernames and the output message. This creates a lot of text and a lot of work in future maintenance. So how do we reduce the amount of text without losing the descriptive value of the scenarios? By collapsing all the scenarios into a single scenario outline:

Scenario outline: Verifying usernames   
Given there is an account already registered under the username “Mark” 
And I am on the account registration page   
When I look up the username “<name>”   
Then I receive a message saying “<message>”

Examples

| name   | message                  |     
| Mike   | Username available       |     
| Mark   | Username not available   |     
| -123   | Username invalid         |

Notice that we have condensed the scenarios without losing anything of value.

Let’s go through the specific differences between a scenario outline and a scenario.

1. On the first line, when creating a scenario outline we have to declare it as ‘Scenario outline’ instead of a ‘Scenario’. This is required for tools like Cucumber to know to look for the examples table at the bottom of the scenario.

2. Below the scenario is an examples table which is required for a scenario outline. It needs to have the title ‘Examples’, and each cell needs to be divided using the ‘pipe’ character.

3. Notice how the entries in the first row of the table are then used in the scenario on the 'When' and 'Then' steps. These are references to the data that you want to inject into the scenario. So when we read the line ‘When I look up the username “”’ I can replace with an entry from the examples table so it reads ‘When I look up the username “Mike”’.

With the table in place, each row below the first refers to a single scenario, meaning if we were to run the scenario outline it would execute the scenario once for each row in the table, replacing the references in the scenario with data from the row that is being run.

For example, if Cucumber was to run this scenario it would run it three times, updating the username to “Mike”, “Mark” and then “-123”. So the behaviour would be exactly the same as if they were three separate scenarios; we’ve simply saved time and space and made the scenario more illustrative of a specific feature.

When to use scenario outlines

Once you know how the syntax of scenario outlines works, it’s easy to go overboard with using them. Knowing when to use them is equally as important as how to use them. You want your scenario outlines to describe behaviours or examples that are important to the business, not detail every boundary or test case. Adding too many rows simply creates more work and obscures where the value is to the business.

To start, try capturing your scenarios as single scenarios and then review them afterwards to see if there are scenarios that could be collapsed into a scenario outline. Also, think about the behaviour you’re describing. If the behaviour of the user is very similar but the system’s key behaviour changes dramatically based on inputs, like in our username example, then a scenario outline may be required.

Using scenario outline in Behave Pro

When creating a scenario, Behave Pro will intelligently monitor what we are writing and if it detects that you have entered the ‘Examples:’ keyword that we’ve seen in prior examples, it will know when to convert your scenario into a scenario outline. Additionally, once we have created our first row in an examples table, Behave Pro will then create the formatting for the next row, allowing us to simply tab between each cell to quickly enter our details.

To give a more detailed overview of how to create a scenario outline, see the image below showing a visual example of how you would create a scenario outline with Behave Pro: