Cucumber REST Gherkin library

A Cucumber / Gherkin step library for Behaviour-Driven Development (BDD) of Spring Boot REST APIs and database interactions.

It ships pre-built step definitions so tests can be written in plain Gherkin without custom step code for the common cases.

What it does

REST API testing

• Execute GET, POST, PUT, PATCH, DELETE calls against any base URL
• Configure authentication (Bearer tokens, per-user credentials) in one Given step
• Set a base path once in Background and use short relative paths in all scenarios
• Validate HTTP status codes, response headers, and response bodies against inline JSON or JSON files

JSON validation

• Exact matching and JSON-Unit flexible matchers (e.g. ${json-unit.matches:isValidUUID})
• Custom matchers for domain-specific assertions

Context & data flow

• ScenarioContext: pass values between steps within a scenario
• ${key} placeholder substitution in URLs and request bodies for dynamic path construction
• Store and read response fields for chained calls

Async & polling

• Polling: repeatedly call an endpoint until a condition is met
• Timing assertions: validate execution duration or introduce waits for async operations

Database

• Database steps: Liquibase migrations, SQL execution, CSV result comparison

Dates

• Dynamic date generation: past/future timestamps without hardcoded values

See Anti-Patterns to keep feature files clean.

See Changelog for release information.

The library tests itself against a dummy Spring Boot application in the test sources. See bdd-cucumber-gherkin-lib/src/test for feature file examples and custom JSON-Unit matchers.

How to integrate

The library is available on Maven Central.

Maven

<dependency>
	<groupId>io.github.ragin-lundf</groupId>
	<artifactId>bdd-cucumber-gherkin-lib</artifactId>
	<version>${version.bdd-cucumber-gherkin-lib}</version>
	<scope>test</scope>
</dependency>

Gradle

For all modules (REST + DB):

dependencies {
    testImplementation "io.github.ragin-lundf:bdd-cucumber-gherkin-lib:${version.bdd-cucumber-gherkin-lib}"
}

For REST only modules:

dependencies {
    testImplementation "io.github.ragin-lundf:bdd-cucumber-gherkin-lib-rest:${version.bdd-cucumber-gherkin-lib}"
}

For DB modules:

dependencies {
    testImplementation "io.github.ragin-lundf:bdd-cucumber-gherkin-lib-db:${version.bdd-cucumber-gherkin-lib}"
}

Documentation

Full documentation lives in the Wiki.

Topic	Wiki page
First test from scratch	Getting Started
Maven / Gradle / BOM setup	Installation
Spring context, auth, proxy, SSL, DB config	Configuration
ScenarioContext, file paths, URL base, keywords	Concepts
All step signatures at a glance	All Steps — Quick Reference
Authentication steps	Given — Authentication
Request setup steps	Given — Request Setup
HTTP call steps	When — REST Calls
Polling steps	When — Polling
Status code / body / header assertions	Then — Validation
Storing response values for later steps	Then — Context
Async wait and timing assertions	Then — Timing
Dynamic date handling	Common — Dates
Liquibase, SQL, CSV comparison	Common — Database
Built-in and custom JSON matchers	JSON-Unit