Cucumber Tutorial 2026: BDD-Testautomatisierung mit Beispielen

Was ist Cucumber?

Cucumber ist das bekannteste BDD-Framework und gilt als Referenz-Implementierung für Gherkin. Aslak Hellesøy hat es 2008 als Ruby-Bibliothek gestartet, heute existieren Implementierungen für Java (Cucumber-JVM), JavaScript (Cucumber.js), .NET (SpecFlow), PHP (Behat), Python (Behave) und viele weitere Sprachen. Cucumber liest Feature Files in Gherkin-Syntax, mappt jeden Schritt auf eine Step Definition in deiner Programmiersprache und führt das Ergebnis als ausführbaren Test aus.

Du nutzt Cucumber typischerweise in zwei Situationen: erstens, wenn dein Team BDD lebt und fachliche Akzeptanzkriterien als ausführbare Tests verankern will. Zweitens, wenn du E2E-Tests verständlich für nicht-technische Stakeholder dokumentieren willst, statt sie in technischen Test-Frameworks zu vergraben. In beiden Fällen ist Cucumber Brücke zwischen Fachlichkeit und Code. Wer den theoretischen Unterbau braucht, findet die Grundlagen in unserem Pillar zu Behavior Driven Development (BDD): Grundlagen + Praxis.

Cucumber und Gherkin: Wie sie zusammenspielen

Cucumber liest Feature Files, die in Gherkin geschrieben sind. Gherkin ist die DSL (Domain Specific Language), die Cucumber versteht. Jedes Feature File beschreibt ein fachliches Verhalten in der Given-When-Then-Struktur und ist gleichzeitig Anforderung, Spezifikation und Testfall. Eine ausführliche Erklärung der Syntax mit Praxis-Beispielen findest du im Gherkin-Tutorial mit Given-When-Then-Beispielen.

Ein typisches Feature File sieht so aus:

Feature: Warenkorb
  Als Online-Shop-Kunde
  möchte ich Produkte in den Warenkorb legen
  damit ich sie bezahlen kann

  Scenario: Produkt erfolgreich hinzufügen
    Given der Online-Shop ist geöffnet
    When ich "Laptop" in den Warenkorb lege
    Then enthält der Warenkorb 1 Produkt
    And der Gesamtbetrag ist "1.299,00 EUR"

Diese Datei ist gleichzeitig fachliche Spezifikation, Akzeptanzkriterium und ausführbarer Test. Cucumber bindet jedes Given/When/Then an eine Step Definition in deiner Programmiersprache. Das machen wir gleich.

Cucumber in der Praxis: Dein erstes Feature

Cucumber funktioniert sprachübergreifend. Das Gherkin-Feature-File bleibt identisch, die Step Definitions schreibst du in der Sprache deines Projekts. Hier die drei häufigsten Stacks.

Java mit JUnit 5

Cucumber-JVM integriert sich nahtlos in JUnit 5. In pom.xml brauchst du:

<dependency>
  <groupId>io.cucumber</groupId>
  <artifactId>cucumber-java</artifactId>
  <version>7.18.0</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>io.cucumber</groupId>
  <artifactId>cucumber-junit-platform-engine</artifactId>
  <version>7.18.0</version>
  <scope>test</scope>
</dependency>

Die Step Definition zum Warenkorb-Feature:

import io.cucumber.java.de.Angenommen;
import io.cucumber.java.de.Wenn;
import io.cucumber.java.de.Dann;
import static org.junit.jupiter.api.Assertions.*;

public class WarenkorbSteps {
    private Warenkorb warenkorb;

    @Angenommen("der Online-Shop ist geöffnet")
    public void shop_geoeffnet() {
        warenkorb = new Warenkorb();
    }

    @Wenn("ich {string} in den Warenkorb lege")
    public void produkt_hinzufuegen(String produkt) {
        warenkorb.hinzufuegen(produkt);
    }

    @Dann("enthält der Warenkorb {int} Produkt")
    public void warenkorb_anzahl(int anzahl) {
        assertEquals(anzahl, warenkorb.anzahl());
    }
}

JavaScript mit Cucumber.js

Für Frontend-Tests kombinierst du Cucumber.js häufig mit Playwright oder Cypress. Installation:

npm install --save-dev @cucumber/cucumber playwright @playwright/test

import { Given, When, Then } from "@cucumber/cucumber";
import { chromium, Page } from "playwright";

let page: Page;

Given("der Online-Shop ist geöffnet", async function () {
  const browser = await chromium.launch();
  page = await browser.newPage();
  await page.goto("https://shop.example.com");
});

When("ich {string} in den Warenkorb lege", async function (produkt: string) {
  await page.click(`[data-product="${produkt}"] .add-to-cart`);
});

Then("enthält der Warenkorb {int} Produkt", async function (anzahl: number) {
  const text = await page.textContent(".cart-count");
  if (Number(text) !== anzahl) throw new Error(`Erwartet ${anzahl}, bekam ${text}`);
});

.NET mit SpecFlow

SpecFlow ist die offizielle Cucumber-Variante für die .NET-Welt. Wer mit C# arbeitet, nutzt SpecFlow mit NUnit oder xUnit als Test-Runner. Die Feature-File-Syntax ist identisch zu Cucumber-JVM, die Step Definitions schreibst du in C#:

using TechTalk.SpecFlow;
using NUnit.Framework;

[Binding]
public class WarenkorbSteps {
    private Warenkorb warenkorb;

    [Given(@"der Online-Shop ist geöffnet")]
    public void ShopGeoeffnet() {
        warenkorb = new Warenkorb();
    }

    [When(@"ich ""(.*)"" in den Warenkorb lege")]
    public void ProduktHinzufuegen(string produkt) {
        warenkorb.Hinzufuegen(produkt);
    }

    [Then(@"enthält der Warenkorb (\d+) Produkt")]
    public void WarenkorbAnzahl(int anzahl) {
        Assert.AreEqual(anzahl, warenkorb.Anzahl);
    }
}

Step Definitions schreiben

Step Definitions binden den Gherkin-Text an deinen Code. Cucumber matcht den Text per Regex oder Cucumber Expression. Cucumber Expressions sind die moderne Variante: lesbarer und typisiert.

Beispiel: {string} matcht einen String in Anführungszeichen, {int} einen Integer, {float} eine Gleitkommazahl. Eigene Parameter-Typen registrierst du selbst:

import { defineParameterType } from "@cucumber/cucumber";

defineParameterType({
  name: "produkt",
  regexp: /Laptop|Smartphone|Tablet/,
  transformer: (s) => s.toLowerCase()
});

When("ich {produkt} in den Warenkorb lege", async function (produkt: string) {
  // produkt ist hier garantiert "laptop", "smartphone" oder "tablet"
});

Für Setup und Teardown nutzt du Hooks: @Before läuft vor jedem Szenario, @After danach. Tagged Hooks (@Before("@login")) laufen nur vor Szenarien mit dem entsprechenden Tag. Damit hältst du dein Feature File frei von Setup-Logik.

Best Practices für Cucumber-Tests

Cucumber wird oft eingeführt und nach 6 Monaten als „zu wartungsintensiv" wieder rausgeworfen. Die Wahrheit ist: Cucumber funktioniert hervorragend, wenn du diese vier Regeln einhältst.

1. Sprache wählen und durchhalten. Schreibe Feature Files entweder konsequent auf Deutsch oder konsequent auf Englisch. Mischmasch macht Step Definitions unwartbar. Cucumber unterstützt beide Sprachen mit dem # language: de Header.
2. Steps wiederverwenden. Generische Schritte wie „Given ich bin als {role} angemeldet" decken viele Szenarien ab. Wenn du jedes Szenario mit eigenen Steps schreibst, explodiert dein Step-Pool. Mehr dazu in den Gherkin Best Practices.
3. Atomare Szenarien schreiben. Jedes Szenario testet genau ein Verhalten. Halte dich an 5 bis 7 Steps pro Szenario. Wenn ein Szenario länger wird, splittest du es oder verlagerst Setup in Background-Steps.
4. Anti-Patterns vermeiden. Schreibe keine UI-Klicks in Steps („Then klicke auf Button mit ID #login-btn") — das ist gegen die BDD-Idee und macht Tests fragil. Beschreibe stattdessen das fachliche Verhalten („Then werde ich auf das Dashboard weitergeleitet").

Cucumber im CI/CD: Reports und Integration

Cucumber-Tests liefern erst dann echten Nutzen, wenn sie bei jedem Commit laufen. Die Integration in CI/CD-Pipelines ist dabei trivial: Cucumber gibt Exit-Code 0 bei Erfolg, alles andere bricht den Build ab.

Drei Reporting-Optionen sind heute Standard:

• Cucumber HTML Reports: integrierter HTML-Output, generiert per --plugin html:target/cucumber-report.html. Schnell und ohne Extra-Tooling.
• Allure: ausführliches Report-Framework mit Screenshots, Step-Traces und Trend-Analyse über mehrere Builds. Standard in Enterprise-Projekten.
• Cucumber Reports Cloud: SaaS-Lösung von SmartBear mit Trend-Dashboards. Kostenpflichtig, aber Setup ist null.

In Jenkins integrierst du Cucumber typischerweise mit der Cucumber Reports Plugin: nach dem Test-Lauf liest sie die JSON-Reports und rendert eine Übersicht im Build-Detail. In GitLab CI reicht ein artifacts.reports.junit Eintrag, damit fehlgeschlagene Szenarien direkt im Merge-Request angezeigt werden.

Fazit: Cucumber als BDD-Werkzeug

Cucumber ist das ausgereifteste BDD-Framework am Markt und der schnellste Weg, fachliche Akzeptanzkriterien als ausführbare Tests zu verankern. Wer Gherkin schreibt, bekommt Spezifikation und Test in einem Artefakt. Wer Step Definitions diszipliniert wiederverwendet, baut sich eine wartbare Test-Suite. Wer Anti-Patterns wie UI-Click-Steps vermeidet, behält die Brücke zwischen Fachlichkeit und Code stabil.

Wenn du Cucumber im eigenen Team einführen willst, lohnt sich der Schulterblick mit erfahrenen Beratern. Unsere Beratung zur Testautomatisierung begleitet von der Workshop-Einführung mit den Three Amigos bis zur CI-Integration mit Cucumber Reports.

FAQ: Häufig gestellte Fragen zu Cucumber

Was ist der Unterschied zwischen Cucumber und Gherkin?

Gherkin ist die Sprache, Cucumber der Test-Runner. Du schreibst dein Feature File in Gherkin („Given… When… Then…") und Cucumber führt es aus, indem es jeden Schritt auf eine Step Definition mappt. Andere Frameworks wie SpecFlow, Behat oder JBehave nutzen Gherkin ebenfalls als Sprache, sind aber eigenständige Test-Runner.

Welche Programmiersprachen unterstützt Cucumber?

Cucumber-JVM deckt Java, Kotlin, Scala und Groovy ab. Cucumber.js läuft auf JavaScript und TypeScript. Für .NET nimmst du SpecFlow, für PHP Behat, für Python Behave, für Ruby den Cucumber-Klassiker. Das Feature File bleibt sprachunabhängig, nur die Step Definitions schreibst du im Stack deines Projekts.

Brauche ich BDD um Cucumber zu nutzen?

Nein, du kannst Cucumber auch ohne BDD-Workflow einsetzen. Aber dann verschenkst du den größten Hebel: die fachliche Klärung in der Three-Amigos-Session. Wenn du Cucumber nur als Test-Tool nutzt und die Feature Files allein vom Entwickler schreiben lässt, hast du den Wartungsaufwand ohne den fachlichen Nutzen. Wer den Unterschied verstehen will, liest unseren Pillar zu BDD vs TDD im Detail.

Wie integriere ich Cucumber in CI/CD?

Drei Schritte: erstens Cucumber als Test-Dependency in dein Build-Tool einhängen (Maven, Gradle, npm, dotnet). Zweitens den Cucumber-Lauf als CI-Stage definieren, der bei Fail den Build bricht. Drittens den HTML- oder Allure-Report als Artifact veröffentlichen, damit Reviewer fehlgeschlagene Szenarien direkt sehen. Wer das in einem laufenden Projekt sauber aufsetzen will, kann unsere BDD-Beratung mit CI-Integration in Anspruch nehmen.

Was sind die häufigsten Fehler bei Cucumber-Tests?

Drei Klassiker: erstens UI-Klicks in Steps („When klicke auf Button #submit") statt fachlicher Beschreibung. Zweitens Step-Explosion durch fehlende Wiederverwendung, sodass jedes Szenario eigene Steps braucht. Drittens fehlende Disziplin bei der Sprache: Wenn Feature Files mal Deutsch und mal Englisch sind, kollabieren Step Definitions. Wer alle drei vermeidet, hat eine wartbare Cucumber-Suite.