Cucumber REST Gherkin library

Cucumber library for simpler e2e tests with predefined sentences for API and basic database access for Spring.


Cucumber REST Gherkin library

Java CI with Gradle Quality Gate Status

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
  • Call an app that listens on several ports (e.g. the actuator/management port) with plain paths — every web server is detected automatically, so no protocol, host or port in the tests
  • Validate HTTP status codes, response headers, and response bodies against inline JSON or JSON files
  • Readable output: one summary line per call on the console, and a report where bodies, headers and query results are collapsed, titled and formatted — with credentials obfuscated

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

Security scan (DAST)

  • Security scan: route the whole Cucumber run through an OWASP ZAP proxy, attack the recorded traffic and fail the build on findings above a risk the feature file states itself — no step code, one dependency and a profile
  • Security scan without Cucumber: the same scan driven from a plain jUnit suite, through a scan session or a jUnit 5 extension — no Cucumber and no Spring dependency

CVE scan of the dependencies

  • CVE scan: scan every library on the test classpath - or the packaged application - for known vulnerabilities with Trivy in a Testcontainers container and fail the build from a severity the feature file states itself — one sentence, no build plugin, no SBOM
  • CVE scan without Cucumber: the same scan from a plain jUnit suite, through a jUnit 5 extension — no Cucumber and no Spring dependency

Dates

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}"
}

For the security scan (in addition to REST):

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

It is deliberately not part of the bdd-cucumber-gherkin-lib bundle: it needs Docker and it is only useful for the runner that executes the scan. See its README for the setup.

For a project that does not use Cucumber, the same scan is available without any Cucumber or Spring dependency:

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

It comes in transitively with the module above, so a Cucumber project never adds it explicitly. See its README for the scan session and the jUnit 5 extension.

For the CVE scan of the dependencies, independent of the DAST scan:

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

It needs Docker as well and is not part of the bundle either. Without Cucumber, use bdd-cucumber-gherkin-lib-security-cve-core instead. See its README.

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
Security scan (DAST) setup and sentences bdd-cucumber-gherkin-lib-security
Security scan from a plain jUnit suite bdd-cucumber-gherkin-lib-security-core
CVE scan of the dependencies bdd-cucumber-gherkin-lib-security-cve
CVE scan from a plain jUnit suite bdd-cucumber-gherkin-lib-security-cve-core