# Scenario Outline In Gherkin Feature File

As we are familiar with the basic gherkin syntax such as `feature`, `scenario`, `background`, `given`, `when` and `then` steps already, let us discuss about the `Scenario Outline` used in a Gherkin feature file.

### Scenario Outline

Let us start with a very simple feature where the remaining candies should be calculated based on the total candies and the candies consumed. However, there can be different scenarios for the different combinations of total candies, consumed candies, and the remaining candies.

`````` Scenario: calculate remaining candies when all candies are consumed
Given I have 10 candies
When I eat 10 candies
Then I should have 0 candies remaining

Scenario: calculate remaining candies when some candies are consumed
Given I have 60 candies
When I eat 23 candies
Then I should have 37 candies remaining

Scenario: calculate remaining candies when no candies are consumed
Given I have 93 candies
When I eat 0 candies
Then I should have 93 candies remaining
``````

It can be very time consuming to write repetitive scenarios with different permutations of data values. It can also be difficult for the reader to understand many separate but similar scenarios. This can be improved by using the `scenario outline` and its example table, thus combining similar scenarios with different combinations of similar data values into one Scenario Outline. A Scenario Outline is always followed by an example table: `Examples`. The example table in scenario outline is used to combine multiple similar scenarios into a single scenario in the feature file. It provides one set of data per scenario. Each new row of the example table is run as a different scenario. The data values in a single row of data are passed to the step definition at the run time of a scenario.

A scenario outline replaces variables with the value from the examples table. Each row in the examples table is considered to be a scenario.

In the scenario outline, the data values do not need to be hardcoded in the step definition. Rather the values are replaced with the name of the parameter itself.

In the above example of candies, if we observe closely, all three scenarios have the same statements, only the parameter value (total/consumed/remaining number of candies) is changing. This is where the significance of the scenario outline comes into the picture.

When we define a scenario using a scenario outline, we can specify a single test scenario for all the similar scenarios and then provide an example table at the end of the test scenario. The test scenario is always specified by `Scenario Outline` and is always followed by a table: `Examples`. This scenario will thus be executed as many times as the number of data inputs (data rows) provided in the examples table

`````` Scenario Outline: calculate remaining candies
Given I have <total> candies
When I eat <eaten> candies
Then I should have <remaining> candies
Examples:
| total | eaten | remaining  |
| 10    | 10    | 0          |
| 60    | 23    | 37         |
| 93    | 0     | 93         |
``````

Now, let us continue with more realistic scenarios. The scenarios of user login with valid credentials (login for different valid users) can be implemented using Scenario Outline as follows:

`````` Scenario Outline: login with valid credentials
Given a user has been created with email "<email>" and password "<password>"
And the user has browsed to the login page
And the user logs in
Then the user should be redirected to the homepage
Examples:
| user1@email.com  | firstpass    |
``````

Here, each row of the example table provides the email and password used in the given and when steps. Even if this scenario looks like a single scenario, it runs 3 times in this example with different email and password set in the step definition, one at a time. The first scenario takes the first row of email and password and completes the test (hopefully passed). Then the 2nd scenario takes the data in the second row independent of other data present in other rows. After this is completed, it's turn for the 3rd row of data sets.

Let us be more clear. The above scenario outline consists of 3 similar scenarios which run uniquely with their own set of data. Let us see how it happens.

The first row of data acts as first scenario and runs as :

``````  Given a user has been created with email "user1@email.com" and password "firstpass"
And the user has browsed to the login page
When the user enters email "user1@email.com" and password "firstpass" in the login form
And the user logs in
Then the user should be redirected to the homepage
``````

Similarly, the next two scenarios run as below respectively.

``````  Given a user has been created with email "second@email.com" and password "password12"
And the user has browsed to the login page
And the user logs in
Then the user should be redirected to the homepage

Given a user has been created with email "test@gmail.com" and password "testpassword"
And the user has browsed to the login page