Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

How Cucumber Works: Features, Glue and Runner

Understand the moving parts of Cucumber: feature files, step definitions called glue, the runner, and the life of a scenario from parsing to pass, fail, undefined or skipped.

Before you write real Cucumber code it helps to know what happens when you press run. Cucumber is surprisingly small: it parses feature files into scenarios, matches each step to a step definition, executes them in order, and reports the result. Everything else (hooks, tags, plugins) is built around that loop.

This lesson walks through the loop, names every component, and builds a working miniature of it so you can see each stage.

The four components

The Cucumber pipeline

Feature files Gherkin scenarios
Glue code Step definitions + hooks
Runner Parse, match, execute
Reports Console, HTML, JSON

Four parts, one loop.

1 / 2
  • Feature files (*.feature) hold the scenarios in Gherkin. They are plain text and belong in version control next to the code.
  • Glue code is the name for everything Cucumber needs to connect the text to your application: step definitions, hooks, parameter types. The word comes from the fact that this code "glues" sentences to the system under test.
  • The runner is the engine. In Cucumber-JVM it is usually started through JUnit, Maven or Gradle, which tell it where the features and the glue live.
  • Reports are produced by plugins: pretty console output, an HTML page, JSON or JUnit XML for CI tools.

The life of one scenario

flowchart LR
    A["Read .feature file"] --> B["Parse into scenarios"]
    B --> C["For each scenario:<br/>create fresh glue objects"]
    C --> D["For each step:<br/>find matching definition"]
    D --> E{"Match found?"}
    E -- "no" --> F["Undefined"]
    E -- "yes" --> G["Run the method"]
    G --> H{"Exception?"}
    H -- "no" --> I["Passed"]
    H -- "yes" --> J["Failed, skip rest"]

Every scenario goes through the same path; a failure skips only the rest of that scenario.

Four rules follow from the diagram and are worth memorizing:

  1. Scenarios are isolated. Cucumber creates new instances of your glue classes for each scenario, so instance fields start empty. State does not leak from one scenario to the next (unless you deliberately store it in a static field, which you should not).
  2. Steps run in file order. A step cannot see a later step; it can only see the state its predecessors left in the glue objects.
  3. The first failure ends the scenario. Remaining steps are reported as skipped (hooks that must clean up still run).
  4. The match is by text, not by keyword. Given, When and Then are only labels for readers. A step defined with @Given can be used after When and the engine will still find it.

A miniature engine you can run

The next program is a stand-in with the same architecture: it parses a small feature text into scenarios, creates fresh state per scenario, matches steps with regular expressions, runs them, skips after a failure, and prints a summary like the real console reporter. Study how each stage is a separate method; that is the shape of the real engine.

Java Stand-in: parse, match, run, report

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.

Look at the output carefully. Scenario two fails on the third step, so its fourth step is skipped even though it would have passed. Scenario three has an undefined step, so the last step after it is skipped as well. Both behaviors match real Cucumber.

Where the real pieces live

In a Cucumber-JVM project the layout is conventional:

TEXT
src/test/
  java/
    com/example/shop/
      CartSteps.java        <- glue: step definitions
      Hooks.java            <- glue: @Before / @After
      RunCucumberTest.java  <- the runner entry point
  resources/
    com/example/shop/
      free_shipping.feature <- the specifications

Cucumber finds the feature files from a features path (a classpath folder or directory) and the glue from a glue package (a Java package name). Both are settings: you will meet them in the lessons on project setup and the first end-to-end run.

The runner class is tiny. With JUnit 5 it is only annotations:

Java
import org.junit.platform.suite.api.*;

import static io.cucumber.junit.platform.engine.Constants.GLUE_PROPERTY_NAME;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("com/example/shop")
@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "com.example.shop")
public class RunCucumberTest {
}

@SelectClasspathResource points at the features, and the GLUE_PROPERTY_NAME parameter names the package to scan for step definitions.

What dry run and snippets tell you

Real Cucumber has two features that rely on the matching stage and are very handy while writing:

  • Undefined step snippets. When a sentence has no definition, Cucumber prints a ready-to-paste method skeleton for it, including the guessed parameter types. You copy it into a glue class and fill in the body.
  • Dry run. With cucumber.execution.dry-run=true it parses and matches everything but does not execute any step code. It is a fast way to find undefined or ambiguous steps across hundreds of scenarios.

Ambiguity is the opposite of undefined: if a sentence matches two definitions, Cucumber refuses to guess and reports an ambiguous step error. The stand-in above takes the first match, which is more forgiving than the real tool; real Cucumber is deliberately strict so that you never run the wrong code by accident.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is 'glue' in Cucumber?

    Glue is all the code that binds the text in feature files to the system under test.
  2. 2. What happens to the remaining steps of a scenario after one step fails?

    The first failure ends the scenario; later steps are marked skipped.
  3. 3. Why does an instance field in a step class start empty in every scenario?

    Per-scenario object creation is what keeps scenarios isolated from each other.
  4. 4. A sentence matches two step definitions. What does real Cucumber do?

    Cucumber is strict: ambiguity is an error so you never run the wrong code by accident.

Summary

  • Cucumber parses feature files, matches each step to glue by text, executes it and reports the result.
  • A step ends as passed, failed, undefined or skipped; the first failure skips the rest of the scenario.
  • New glue objects per scenario keep scenarios isolated.
  • Keywords are labels for readers; matching is by the sentence text.
  • Dry run finds undefined and ambiguous steps without executing code.

Next: Setting Up a Cucumber Project