Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 37 ยท Getting Started

What Is Cucumber?

Learn what Cucumber is, what problem it solves, how plain-language Gherkin specifications become automated tests, and when it is (and is not) the right tool.

Cucumber is a tool that runs executable specifications. You describe how a system should behave in plain, structured language, and Cucumber connects each sentence to a piece of code that exercises the real application. When the code runs and the checks pass, the sentence is proven true. When it does not, you get a failing line that a product owner can read as easily as a developer can.

The idea behind it is called Behavior-Driven Development (BDD): a way of working in which the whole team agrees on examples of behavior first, and the examples then double as documentation and automated tests. This course teaches both the practice and the tool.

Honest scope. The real Cucumber libraries (Cucumber-JVM, Cucumber.js, Cucumber-Ruby and others) need a build tool, a test framework and, for UI tests, a browser. None of these can run inside this website. So every real Cucumber snippet in this course is read-only, and every runnable example is a clearly labelled stand-in written in Java that implements the same ideas (parsing steps, matching patterns, passing parameters) in a few dozen lines. You will learn what Cucumber does by watching a miniature version do it.

The problem Cucumber solves

Software projects fail for a boring reason: people understand the requirement differently. A product owner writes "customers get free shipping on big orders". A developer reads "big" as 100 dollars; the tester reads it as 50. Everyone is confident, nobody is aligned, and the difference is discovered in production.

Cucumber attacks this in two ways:

  1. It pushes the team to replace vague words with concrete examples ("an order of 75 dollars ships free; an order of 49.99 dollars pays 5 dollars shipping").
  2. It makes those examples executable, so the documentation can never silently drift away from the software. A stale example fails the build.

One example, three jobs

Conversation The team agrees on examples
Documentation The examples are readable
Automated test The examples run on every build

Write it once, use it three times.

1 / 2

What a Cucumber specification looks like

A specification lives in a .feature file written in Gherkin, the language of Cucumber. Here is one in full. You do not need to know the syntax yet; just notice how readable it is.

GHERKIN
Feature: Free shipping

  Scenario: A large order ships free
    Given a cart containing 75 dollars of books
    When the customer checks out
    Then the shipping cost is 0 dollars

  Scenario: A small order pays shipping
    Given a cart containing 49 dollars of books
    When the customer checks out
    Then the shipping cost is 5 dollars

Nothing in these sentences says how the shop is built. They could describe a website, a mobile app or a REST API. That is deliberate: the specification states what the system does, and the step definitions behind it decide how to drive the system.

From sentence to code

For each distinct sentence you write a step definition: a small function tagged with a pattern. In real Cucumber-JVM it looks like this (read-only; you will build up to it over the next chapters):

Java
@Given("a cart containing {int} dollars of books")
public void aCartContainingDollarsOfBooks(int amount) {
    cart.addBook(amount);
}

@When("the customer checks out")
public void theCustomerChecksOut() {
    receipt = shop.checkout(cart);
}

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

The in the pattern captures the number from the sentence and passes it to the method as a real int. Cucumber reads the feature file, finds the matching method for each line, and calls it in order.

A stand-in you can run

The program below is not Cucumber. It is a miniature stand-in that does the same job: it keeps a list of (pattern, action) pairs, takes the sentences of one scenario, finds the pattern that matches each, and runs it with the captured value. Read it, run it, then change a number in the scenario and watch the result change.

Java Stand-in: a ten-line step matcher

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.

Notice three things that hold for real Cucumber too:

  • The sentences are data; the code is attached by pattern matching.
  • A sentence with no matching pattern is reported as undefined, not as a crash.
  • A failed check is an exception (here AssertionError); the runner catches it and marks the step failed.

The Cucumber family

"Cucumber" is a family of implementations that all understand the same Gherkin:

Implementation Language Typical test framework
Cucumber-JVM Java, Kotlin, Scala, Groovy JUnit 5 (JUnit Platform), TestNG
Cucumber.js JavaScript, TypeScript built-in runner
Cucumber-Ruby Ruby the original; works with Rails
Behave / pytest-bdd Python community projects that read Gherkin
SpecFlow / Reqnroll C# (.NET) NUnit, xUnit
Godog Go Go's testing

Because the feature files are the same everywhere, a team can share the language of its specifications even when its services use different stacks. This course shows Java and Kotlin because Cucumber-JVM is the most widely used implementation and because Java stand-ins can run here.

When Cucumber is a good fit

Use it when:

  • Non-programmers (product owners, analysts, testers, domain experts) should be able to read and review the tests.
  • The behavior is business rules with many examples: pricing, eligibility, workflows, permissions.
  • You want living documentation of what the system does.

Skip or limit it when:

  • The tests are purely technical (unit tests of a sorting function). Plain JUnit is shorter and clearer.
  • Nobody outside the dev team will ever read the scenarios. Then Gherkin is just an extra translation layer you maintain.
  • You need heavy performance or load testing.

The most common Cucumber failure is not technical. Teams treat it as "a way to write UI tests in English", skip the conversations, and end up with hundreds of slow, brittle scenarios nobody reads. You will see how to avoid this in the chapter on BDD concepts and again in the later chapters on patterns and pitfalls.

What you will build in this course

By the end you will be able to write good Gherkin, implement steps with Cucumber expressions, parameterize with outlines and data tables, organize runs with hooks and tags, drive a browser through page objects, produce reports in CI, and avoid the classic traps. Each concept appears as real Cucumber code (read-only) and as a runnable Java stand-in.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main purpose of Cucumber?

    Cucumber connects readable Gherkin sentences to code, so examples agreed by the team become executable tests.
  2. 2. In a feature file, which part decides HOW the system is driven?

    Sentences state what should happen; the step definitions contain the code that drives the application.
  3. 3. What does a runner report for a sentence that matches no step definition?

    Cucumber marks it as undefined so you know there is no code behind the sentence yet.
  4. 4. Why does this course use Java stand-ins for most runnable examples?

    The real tool needs a build setup and a browser, so the site runs small stand-ins that show the same ideas.

Summary

  • Cucumber runs executable specifications written in Gherkin and bound to code by step definitions.
  • BDD is the practice; Cucumber is the tool that automates the examples.
  • Sentences describe behavior; step definitions describe how to drive the system.
  • Unmatched sentences are undefined, failed checks are exceptions caught by the runner.
  • Use Cucumber when non-programmers read the specs and the rules have many examples; skip it for purely technical tests.

Next: How Cucumber Works