Gherkin Scenario Outlines Explained

If you've spent time workin' with Gherkin, you may have noticed several examples of Feature files where the "Scenario" section is replaced with a "Scenario Outline" section. Why is that?

Basic Gherkin Feature Files

The main sections of a Gherkin Feature file are as follows:

Feature	A short descriptive title, usually only a few words, dictating the function of the feature file.
Scenario	A discrete piece of functionality to be tested, via the Given-When-Then syntax.
Given	Preconditions for the parent scenario required to perform the test.
When	A single action to be taken in order to move the system from the precondition state to the result state.
Then	Verifiable information that is able to be confirmed without performing any additional actions from the result state.

When writing a Gherkin Feature file, these sections will typically be laid out in the format shown below:

Feature: One Aspect Of The System
 Additional Lines Can Be Added To Provide Detail Here

Scenario: One Function Within Aspect
   Given Preconditions Like Going To Homepage Or Logging In
   When A Single Action Is Performed Which Changes System State
   Then Verify Expected Result Through Checking Result State 

Scenario vs Scenario Outline

The default style for Feature files is fantastic for laying out quick tests like verifying that a page link works correctly or performing some discrete testable action. However, if we only use this format, we quickly run into a pretty noticeable problem: what if we need to test variable data?

In traditional programming, we have concepts like loops and arrays that can allow us to perform the same action with multiple variations of data seamlessly, but this default format for Gherkin Feature files would result in us writing a Scenario for every permutation of data we want to test. This would make the file drastically less readable, and would require far too much time to be worth writing out. That's where Scenario Outlines come in.

A Scenario Outline reformats the Scenario to include a check for user input in the form of predefined data, and this data is presented in a table under the Scenario Outline subheading. With this method, we can write a single scenario that is capable of checking a wide variety of inputs and outputs without duplicating effort on the part of the developer or the tester.

Example

Feature: One Aspect Of The System
 Additional Lines Can Be Added To Provide Detail Here

Scenario Outline: One Function Within Aspect
   Given Preconditions Like Logging In As <user>
   When A Single Action <action> Is Performed Which Changes System State
   Then Verify Expected Result <result> Through Checking Result State 

   Examples:
      | user   | action   | result  |
      | normal | normAct  | success |
      | normal | adminAct | fail    |
      | admin  | normAct  | success |
      | admin  | adminAct | success |

As you can see, we've made two small changes and one addition to our initial Scenario, and it's resulted in a Scenario Outline which is readable, extendable, and functional.

• The "Scenario" heading has been changed to "Scenario Outline".
  • This lets the feature file know it should be looking for variable data rather than interpreting the scenario all at once.
• The Given-When-Then steps have been updated with variables enclosed in <> brackets.
  • These brackets flag the enclosed terms as variables which should be filled with associated data.
  • It's not required to have exactly one per statement line. There can be lines with none, or lines with multiple.
• The "Examples" heading has been added, and a table has been created below it.
  • It's not strictly required to indent the table under the heading, but it does improve readability.
  • Similarly, it's not required to add additional whitespace to line up the table (as shown), but it drastically improves readability.

Making these three changes will allow you to turn any Scenario into a Scenario Outline, to help keep tests concise and relevant.

Example Categories

You may find that in creating Scenario Outlines, you end up having a large number of scenarios being tested before long. When you run your tests, the results are running off the screen, and it's hard to find a single specific test when you review. In this situation, there's one more feature that you can make use of.

Feature: One Aspect Of The System
 Additional Lines Can Be Added To Provide Detail Here

Scenario Outline: One Function Within Aspect
   Given Preconditions Like Logging In As <user>
   When A Single Action <action> Is Performed Which Changes System State
   Then Verify Expected Result <result> Through Checking Result State 

   Examples: Failing Tests
      | user   | action   | result  |
      | normal | adminAct | fail    |

    Examples: Succeeding Tests
      | user   | action   | result  |
      | normal | normAct  | success |
      | admin  | normAct  | success |
      | admin  | adminAct | success |

By setting up multiple blocks of Examples within a single Scenario Outline, you can visually reorganize your tests and get more detailed information about what results are actually being returned by your test suite.

-- ArronReed - 30 Sep 2021