Examples

The fastest way to learn SpecBinder is to read a small, focused example for the construct you care about. Every example below ships as a runnable Maven project in the SpecBinder repository — clone it and mvn test to see the generated code on your own machine.

Every example implements its steps in a concrete test class that extends the generated one — except Concrete Mode, where the generated class is itself the test. From Convention Discovery onward, the spec files sit next to their marker classes in src/test/java.

Getting started

The fundamentals — one concept per example.

Example	What it covers
Hello World	The smallest possible feature — one scenario, plain steps, one test class implementing them
Step Parameters	Type inference for quoted values: String, Integer, Long, Double, Boolean, Character
Step Reuse and Scenario State	One method per distinct step; scenario state in the test class, fresh for each scenario
Rules	Gherkin Rule blocks → JUnit @Nested test classes
Background	Feature- and rule-level Background blocks → @BeforeEach
Scenario Outline	Parameterized scenarios → JUnit @ParameterizedTest with @CsvSource
Tags	Gherkin tags → JUnit @Tag for selective execution
Convention Discovery	Bare @Gherkin2JUnit with spec files co-located next to the marker class

Common use cases

Patterns that come up beyond the getting-started examples.

Example	What it covers
Typed Data Tables	The default LIST_OF_OBJECT_PARAMS mode — typed inner classes
DocStrings	Multi-line input (JSON, plain text) → trailing String parameter, and typed doc strings (json, image, svg, html)
Sharing Steps via a Base Class	Put common step implementations in a base class the marker extends
Type Refinement with Enums	Refine generated Param fields and step parameters to enums for compile-time safety
TDD Workflow	Red-green iteration with empty rules and scenarios tagged @new
Glob Patterns	One marker discovering specs across sub-packages with ./**/*.specb
Config Inheritance	Shared @Gherkin2JUnitOptions in a base class, overridden per feature
Scenario Outline Parameters	Examples values in quoted values, doc strings and data tables

Going further

Trickier, more advanced territory — patterns that lean on deeper JUnit or SpecBinder mechanics.

Example	What it covers
Concrete Mode	Opt out of the default abstract mode — a directly-runnable class with failing stubs for unimplemented steps
JUnit Parameter Resolution	TestInfo, @TempDir and custom @JUnitResolved parameters — declared in the marker, implemented in the test
Organizing Steps into Interfaces	Reusable step logic in interfaces with default methods; the test supplies the state
Execution Reporter	The dev.specbinder:execution-reporter module — one JSON report per test class
Playwright Traces per Step	One Playwright trace per Gherkin step, recorded onto the execution report
Layered Tests from One Spec	Run one specification through direct Java calls, Spring beans, and a browser UI for feedback at different application layers

Migrating from Cucumber

The migration guide explains what changes when an existing Cucumber suite moves to SpecBinder. Two focused examples show how to keep the Cucumber APIs that would otherwise cause the most rewriting.

Example	What it covers
Cucumber Data Tables	Keep step methods that consume Cucumber's DataTable API, with asList(...) POJO mapping
Cucumber Annotations	Keep existing @Given / @When / @Then methods and match them by pattern, plus generated Cucumber annotations

Running an example

Every example is a self-contained Maven project. After cloning the repo:

cd examples/getting-started/example-1
mvn test

The generated test class appears under target/generated-test-sources/ — open it in your IDE to see what the annotation processor produced.