Cucumber Scenarios and Scenario Outlines: Writing Effective Test Cases

← Previous

What are Scenarios and Scenario Outlines?

In Cucumber, a Scenario is a single test case that describes a specific behavior of your application using Gherkin syntax. It typically follows the Given-When-Then structure to define the context, action, and expected outcome. A Scenario Outline, on the other hand, is a way to run the same scenario multiple times with different data sets, making your tests more efficient and reusable.

Key Differences

Scenario: Tests one specific case (e.g., a user logging in with valid credentials).
Scenario Outline: Tests multiple cases using a template and a data table (e.g., logging in with various usernames and passwords).

Both are written in feature files and linked to step definitions for automation.

Writing a Scenario

A Scenario is a single test case that describes one aspect of a feature. It’s written using Gherkin keywords (Given, When, Then, And, But) to describe the behavior in a structured, human-readable way.

Example: Simple Scenario

Let’s create a scenario for a product search feature in a file named search.feature:

Feature: Product Search
  As a user, I want to search for products so that I can find items to purchase.

  Scenario: Search for a product by name
    Given the user is on the search page
    When the user enters "laptop" in the search bar
    And the user clicks the search button
    Then the user should see a list of laptops

Explanation:

Scenario: “Search for a product by name” tests a specific case of searching for “laptop.”
Given: Sets the context (user is on the search page).
When/And: Describes the actions (entering a search term and clicking the button).
Then: Specifies the expected outcome (seeing a list of laptops).

Step Definitions

Create SearchSteps.java in src/test/java/steps:

package steps;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.When;
import io.cucumber.java.en.Then;

public class SearchSteps {
    @Given("the user is on the search page")
    public void userIsOnSearchPage() {
        System.out.println("User navigates to the search page");
    }

    @When("the user enters {string} in the search bar")
    public void userEntersSearchTerm(String searchTerm) {
        System.out.println("User enters: " + searchTerm);
    }

    @When("the user clicks the search button")
    public void userClicksSearchButton() {
        System.out.println("User clicks the search button");
    }

    @Then("the user should see a list of laptops")
    public void userSeesLaptopList() {
        System.out.println("User sees a list of laptops");
    }
}

Run the Scenario:
Use the Cucumber CLI or TestRunner (as shown in previous posts):

mvn test

Output:

User navigates to the search page
User enters: laptop
User clicks the search button
User sees a list of laptops

1 Scenarios (1 passed)
4 Steps (4 passed)
0m0.123s

Writing Multiple Scenarios

A feature file can include multiple scenarios to test different aspects of the same feature. Let’s add a second scenario to search.feature to test a case where no results are found.

Feature: Product Search
  As a user, I want to search for products so that I can find items to purchase.

  Scenario: Search for a product by name
    Given the user is on the search page
    When the user enters "laptop" in the search bar
    And the user clicks the search button
    Then the user should see a list of laptops

  Scenario: Search with no results
    Given the user is on the search page
    When the user enters "nonexistent" in the search bar
    And the user clicks the search button
    Then the user should see a "No results found" message

Update Step Definitions:
Add the new step to SearchSteps.java:

@Then("the user should see a {string} message")
public void userSeesMessage(String message) {
    System.out.println("User sees message: " + message);
}

Explanation:

The second scenario reuses the Given and When steps but has a different Then step.
The {string} placeholder captures the message (“No results found”) dynamically.

Output (when run):

User navigates to the search page
User enters: laptop
User clicks the search button
User sees a list of laptops

User navigates to the search page
User enters: nonexistent
User clicks the search button
User sees message: No results found

2 Scenarios (2 passed)
8 Steps (8 passed)
0m0.245s

Using Scenario Outlines

A Scenario Outline allows you to run the same scenario with multiple sets of data, defined in an Examples table. This is ideal for testing the same behavior with different inputs (e.g., different search terms).

Example: Scenario Outline

Update search.feature to use a Scenario Outline:

Feature: Product Search
  As a user, I want to search for products so that I can find items to purchase.

  Scenario Outline: Search for products with different terms
    Given the user is on the search page
    When the user enters "<search_term>" in the search bar
    And the user clicks the search button
    Then the user should see "<result>"

    Examples:
      | search_term   | result                    |
      | laptop        | a list of laptops         |
      | nonexistent   | a "No results found" message |
      | phone         | a list of phones          |

Explanation:

Scenario Outline: Defines a template with placeholders (<search_term>, <result>).
Examples: Provides data to run the scenario multiple times (3 times in this case).
Each row in the Examples table runs the scenario with different values.

Step Definitions:
The existing SearchSteps.java already supports this Scenario Outline because the steps use {string} placeholders:

@When("the user enters {string} in the search bar")
public void userEntersSearchTerm(String searchTerm) {
    System.out.println("User enters: " + searchTerm);
}

@Then("the user should see {string}")
public void userSeesResult(String result) {
    System.out.println("User sees: " + result);
}

Run the Scenario Outline:

mvn test

Output:

User navigates to the search page
User enters: laptop
User clicks the search button
User sees: a list of laptops

User navigates to the search page
User enters: nonexistent
User clicks the search button
User sees: a "No results found" message

User navigates to the search page
User enters: phone
User clicks the search button
User sees: a list of phones

3 Scenarios (3 passed)
12 Steps (12 passed)
0m0.367s

Benefits of Scenario Outline:

Reduces repetition by avoiding duplicate scenarios.
Makes it easy to test multiple inputs without writing separate scenarios.
Keeps feature files concise and maintainable.

Using Tags with Scenarios

Tags allow you to categorize scenarios or Scenario Outlines for selective execution. Let’s add tags to the Scenario Outline:

@search
Feature: Product Search
  As a user, I want to search for products so that I can find items to purchase.

  @positive @negative
  Scenario Outline: Search for products with different terms
    Given the user is on the search page
    When the user enters "<search_term>" in the search bar
    And the user clicks the search button
    Then the user should see "<result>"

    Examples:
      | search_term   | result                    |
      | laptop        | a list of laptops         |
      | nonexistent   | a "No results found" message |
      | phone         | a list of phones          |

Run only @positive scenarios:

mvn cucumber:test -Dcucumber.features=src/test/resources/features -Dcucumber.glue=steps -Dcucumber.filter.tags="@positive"

Note: In this case, the entire Scenario Outline runs because it’s tagged with @positive. To filter specific rows, you’d need to split the Examples table or use more granular tags.

Best Practices for Scenarios and Scenario Outlines

Keep Scenarios Focused: Each scenario should test one specific behavior.
Use Scenario Outlines for Data-Driven Tests: When testing the same behavior with different inputs, use a Scenario Outline.
Clear Naming: Give scenarios descriptive names (e.g., “Search for a product by name”).
Avoid Overloading: Don’t put too many steps in a single scenario; break complex tests into multiple scenarios.
Use Tags: Categorize scenarios for selective execution (e.g., @smoke, @regression).
Validate with Stakeholders: Ensure scenarios are clear to non-technical team members.

Troubleshooting Scenarios and Scenario Outlines

Undefined Steps: If Cucumber reports undefined steps, ensure step definitions match the Gherkin steps exactly or use placeholders like {string}.
Examples Table Errors: Check that the column names in the Examples table match the placeholders in the Scenario Outline.
Overly Complex Scenarios: Break long scenarios into smaller ones or use a Background for common steps.
Tag Issues: Ensure tags are correctly applied and match the filter in your CLI or TestRunner.

Tips for Beginners

Start with Scenarios: Write simple scenarios before trying Scenario Outlines.
Use Descriptive Names: Make it clear what each scenario tests.
Test Small Data Sets: Start with a small Examples table in Scenario Outlines to avoid complexity.
Run Frequently: Test your scenarios early to catch syntax or step definition issues.

← Previous