Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 37 ยท Getting Started

Your First Feature, End to End

Write a first Cucumber feature, see the undefined-step snippets, implement the steps against a small domain class, and watch the scenario go from red to green.

Time to put the pieces together. In this lesson you will write one feature for a tiny piece of business logic, run it with no code behind it, let Cucumber tell you what is missing, implement exactly that, and finish with a passing scenario. This red, then green rhythm is the daily loop of working with Cucumber.

The example is a shipping-cost rule for an online shop: orders of 50 dollars or more ship free; smaller orders pay 5 dollars.

Step 1: write the feature first

Create src/test/resources/features/shipping.feature:

GHERKIN
Feature: Shipping cost
  Orders of 50 dollars or more ship for free.
  Smaller orders pay a flat 5 dollars.

  Scenario: A large order ships free
    Given an order worth 75 dollars
    When the shipping cost is calculated
    Then the shipping cost is 0 dollars

  Scenario: A small order pays shipping
    Given an order worth 20 dollars
    When the shipping cost is calculated
    Then the shipping cost is 5 dollars

Two things to notice. The free text under Feature: is a description; Cucumber ignores it but humans read it, so use it to state the rule. And the scenarios use concrete numbers, not "a big order".

Step 2: run it and read the red

With no step definitions, the run prints something like this (shortened, read-only):

TEXT
Scenario: A large order ships free
  Given an order worth 75 dollars
  When the shipping cost is calculated
  Then the shipping cost is 0 dollars

Undefined scenarios:
shipping.feature:5 # A large order ships free

2 Scenarios (2 undefined)
6 Steps (6 undefined)

You can implement missing steps with the snippets below:

@Given("an order worth {int} dollars")
public void anOrderWorthDollars(Integer int1) {
    // Write code here that turns the phrase above into concrete actions
    throw new io.cucumber.java.PendingException();
}

@When("the shipping cost is calculated")
public void theShippingCostIsCalculated() {
    throw new io.cucumber.java.PendingException();
}

@Then("the shipping cost is {int} dollars")
public void theShippingCostIsDollars(Integer int1) {
    throw new io.cucumber.java.PendingException();
}

This is Cucumber doing the boring part for you. It noticed the number in each sentence, proposed a parameter and generated method names from the text. Notice that both scenarios needed only three definitions: the second scenario reuses the same sentences with different numbers.

A stand-in for the snippet generator

The idea behind the snippets is a small text transformation: replace numbers with parameter placeholders, turn the rest into a camel-case method name. This runnable stand-in does that for any sentence. Try your own.

Java Stand-in: generate a step snippet from a sentence

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Step 3: implement the glue

Create the domain class first. It is ordinary production code, with no Cucumber in it:

Java
package shop;

public class ShippingCalculator {
    public int costFor(int orderTotal) {
        return orderTotal >= 50 ? 0 : 5;
    }
}

Then paste the snippets into src/test/java/shop/ShippingSteps.java and fill them in. This is the real Cucumber-JVM version (read-only):

Java
package shop;

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

import static org.junit.jupiter.api.Assertions.assertEquals;

public class ShippingSteps {
    private final ShippingCalculator calculator = new ShippingCalculator();
    private int orderTotal;
    private int shippingCost;

    @Given("an order worth {int} dollars")
    public void anOrderWorthDollars(int total) {
        orderTotal = total;
    }

    @When("the shipping cost is calculated")
    public void theShippingCostIsCalculated() {
        shippingCost = calculator.costFor(orderTotal);
    }

    @Then("the shipping cost is {int} dollars")
    public void theShippingCostIsDollars(int expected) {
        assertEquals(expected, shippingCost);
    }
}

Three habits are visible even in this tiny class:

  • Steps are thin. Each method does one small thing and delegates to production code (calculator.costFor). Business logic never lives inside a step definition.
  • State lives in fields. orderTotal and shippingCost carry information from the Given to the When to the Then. Because Cucumber builds a new ShippingSteps per scenario, they start fresh each time.
  • Assertions live only in Then steps. Given sets up, When acts, Then checks. Mixing the roles makes scenarios hard to read.

Step 4: watch it go green

Run mvn test again. The two scenarios now execute:

TEXT
Scenario: A large order ships free
  Given an order worth 75 dollars
  When the shipping cost is calculated
  Then the shipping cost is 0 dollars

Scenario: A small order pays shipping
  Given an order worth 20 dollars
  When the shipping cost is calculated
  Then the shipping cost is 5 dollars

2 Scenarios (2 passed)
6 Steps (6 passed)

The same loop, runnable

The following stand-in contains the real ShippingCalculator and a three-definition glue table, and runs both scenarios from the feature text. Change the threshold in the calculator to 80 and watch the first scenario fail with a readable message; that is the regression-catching power you get from executable examples.

Java Stand-in: the shipping feature, red and green

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Common first-run problems

Symptom Likely cause
"0 Scenarios" The feature path is wrong or the file is not under src/test/resources
Every step undefined, but you wrote definitions The glue package setting does not cover your step class
DuplicateStepDefinitionException Two methods have the same expression
Step shows PendingException You pasted a snippet and did not replace the placeholder
Class not found for the runner The runner file is not named or located in a way your build tool picks up

More details on writing the expressions themselves arrive in the chapter on step definitions. First, though, you need a clear picture of the practice that gives Cucumber its purpose: BDD basics.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In which order does the loop of a new feature usually go?

    You start from the example, see it fail or be undefined, then implement just enough to make it pass.
  2. 2. Where should business logic live?

    Steps stay thin and delegate to the application; otherwise your test code duplicates the product.
  3. 3. Why did two scenarios need only three step definitions?

    Parameters such as {int} let one definition serve many examples.
  4. 4. Which kind of step should contain assertions?

    Then steps check outcomes; Given arranges and When acts.
  5. 5. What does a PendingException in a step tell you?

    Pending marks a step you have declared but not yet implemented.

Summary

  • Write the feature with concrete numbers, run it, and let Cucumber print snippets for undefined steps.
  • Keep step definitions thin: store state in fields, call production code, assert only in Then steps.
  • Parameters let one definition serve many scenarios.
  • Cucumber creates fresh step-class instances per scenario, so state does not leak.
  • Most first-run problems are location problems: feature path, glue package or build integration.

Next: BDD Basics: Behavior Before Code