Release 3.18.0

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


Release 3.18.0

Bugfixes

IncompatibleClassChangeError when Cucumber loads a broad glue path

Projects whose glue path covered more than the library’s glue packages (e.g. com.ragin.bdd.cucumber.security) failed before the first scenario with VulnerabilityHtmlReport and VulnerabilityHtmlReport$bySeverity$$inlined$thenBy$1 disagree on InnerClasses attribute. Cucumber calls getDeclaringClass() on every glue class, and the JVM rejects the synthetic classes of the inline comparator functions there. VulnerabilityHtmlReport, ZapHtmlReport and ServiceUrlResolver no longer use inline comparator functions, the sort orders are unchanged. GlueClassLoadingTests now checks every class below com.ragin.bdd.cucumber instead of only the glue packages.

Release 3.17.0

Bugfixes

Inconsistent class files of the ZAP HTML report

ZapHtmlReport sorted the alerts with a chain of inline comparator functions (compareByDescending { }.thenBy { } .thenBy { }). The Kotlin compiler copies each of them into the calling class as a synthetic class (ZapHtmlReport$render$$inlined$compareByDescending$1, ...$thenBy$1, ...$thenBy$2), whose generation is not stable across builds - incremental and clean builds could produce different class files from the same source. The sort uses the non-inline compareBy(vararg selectors) now, whose lambdas compile to invokedynamic without generated classes. The order of the alerts is unchanged: risk descending, then name, then site.

Release 3.16.0

New features

Limit what ZAP writes to disk during the scan

ZAP records every message of the run in its session database, which never shrinks while ZAP runs. In some environments this took several GB of disk. Three new opt-in scanner properties cap it; without them nothing changes:

cucumbertest:
    security:
        scanner:
            max-request-body-size: 65536    # database.request.bodysize, ZAP default 16 MB
            max-response-body-size: 65536   # database.response.bodysize, ZAP default 16 MB
            container-log-max-size: 50m     # cap Docker's copy of the console output

Without Spring: ScannerProperties(maxRequestBodySize = ..., maxResponseBodySize = ..., containerLogMaxSize = ...). See “Disk usage” in the security module README.

Release 3.15.0

New features

ZAP database recovery log: scanner.database-recovery-log

ZAP keeps its session in a database and writes a recovery log for it. The scanner container is thrown away after the run, so the log only costs disk I/O and scan time. It is now switched off by default (-config database.recoverylog=false); set the property to true to restore ZAP’s own behaviour:

cucumbertest:
    security:
        scanner:
            database-recovery-log: true

Without Spring: ScannerProperties(databaseRecoveryLog = true).

Suppressed alerts in the reports: report.include-suppressed-alerts

Suppressed alerts - marked as false positive by an alerts.alert-filter with new-risk: False Positive or by alerts.ignored-rule-ids - were always left out of the reports. They can be listed now, so a review sees what was suppressed (alerts a filter moves to another risk were and are reported at their new risk):

cucumbertest:
    security:
        report:
            include-suppressed-alerts: true

Without Spring: ReportProperties(includeSuppressedAlerts = true).

Applies to every template. ZAP’s own templates show them with the confidence False Positive; bdd-modern-plus lists them in a section Suppressed alerts after the findings and leaves them out of the counts per risk. The default false keeps the reports as they were. The gate is not affected: suppressed alerts never fail the build.

Release 3.14.1

Breaking Changes

Several security scan reports: report.templates replaces report.template and report.file-name

The DAST scan writes a list of reports now, each with its own template and file name. report.template and report.file-name (ReportProperties.template / fileName) are gone; move them into one entry of report.templates:

# before
cucumbertest:
    security:
        report:
            template: traditional-html-plus
            file-name: security-report.html
# after
cucumbertest:
    security:
        report:
            templates:
                - template: traditional-html-plus
                  file-name: security-report.html

Without Spring: ReportProperties(outputDir = ..., templates = listOf(ReportTemplateProperties(template = ..., fileName = ...))). A blank template or file-name fails at start-up.

The default changes from traditional-html to two reports: the library’s own bdd-modern-plus HTML (security-report.html) and traditional-xml (security-report.xml).

An own SecurityScanner implementation has to take the template: storeReport(template: String, destination: Path).

New features

Own all-in-one HTML report: bdd-modern-plus

One self-contained HTML file built from ZAP’s traditional-json-plus: counts per risk, an index of all alerts and, per alert, description, solution, references, CWE/WASC and every instance with evidence, request and response. Embedded styles, no JavaScript - instances fold away in <details> - so it stays readable when Jenkins strips inline styles. Any ZAP template can be listed next to it, e.g. traditional-xml to collect results across projects, see the security README.

All reports are attempted even if one template fails; the scan fails afterwards with the first error.

New sentences for reports

  • I store the security scan reports to the directory {string} - every report of report.templates.
  • I store the security scan report with template {string} to the file {string} - one report with any template.

I store the security scan report to the file {string} writes the first entry of report.templates.

Release 3.13.0

New features

ZAP alert filters: alerts.alert-filter

cucumbertest.security.alerts.alert-filter (AlertProperties.alertFilter) takes a list of ZAP global alert filters. Unlike ignored-rule-ids, which drops a whole rule, a filter can be limited to a url, parameter, attack, evidence or HTTP methods (each optionally as regex) and can set any risk: False Positive, Info, Low, Medium or High. The fields are those of the ZAP Automation Framework alertFilter job, so filters from a ZAP plan can be copied over:

cucumbertest:
    security:
        alerts:
            alert-filter:
                - rule-id: "10038"   # CSP header not set - the actuator serves no HTML
                  new-risk: False Positive
                  url: ".*/actuator/.*"
                  url-regex: true

The filters are registered before any traffic, and the gate sees the changed risk. A filter that ZAP rejects fails the start of the scan. context is not supported; every filter is global.

Release 3.12.0

Breaking Changes

Upgrade to Cucumber 8.x - jUnit 6.1 is required

Cucumber 8 is built against jUnit 6.1 (e.g. ParallelHierarchicalTestExecutorServiceFactory), but Spring Boot 4.1.x still manages jUnit 6.0.x. With the managed version the Cucumber engine fails when the test run starts. The version override of this library is not published, so every consuming project has to raise the jUnit version itself until Spring Boot manages 6.1 or later:

// build.gradle, with the io.spring.dependency-management plugin
ext["junit-jupiter.version"] = "6.1.3"
// build.gradle.kts, without the plugin
testImplementation(platform("org.junit:junit-bom:6.1.3"))

Other changes of Cucumber 8 that can affect a consuming project

  • Nullability is declared with JSpecify. Kotlin now sees the cells of DataTable.asLists(), asMap() and similar as nullable. Own glue code that treats them as non-null gets compile errors or warnings. An empty cell in a feature file is null.
  • Classes not designed for extension are final now and utility classes can no longer be instantiated. Projects that extend Cucumber classes (plugins, formatters) have to switch to composition.
  • Jackson is an opt-in dependency of cucumber-core. The json, message and html plugins need it at runtime. This library brings jackson-databind 3.x, so nothing changes as long as it is not excluded.
  • Plugin exceptions are no longer suppressed, so a plugin that failed silently before fails the run now.
  • Partial matches with cucumber.filter.name are aligned with the other Cucumber implementations.
  • Baseline is Java 17.

Deprecated and removed Cucumber modules

  • Deprecated for removal: cucumber-junit (jUnit 4 runner) and cucumber-testng. Use cucumber-junit-platform-engine with @Suite runners, as this library does.
  • Removed: cucumber-openejb (use cucumber-jakarta-openejb), cucumber-cdi2 (use cucumber-jakarta-cdi) and cucumber-deltaspike (no replacement).

Glue classes must survive getDeclaringClass()

Cucumber 8 inspects every class of a glue package with getDeclaringClass() to print hints about the glue configuration. Kotlin can generate classes that the JVM rejects there, which aborts the whole run with IncompatibleClassChangeError: ... disagree on InnerClasses attribute. A known trigger is a reified inline function that creates an anonymous object inside a lambda, e.g. runCatching { restTemplate.exchange<String>(...) }. The library glue no longer does this. Own glue classes of a project can hit the same error; use the non-reified variant there, e.g. restTemplate.exchange(url, method, entity, String::class.java).

Changes

Empty DataTable cells

  • The key/value sentences (that the following users and tokens are existing, that the context contains the following 'key' and 'value' pairs, I ensure that the body of the response contains the following fields and values) fail with a message that names the row when a cell is empty, instead of a NullPointerException.
  • A form-data sentence sends an empty value cell as an empty form field. An empty field name fails the step.

Security scan without a browser

The browser based scan rules (ZAP 40026, Cross Site Scripting (DOM Based)) are disabled by default. A REST API has no DOM to attack, and the scanner container logged RedirectScript - Failed to configure ZAP extension on browser launch while the rule tried to start a browser. cucumbertest.security.scanner.browser-enabled: true restores the previous behavior.

Hints

Management port and the security scan

When the actuator runs on its own port, the security scan only exposes the application port to the scanner container, unless every port is listed in cucumbertest.security.target.exposed-ports. With RANDOM_PORT, placeholders like ${management.server.port} resolve to 0 there, so they do not help.

The simplest solution for the tests is to run the actuator on the application port:

management:
  server:
    port: ${server.port}

Spring Boot then starts no separate management server, /actuator/... is answered by the application port and the scan covers it without any further configuration.

Release 3.11.0

New features

CVE scan of the dependencies: bdd-cucumber-gherkin-lib-security-cve and -security-cve-core

Two new modules scan the libraries of the application under test for known vulnerabilities with Trivy, which runs in a short-lived Testcontainers container. There is nothing to install and no build plugin: the archives come from the classpath of the test JVM, a pathing jar included, and the vulnerability databases are kept in a Docker volume between runs.

Then I scan the dependencies for known vulnerabilities and fail on findings of severity "CRITICAL" or higher
Then I scan the artifacts "build/libs" for known vulnerabilities and fail on findings of severity "HIGH" or higher

The scan is configured under cucumbertest.security.cve (disabled by default), its glue is BddLibConfigConstants.GLUE_PROPERTY_VALUES_SECURITY_CVE. bdd-cucumber-gherkin-lib-security-cve-core has no Cucumber and no Spring dependency and brings a jUnit 5 extension, VulnerabilityScanExtension, for suites without Cucumber. Both modules are independent of the DAST scan. The default Trivy image is aquasec/trivy:latest; pin scanner.image by digest if you need reproducible scans.

Every scan writes its raw JSON report and an HTML report named after the scan (vulnerability-report-dependencies.html, vulnerability-report-artifacts-build-libs.html), so the scans of one run keep their own reports. The HTML report is one self-contained file - styles embedded, no JavaScript - and shows the verdict, the counts per severity and every finding with its advisory link, including the ignored ones with the reason.

The vulnerability databases can come from a registry mirror or pull-through cache (scanner.database.repositories), from a daily updated storage (scanner.database.archive, an http(s) URL or a file path, loaded into the cache volume at most once per max-age) or through a proxy (scanner.https-proxy) - separately for the vulnerability and the Java database.

Report directories come from the configuration

cucumbertest.security.report.output-dir and cucumbertest.security.cve.report.output-dir are set in the profile like every other property; a system property of the same name still overrides them. The framework independent core modules read no system properties: a project that creates the properties objects itself passes the directory.

Bugfixes

The security scan failed with Unrecognized token 'ZAP'

The JDK HTTP client talks HTTP/2 by default and ZAP accepts the h2c upgrade on the first API call. HTTP/2 has no Host header, so every later call lost the Host: zap that separates ZAP’s API from its proxy: ZAP forwarded the call to localhost:<port> and answered with a 502 error page instead of JSON - typically on the start of the active scan. The ZAP API client is pinned to HTTP/1.1 now.

alerts.ignored-rule-ids is applied to the security report

The ignore list was only used by the gate, so the HTML report still listed every ignored rule. ZAP now marks each ignored rule id as false positive through a global alert filter registered right after start - before any proxied or replayed traffic - and the report is generated with includedConfidences=Low|Medium|High|Confirmed, so false positives are left out. The filters need the alertFilters add-on, which zap-stable bundles; without it a warning is logged and only the report is affected, the gate still drops the rules. No configuration change is needed.

Release 3.10.0

New features

New module bdd-cucumber-gherkin-lib-security-core

The security scan is now split into two artifacts.

bdd-cucumber-gherkin-lib-security-core contains the basic implementations without Cucumber dependencies: the SecurityScanner abstraction, the scan orchestration, the finding gate, the configuration objects, the Testcontainers based OWASP ZAP implementation, and the entry points a plain jUnit suite needs. It depends on no Spring artifact and on no other module of this library, so a project on a different Spring Boot generation can create the objects and load the configuration itself.

bdd-cucumber-gherkin-lib-security adds the Gherkin sentences, the lifecycle hooks and the Spring Boot auto-configuration on top. A project that uses the sentences needs no change — the core module comes in transitively, the sentences, tags, properties and beans are unchanged.

Driving the scan from a test suite that is not Cucumber:

val properties = SecurityScanProperties(enabled = true)

SecurityScanSession(properties, ZapSecurityScanner.create(properties)).use { session ->
    val proxy = session.start(hostPorts = setOf(port))

    // route the HTTP client of the tests through proxy.host:proxy.port, then run the traffic

    session.scanAndVerify(maxDuration = Duration.ofMinutes(30), failFrom = SecurityRisk.MEDIUM)
}

A jUnit 5 extension wraps the same session around a test class:

@RegisterExtension
val securityScan = SecurityScanExtension(
    properties = properties,
    scanner = ZapSecurityScanner.create(properties),
    maxDuration = Duration.ofMinutes(30),
    failFrom = SecurityRisk.MEDIUM,
    hostPorts = Supplier { setOf(port) }
)

The time budget and the risk that fails the build stay parameters rather than properties, so nothing can silently weaken the gate.

Setup, configuration and the caveats are documented in bdd-cucumber-gherkin-lib-security-core/README.md.

Changes

Security scan internals

These only concern a project that reached past the Gherkin sentences into the beans of the security module.

  • SecurityScanProperties no longer carries @ConfigurationProperties; it is a plain data class so the core module stays free of Spring. SecurityScanBeanConfig binds the prefix — named by SecurityScanProperties.PREFIX — with a Binder, which gives the same relaxed, constructor based binding. Configuration files are unchanged.
  • The SecurityScan bean is replaced by a SecurityScanSession bean, which owns the scan and the scanner lifecycle. The hook and the steps share it, so the target list and the attack always work on the same state.
  • The ZapContainer and ZapApiClient beans are gone. ZapSecurityScanner.create(properties) builds the stack, and the single SecurityScanner bean stays @ConditionalOnMissingBean, so replacing the scanner still costs one bean.
  • The ZAP API client now uses the JDK HTTP client instead of Spring’s RestClient. The jdk.httpclient.allowRestrictedHeaders=host system property the setup already required is unchanged.

Release 3.9.0

New features

New module bdd-cucumber-gherkin-lib-security

Dynamic application security testing (DAST) driven from the Cucumber suite that already exists.

A @Before hook starts an OWASP ZAP container, exposes the ports of the application under test to it and routes the HTTP client of the library through its proxy. Every request the functional scenarios make is recorded, and a final scenario attacks that recorded traffic, writes a report and fails the build on findings:

@securityScan
Feature: Security scan

    @securityExecuteScan
    Scenario: scan the application and fail on relevant findings
        Then I run the security scan for max. 30 minutes and fail on findings of risk "MEDIUM" or higher

No step code is needed in the consuming project — one test dependency, the glue package and a profile:

cucumbertest:
    security:
        enabled: true
        target:
            host: host.testcontainers.internal
            exposed-ports: ["${server.port}"]

The time budget and the risk that fails the build are sentence parameters rather than properties, so a feature file states its own limits and no profile can silently weaken the gate.

Nothing a project writes names a scanner: the tags, the properties and the sentences are all security*. Replacing ZAP means publishing one SecurityScanner bean — every ZAP bean is @ConditionalOnMissingBean(SecurityScanner), so no feature file, tag, property or Gradle task changes.

The module is not part of the bdd-cucumber-gherkin-lib bundle: it needs Docker and is only useful for the runner that executes the scan. Add it explicitly, next to the REST module.

Setup, configuration reference, replay mode and the granular sentences are documented in bdd-cucumber-gherkin-lib-security/README.md.

Release 3.8.0

New features

Applications with more than one port

Tests no longer need a protocol, host or port for an endpoint that runs on a second port. Every web server the Spring context starts is detected automatically under the name Spring uses for it, so an actuator on its own port is reachable with a plain path and no configuration at all:

Scenario: Read the health endpoint from the management port
  When executing a GET call to "/actuator/health"
  Then I ensure that the status code of the response is 200

Servers that Spring does not start itself — a mock, a side car, a second deployment — are declared once in the application.yml and then addressed the same way:

cucumberTest:
  services:
    payment-mock:
      host: localhost
      port: "${wiremock.server.port}"
      path-prefixes: ["/payments"]

port, host and base-path may contain ${...} placeholders. They are resolved when the request runs and not when the properties are bound, so a random port is always the current one.

base-path is prepended to the URL, while path-prefixes only decides which service a path is routed to. Use path-prefixes when the feature file already spells the prefix out ("/actuator/health") and base-path when it does not ("/health").

New sentence that the service "..." is used

For the cases where a path prefix is not enough, a scenario can name the service explicitly. server is the application itself, so it also switches back to the default:

Scenario: Read a mocked endpoint
  Given that the service "payment-mock" is used
  When executing a GET call to "/v1/payments"
  Then I ensure that the status code of the response is 200

An unknown name fails immediately and lists the names that are available.

Logging and reporting you can actually read

Two things were wrong: the console said nothing while tests ran, and the report put every detail of a call into flat, always-expanded blocks.

On the console, one short line per call now appears with no setup at all:

INFO ScenarioReporter - → DELETE /api/v1/unauthorized
INFO ScenarioReporter - ← 401 UNAUTHORIZED  (12 ms)

Turn it down with logging.level.com.ragin.bdd.cucumber: WARN. A failed scenario is logged with its name and feature location, so a failure is never anonymous. Everything that only the framework cares about — state resets, per-field matcher traces — moved to debug.

For the scenario and step tree, append the new plugin constant to the plugins the project already configures. Cucumber has no way to register a plugin by itself, so this stays explicit:

@ConfigurationParameter(
    key = Constants.PLUGIN_PROPERTY_NAME,
    value = "html:build/reports/cucumber/cucumber.html, " +
        BddLibConfigConstants.Plugin.PLUGIN_PROPERTY_VALUES_DEFAULT
)
Scenario: Unauthorized DELETE call ...              # delete_auth.feature:7
  ✔ Given that the body of the request is
INFO ScenarioReporter - → DELETE /api/v1/unauthorized
INFO ScenarioReporter - ← 401 UNAUTHORIZED  (12 ms)
  ✔ When executing a DELETE call to "/api/v1/unauthorized" with previously given body
  ✔ Then I ensure that the status code of the response is 401

With Gradle this needs testLogging { showStandardStreams = true; exceptionFormat = 'full' }, otherwise nothing is printed and a failure is reduced to an exception type and a line number.

In the report, a call used to produce eight expanded blocks:

Request:
========
HTTP Method: DELETE
HTTP URL   : /api/v1/unauthorized
Response:
========
Status Code: 401 UNAUTHORIZED
Body       : {"error":"unauthorized","error_description":"Full authentication is required"}

It now produces two visible lines and the payloads as collapsed, titled blocks that the report indents for you:

→ DELETE /api/v1/unauthorized
← 401 UNAUTHORIZED  (12 ms)

▸ Request body
▸ Response body

Across the library’s own suite that is 1416 flat log lines down to 404, and 0 up to 256 collapsed attachments. Steps that were silent now report too: the multipart form-data call, the Then validations (with expected-vs-actual attached on a mismatch), the database steps (Liquibase file, SQL file, row count, query result versus CSV) and each polling attempt.

New switches, all optional:

cucumberTest:
  logging:
    request-body: true        # attach the request body
    response-body: true       # attach the response body
    headers: false            # attach headers, credentials obfuscated
    sql: false                # attach the executed SQL
    pretty-json: true         # indent JSON before attaching it
    max-body-length: 8192     # truncate an attached payload beyond this

Credentials are obfuscated before anything is attached. The middle third of a Bearer, Basic or Digest credential is replaced with * so it stays recognisable but not usable, and this applies wherever it appears — including inside a response body that an API echoed back. Sensitive headers are obfuscated by name as well.

Compatibility

  • Every existing feature file and application.yml resolves to the same URL as before. Without cucumberTest.services and without a second port nothing is routed anywhere new, because the server service intentionally claims no path prefix.
  • One behaviour change to be aware of: an application that already runs a management port now answers /actuator/... calls from that port instead of returning 404 from the application port. Set cucumberTest.services.management.path-prefixes: [] to keep the old behaviour.
  • BddProperties gained a constructor parameter and UrlUtils.fullURLFor an optional parameter.
  • The console and report output changed on purpose. Anything that scraped CI logs for Executing call to [GET][...] has to look for → GET ... instead.
  • RequestLoggerUtils is now a class that takes the logging options, and its log field is no longer public. It was only public by omission.
  • ScenarioLoggingHooks takes BddProperties and is no longer final. It is created from the Spring context, where BddProperties is already a bean, so no project configuration changes.
  • Removed, because nothing uses them any more now that the running scenario comes from the scenario state: the scenario parameter of executeRequest and executeUrlEncodedRequest in BaseRESTExecutionGlue, the scenarioState field and injectScenario hook of WhenRESTExecutionGlue, the NotLoggableSubtype enum (superseded by BddReportConstants.NOT_LOGGABLE_SUBTYPES), and the EMPTY_JSON, NEW_LINE, CARRIAGE_RETURN, JSON_SPACING and JSON_COMPACT constants of BddJsonUtils.

Internal changes

  • Coverage was being measured wrong. The integration test module has no src/main, so Kover created no variant for it and silently discarded every binary report it produced.
  • The url-encoded POST sentence had no scenario. It has one now, together with the endpoint it needs, so all three request paths are demonstrated in the feature files.
  • Added unit tests for the parts of the new reporting that a scenario cannot assert: the max-body-length boundary and the header obfuscation decision.
  • The demo application switches cucumberTest.logging.headers and .sql on, so the library’s own report shows what those produce and the obfuscation is exercised end to end.
  • Some housekeeping under the hood: a handful of small glitches that had crept in over time are gone, so a few things now behave the way they always should have.
  • Tightened up the build itself. Tests, coverage and code formatting are checked automatically again instead of being quietly skipped.
  • Two leftovers that nobody was using are now marked as deprecated. They still work, but they will disappear with the next major release.

Release 3.7.0

  • Some dependency updates
  • Added BDD_CUCUMBER_SKILL.md to support development with AI agents
  • Added BDD_CUCUMBER_AGENT_INSTRUCTIONS.md with more detailed instructions for development with AI agents

Release 3.6.0

  • Some dependency updates

Release 3.5.0

Important Update Libraries

  • Spring Boot from 4.0.7 to 4.1.0

New features

Validator json-unit.matches:string-contains and json-unit.matches:string-contains-not

This can compare if a value of a JSON string contains a string or a context value:

Scenario: JSON contains a string
  When executing a GET call to "/api/v1/mydata"
  Then I ensure that the status code of the response is 200
  And I ensure that the body of the response is equal to
  """
  {
    "myfixvalue": "${json-unit.matches:string-contains}mustbethere",
    "myvaluefromcontext": "${json-unit.matches:string-contains}CONTEXT_PARAM"
  }
  """

In this test, the string of the element myfixvalue must contain the value “mustbethere”. The string of the element myvaluefromcontext must contain the value from the scenario context parameter CONTEXT_PARAM. The same can be used with json-unit.matches:string-contains-not to ensure a string does not contain a specific value.

Release 3.4.0

  • Added AI instructions that AI can help with testing or optimization. This means not, that it becomes an AI sloppish library, but for suggestions and findings or testing it is good. Everything is still reviewed manually and in most cases also written manually. But it makes live easier if AI can analyze or suggest something and it is in a proper shape.
  • Moved com.ragin.bdd.BddLibConstants to com.ragin.bdd.constants.BddLibConstants to have a more consistent package usage.
  • Added some tests for internal functions to make it more stable.

Release 3.3.0

Main Library Updates

  • Spring Boot to 4.0.7

Fixes

  • Fixed that json-unit and json-path was not used as transitive dependency.

Release 3.2.0

Bugfix

Fixes the issue, that if a server was configured in the application.yaml (cucumberTest.server.*), that it was not taken into consideration.

Release 3.1.0

Update Libraries

  • Spring Boot to 4.0.6
  • Kotlin to 2.3.21
  • Postgres to 42.7.11
  • Liquibase to 5.0.3

Architecture Changes

Split the project into multiple modules for better maintainability and scalability.

Module Description
bdd-cucumber-gherkin-lib Meta-Package which bundles all modules (compatibility mode)
bdd-cucumber-gherkin-lib-bom Bills of Material for the modules.
bdd-cucumber-gherkin-lib-core Main code like utils, matcher, ScenarioContext.
bdd-cucumber-gherkin-lib-db Database related sentences. This module automatically depends on core.
bdd-cucumber-gherkin-lib-rest REST sentences. If no database sentences are required, this module should be used.

Release 3.0.0

This major release update is a breaking change release in matter of the minimum requirements.

Breaking Changes

This release requires at least the following versions:

  • Spring Boot to 4.0.1
  • Kotlin 2.3.0
  • JDK 25
  • jUnit 6.0.1

Release 2.32.0

Version bumps in build/dependency configs

Cohort / File(s) Summary of Changes
Build file
build.gradle
Spring Boot 3.5.6 → 3.5.9, Kover 0.9.2 → 0.9.4
Dependency file
dependencies.gradle
kotlin-logging-jvm 7.0.13 → 7.0.14, httpclient5 5.5 → 5.5.2, json-unit 4.1.1 → 5.1.0, commons-text 1.14.0 → 1.15.0, commons-io 2.20.0 → 2.21.0, commons-lang3 3.19.0 → 3.20.0, json-path 2.9.0 → 2.10.0.
Configuration for dependency file
gradle.properties
cucumber 7.29.0 → 7.33.0, testcontainers 1.21.3 → 2.0.3, jackson 2.19.2 → 2.20.1.

Release 2.31.0

Version bumps in build/dependency configs; test configuration tweaks for Cucumber patterns; dependency reshuffle from Spring Boot starters to individual modules; introduction of JacksonUtils and migration from org.json; functional error-handling refactors using runCatching across core utils/glue; matcher classes now implement BddCucumberJsonMatcher; new Konsist architectural tests; minor message fix.

Changes

Cohort / File(s) Summary
Build and plugins
build.gradle, gradle.properties
Updated plugin versions (JReleaser, SonarQube, Spring Boot, Kover). Bumped project to 2.31.0 and Cucumber to 7.29.0.
Dependencies restructuring
dependencies.gradle
Replaced Spring Boot starters with granular Spring modules; added Jackson Blackbird, json-path; bumped commons-lang3, snakeyaml, PostgreSQL; added test deps (Kotlin test, Konsist, Spring Boot starters for tests).
Test config
config/gradle/tests.gradle
Narrowed test exclusions to only **/*CucumberRunner*; aligned Cucumber task includes to **/*CucumberRunner*.
Core error-handling refactors
.../core/DatabaseExecutorService.kt, .../glue/BaseRESTExecutionGlue.kt, .../glue/ThenRESTValidationGlue.kt, .../glue/WhenRESTExecutionGlue.kt, .../utils/DateUtils.kt
Replaced try/catch/finally with runCatching and onFailure/also across DB init, REST execution, sleeps, polling logic, and date parsing. DatabaseExecutorService now captures exceptions without rethrowing while always closing connections.
JSON utilities and glue
.../utils/JacksonUtils.kt, .../utils/JsonUtils.kt, .../glue/DatabaseGlue.kt
Added JacksonUtils with an ObjectMapper (Kotlin, JavaTime, Blackbird modules). JsonUtils refactored matcher registration and error handling; DatabaseGlue switched to JacksonUtils.mapper.
Matchers API conformance
.../matcher/NeStringMatcher.kt, .../matcher/ScenarioStateEqContextMatcher.kt, .../matcher/ScenarioStateNeContextMatcher.kt, .../matcher/UUIDMatcher.kt, .../matcher/ValidDateContextMatcher.kt, .../matcher/ValidDateMatcher.kt
Matchers now implement BddCucumberJsonMatcher and add matcherName()/matcherClass() overrides; matching logic unchanged.
Minor message fix
.../core/ScenarioStateContext.kt
Corrected error message typo (“scendario” → “scenario”).
Konsist architectural tests
src/test/kotlin/com/ragin/bdd/architecture/*
Added Konsist-based tests for naming and inheritance conventions in tests, glue, hooks, and matchers.
Unit test modernization
.../utils/DateUtilsTests.kt
Migrated to Kotlin test API; renamed and reformatted assertions.
Test stubs: org.json → Jackson
src/test/kotlin/com/ragin/bdd/cucumbertests/library/test/*
Replaced org.json construction with JacksonUtils.mapper serialization across Authentication, BodyManipulation, CustomDateTime, CustomHeader, FieldValidation, FormData, HeaderCheck, IBANMatcherCheck, JsonTolerance, PathManipulation, Polling, RestErrors, UserSelection. Also updated ParameterizedCustomMultiParameterMatcher to use Jackson and runCatching.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Step as Step Definition
  participant Glue as BaseRESTExecutionGlue
  participant Client as HTTP Client
  participant State as ScenarioState

  Step->>Glue: executeRequest(...)
  rect rgb(240,248,255)
    note right of Glue: runCatching { invoke HTTP }
    Glue->>Client: send(request)
    Client-->>Glue: response or HttpServerErrorException
  end
  alt Success
    Glue->>State: update latestResponse (status/body)
    State-->>Step: OK
  else HttpServerErrorException
    note right of Glue: onFailure branch
    Glue->>State: update latestResponse from error body/status
    State-->>Step: handled error response
  else Other exception
    note right of Glue: onFailure (no special handling)
    Glue-->>Step: propagate/handle upstream as implemented
  end
sequenceDiagram
  autonumber
  participant App as App Startup
  participant DB as DatabaseExecutorService
  participant Conn as DB Connection
  participant LB as Liquibase

  App->>DB: initDatabase(...)
  rect rgb(245,245,245)
    note right of DB: runCatching { update }
    DB->>Conn: getConnection()
    DB->>LB: new Liquibase(...).update(...)
    LB-->>DB: success or exception
  end
  DB-->>Conn: close() (always via also)
  alt Success
    DB-->>App: return (no error)
  else Failure
    note right of DB: exception captured, not rethrown
    DB-->>App: return without error propagation
  end

Release 2.30.0

Changes

Cohort / File(s) Summary of Changes
Bearer Token The default bearer token was not set properly.

Release 2.29.0

Changes

Cohort / File(s) Summary of Changes
Matcher Added some more logging of context and parameter.

Release 2.28.0

Changes

Cohort / File(s) Summary of Changes
Build plugin and Detekt alignment
build.gradle
Spring Boot plugin 3.5.4 → 3.5.5.
Dependency versions and BOM
dependencies.gradle
Bumped io.github.oshai:kotlin-logging-jvm 7.0.12 -> 7.0.13.
Project/version properties
gradle.properties
Version 2.27.0 → 2.28.0; Cucumber 7.27.0 → 7.27.2.

Release 2.27.0

Summary

Release 2.27.0 updates versions across Gradle, Spring Boot, Kotlin, libraries, and Testcontainers. Adds a JUnit 5 BOM, enforces Kotlin alignment for Detekt, tweaks Gradle task configurations (including cucumber with JUnit Platform), updates Gradle wrapper and scripts, and adjusts a test datasource image tag.

Changes

Cohort / File(s) Summary of Changes
Gradle wrapper update
config/gradle/wrapper.gradle, gradle/wrapper/gradle-wrapper.properties, gradlew, gradlew.bat
Bumped Gradle from 8.14.2 to 8.14.3; wrapper scripts now invoke the wrapper jar via -jar and clear CLASSPATH.
Build plugin and Detekt alignment
build.gradle
Spring Boot plugin 3.5.3 → 3.5.4; added resolutionStrategy to force Detekt’s supported Kotlin version for org.jetbrains.kotlin deps in detekt configuration.
Gradle config syntax normalization
config/gradle/detekt.gradle, config/gradle/java.gradle, config/gradle/publishing.gradle
Switched from setter methods to property assignments for report requirements, toolchain languageVersion, artifactId, and version. No functional change.
Test task configuration
config/gradle/tests.gradle
Enabled useJUnitPlatform() for cucumber; set group via property; wired testClassesDirs and classpath from testing.suites.test.
Dependency versions and BOM
dependencies.gradle
Added dependencyManagement importing org.junit:junit-bom:5.13.4; bumped commons-text, commons-io, commons-lang3, kotlin-logging-jvm, liquibase-core.
Project/version properties
gradle.properties
Version 2.25.0 → 2.26.0; Kotlin 2.0.21 → 2.2.10; Cucumber 7.23.0 → 7.27.0; Testcontainers 1.21.2 → 1.21.3; Jackson 2.19.1 → 2.19.2.
Test resource adjustment
src/test/resources/application.yml
Updated Testcontainers PostgreSQL image tag from 16.6 to 17 for cucumberTest datasource.

If you have trouble with Detekt and Kotlin 2.2.10, you can add the following to your build.gradle:

configurations.matching { it.name == "detekt" }.configureEach {
    resolutionStrategy.eachDependency { DependencyResolveDetails details ->
        if (details.requested.group == "org.jetbrains.kotlin") {
            details.useVersion(io.gitlab.arturbosch.detekt.DetektPluginKt.getSupportedKotlinVersion())
        }
    }
}

# Release 2.26.0

n/a -> Maven Central Changes

Release 2.25.0

  • JDK 21 is now minimum requirement
  • jUnit 5 support by default

Update Dependencies

  • Spring Boot 3.5.3
  • Liquibase 4.32.0
  • Cucumber 7.23.0

Migration from jUnit4 to jUnit5

Example from jUnit4:

package com.ragin.bdd.cucumbertests

import io.cucumber.junit.Cucumber
import io.cucumber.junit.CucumberOptions
import org.junit.runner.RunWith

@RunWith(Cucumber::class)
@CucumberOptions(
    features = [
        "classpath:features"
    ],
    glue = [
        "com.ragin.bdd.cucumber.glue",
        "com.ragin.bdd.cucumber.hooks",
        "com.ragin.bdd.cucumbertests.hooks"
    ],
    plugin = [
        "json:build/reports/cucumber/cucumber.json",
        "html:build/reports/cucumber/cucumber.html",
        "junit:build/reports/cucumber/cucumber.xml"
    ],
    publish = true,
    tags = "not @ignore"
)
class CucumberRunner

can be changed to:

package com.ragin.bdd.cucumbertests

import io.cucumber.junit.platform.engine.Constants
import org.junit.platform.suite.api.ConfigurationParameter
import org.junit.platform.suite.api.ExcludeTags
import org.junit.platform.suite.api.IncludeEngines
import org.junit.platform.suite.api.SelectClasspathResource
import org.junit.platform.suite.api.Suite

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(
    key = Constants.GLUE_PROPERTY_NAME,
    value = "com.ragin.bdd.cucumber.glue, " +
            "com.ragin.bdd.cucumber.hooks, " +
            "com.ragin.bdd.cucumbertests.hooks"
)
@ConfigurationParameter(
    key = Constants.PLUGIN_PROPERTY_NAME,
    value = "json:build/reports/cucumber/cucumber.json, " +
            "html:build/reports/cucumber/cucumber.html, " +
            "junit:build/reports/cucumber/cucumber.xml"
)
@ConfigurationParameter(key = Constants.PLUGIN_PUBLISH_ENABLED_PROPERTY_NAME, value = "true")
// @ConfigurationParameter(key = Constants.FILTER_TAGS_PROPERTY_NAME, value = "not @ignore")
@ExcludeTags("ignore")
class CucumberRunner

To include tags, the @IncludeTags annotation can be used. Exclude is possible with @ExcludeTags.

Please note, that the @ is not required in this case.

Release 2.24.0

Update Dependencies

Release 2.23.0

New sentence to set a proxy for the communication at “runtime”

This introduces a sentence for dynamic proxy settings.

Given that a proxy with host "<string>" and port "<string>" is configured

Both the host and the port can either be the host/proxy or a variable from the ScenarioStateContext.

This helps, for example, to set proxies started via test containers (e.g. Burp Scanner or Mock Server) during the test. This way it is not necessary to assign a fixed port to the proxy. This can then be written in another sentence or after starting a proxy container in the ScenarioContext.

Alternatively, the proxy can also be written directly to the ScenarioStateContext:

ScenarioStateContext.current().dynamicProxyHost = "localhost"
ScenarioStateContext.current().dynamicProxyPort = "8808"

Release 2.22.0

Fixes

The SSL configuration has returned a wrong HTTP client configuration, which was not ignoring redirects from the server.

Release 2.21.0

Dependency Updates

All dependencies were updated.

Most noticeable:

  • Spring Boot to 3.4.4

Release 2.20.0

Dependency Updates

All dependencies were updated.

Most noticeable:

  • Spring Boot to 3.4.2
  • Cucumber to 7.21.1

Logging Optimization

Now the logging of the response will only log the body, if it is not a media-subtype of pdf, octet-stream or zip.

Assertions

The internal assertions are now using assertj-core, which is a dependency of spring-test instead of using jUnit 4. jUnit 4 is sadly still a dependency, because of cucumber-junit.

Release 2.18.0

Dependency Updates

All dependencies were updated.

Most noticeable:

  • Spring Boot to 3.4.1
  • Kotlin to 2.0.10

Form Data Optimization

The multi-form-data upload uses now Resource as basis instead of ByteArray. This matches better to the needs of RestTemplate and the MultipartFile on server-side.

The sentence Given that the file "<filename>" is stored as "<context>" stores now the file in the ScenarioContext file map, but also the name of the file in the regular map under the same key. This is required, because the filename is required for multi-form-data uploads.

Release 2.17.0

The configuration

cucumberTest:
  authorization:
    ...

is no longer required. It must be set, if a default token can be used. Else the token must be provided via Background or inside of the Scenario.

Release 2.16.0

  • Spring Boot to 3.3.3
  • liquibase-core to 4.29.1

Release 2.15.0

  • Fixed issues with BOM’s. It was not possible to resolve the transitive dependencies.

Release 2.14.0

Updated Gradle structure, code analysis and coverage

  • Updated Gradle structure and split each configuration into separate files
  • Replaced jacoco with kover
  • Updated Gradle task for cucumber
  • Added Detekt for static code analysis

Updated Libs

  • Spring Boot to 3.3.2
  • liquibase-core to 4.29.0
  • Cucumber libs to 7.18.1

Release 2.12.0

Updated Libs

  • Spring Boot to 3.2.5
  • Cucumber Libs to 7.18.0
  • liquibase-core to 4.27.0

Features

Added a new default matcher (${json-unit.matches:isNotEqualTo}string) to compare, that a value is not equal to a given string. The string can be anything after the closing bracket:

{
  "string": "${json-unit.matches:isNotEqualTo}another string"
}
  Scenario: Validate field with a string that it is not the value
When executing a GET call to "/api/v1/fieldValidation"
Then I ensure that the status code of the response is 200
And I ensure that the body of the response is equal to
"""
      {
        "string": "${json-unit.matches:isNotEqualTo}another string",
        "number": 12,
        "boolean": true,
        "list": [
          "First",
          "Second"
        ],
        "object": {
          "firstname": "John",
          "lastname": "Doe"
        },
        "uuid": "${json-unit.matches:isValidUUID}",
        "objectList": [
          {
            "first": 1,
            "second": 2
          },
          {
            "first": 3,
            "second": 4
          }
        ]
      }
    """

See src/test/resources/features/body_validation/field_compare.feature

Release 2.11.0

Updated Libs

  • Spring Boot to 3.2.4
  • Cucumber Libs to 7.16.1
  • liquibase-core to 4.26.0

Release 2.10.0

  • Removed Accept-Language default header.

Release 2.9.0

Updated Libs

  • Spring Boot to 3.2.3
  • Cucumber Libs to 7.15.0
  • liquibase-core to 4.26.0

Release 2.8.0

Updated Libs

  • Spring Boot to 3.2.0
  • Cucumber Libs to 7.14.1
  • liquibase-core to 4.25.0

Release 2.7.0

Updated Libs

  • Spring Boot to 3.1.4
  • Cucumber Libs to 7.14.0
  • json-unit to 3.2.2
  • liquibase-core to 4.24.0

Features

Added a new default matcher (${json-unit.matches:isNotEqualToScenarioContext}MY_CONTEXT_VALUE) to compare, that a value is not equal to the context:

    And I ensure that the body of the response is equal to
""" 
        {
          "value": "${json-unit.matches:isNotEqualToScenarioContext}MY_CONTEXT_VALUE",
        }
      """

Release 2.6.1

Small fix for URL encoded calls, to be able to leave a value empty if the parameters are dynamic.

Release 2.6.0

New sentence added for application/x-www-form-urlencoded POST calls.

When executing a url-encoded POST call to "/api/form-encoded" with the fields
| Key    | Value         |
| first  | myFirstValue  |
| second | mySecondValue |

The first line of the fields MUST contain | Key | Value |.

Release 2.5.1

In some cases, a @PostConstruct annotation was not executed in the correct order. This has now been taken care of by moving the logic it contains to a constructor.

Release 2.5.0

  • Fix for URLs with http(s)://

Release 2.4.0

Logging of requests and responses

Now all executing sentences log the request and response as scenario text in the report. This makes problems in tests more visible on CI/CD scenarios.

Example:

When executing a GET call to "/api/v1/unauthorized"
  Request:
  ========
  HTTP Method: GET
  HTTP URL   : /api/v1/unauthorized
  Response:
  ========
  Status Code: 401 UNAUTHORIZED
  Body       : {"error_description":"Full authentication is required to access this resource","error":"unauthorized"}

Release 2.3.0

New sentence

Given that the request body in the scenario context map has been reset

This sentence resets the body if a scenario uses 2 requests and the second should be empty.

Release 2.2.0

Feature

  • Logs the http method and URL for each request to have a better overview what was called with dynamic URLs.

Release 2.1.0

Update Libraries

  • Spring Boot updated to 3.1.2

New matcher

  • A new matcher for IBANs was added. The syntax is ${json-unit.matches:isValidIBAN}.

Release 2.0.1

This release requires Java 17 and Spring Boot 3. It uses also the jakarta.* packages instead of the javax.* packages.

Update Libraries

  • Spring Boot updated to 3.1.1
  • Liquibase updated to 4.23.0
  • Cucumber updated to 7.13.0
  • Apache HTTP Client updated to 5.2.1

Release 1.52.0

Update Libraries

  • Cucumber updated to 7.11.2
  • Spring Boot updated to 2.7.10
  • Liquibase updated to 4.20.0
  • Snakeyaml updated to 2.0

Release 1.51.0

Update Libraries

  • Cucumber updated to 7.11.1
  • Spring Boot updated to 2.7.8
  • Liquibase updated to 4.19.0

Release 1.50.0

Update Libraries

  • Cucumber updated to 7.9.0
  • Spring Boot updated to 2.7.5
  • Liquibase updated to 4.17.2

Release 1.49.0

Update Libraries

  • Cucumber updated to 7.5.0
  • Spring Boot updated to 2.7.2
  • Liquibase updated to 4.14.0

Fixes

The sentence I store the string of the field "{string}" in the context "{string}" for later usage is now able to store any kind of objects and not only strings.

Release 1.48.0

Updated Libraries

  • Cucumber updated to 7.3.4
  • Liquibase updated to 4.10.0 (CVE-fix)
  • JSON-Unit to 2.35.0

Release 1.46.0

Updated Libraries

  • Spring Boot updated to 2.6.7
  • Cucumber updated to 7.3.2

Feature: Simple form-data POST request

It is now possible to create a simple form-data POST request. A file can also be attached in the process.

To add the file there is the sentence:

Scenario: Post form data
Given that the file "test.txt" is stored as "FORM_FILE"

The file is placed as a byte array in a separate context, which is emptied again after the scenario is completed for memory reasons.

To execute a form-data request the following sentences are available:

When executing a form-data POST call to "/your/api" with the fields
| text-form-data-key  | text-form-data-value      |
When executing an authorized form-data POST call to "/your/api" with the fields
| text-form-data-key  | text-form-data-value      |

The fields are written as key/value datamap.

Examples can be found at src/test/resources/features/form_data/.

Release 1.45.0

  • Updated Spring Boot to 2.6.6 to avoid issues with Spring Shell.

Release 1.44.0

  • Disable redirects for HTTP client.

Release 1.43.0

Updating dependencies

  • Spring Boot 2.6.4

Release 1.42.0

An issue was fixed, which prevented to overwrite the Accept-Language, Content-Type and Accept headers.

Release 1.41.0

Updated libraries

  • Spring Boot updated to 2.6.2
  • Cucumber updated to 7.2.2

Extended Polling

Polling now allows also to check for the HTTP code only.

Unauthorized Example

Scenario: Polling unauthorized until response code is correct with long config
Given that a requests polls every 1 seconds
And that a requests polls for 5 times
And that the API path is "/api/v1/polling"
When executing a GET poll request until the response code is 200

Authorized Example

Scenario: Polling authorized until response code is correct with short config
Given that a request polls every 1 seconds for 5 times
And that the API path is "/api/v1/pollingAuth"
When executing an authorized GET poll request until the response code is 200

Examples can be found at src/test/resources/features/polling/.

Extended Header Manipulation

Prefix for Header manipulation

Scenario: Add custom header with prefix
Given I set the header "X-My-Custom-Header" to "ABC_DEF" prefixed by "PRE_"

This sets the header X-My-Custom-Header to the value of ABC_DEF with the prefix PRE_. The prefix and the value can be also a variable name from the context.

Please have a look to the examples at: src/test/resources/features/header/

Release 1.40.0

Updated libraries

  • Spring Boot updated to 2.6.1
  • Cucumber updated to 7.1.0

Release 1.39.0

Updated libraries

  • Spring Boot updated to 2.5.6 because of a memory leak in tomcat
  • Cucumber updated to 7.0.0

Enhancements

Added check for headers

If it is required to check if a HTTP header contains a special value, this can be done with the following sentence:

And I ensure, that the header "<header name>" is equal to "<header values>"

Be aware, that headers are always an array. If there are more header values you want to check, please add them comma separated.

Example:

Scenario: Check a header
When executing an authorized GET call to "/api/v1/header"
Then I ensure that the status code of the response is 200
And I ensure, that the header "X-TEST-HEADER" is equal to "present"

This might be used to check if XSS headers are set for example.

See src/test/resources/features/header/header.feature

Release 1.37.0

Updated libraries

  • Spring Boot updated to 2.5.5
  • Cucumber-JVM updated to 6.11.0

Release 1.36.0

Updated libraries

  • Spring Boot updated to 2.5.2
    • With the Spring update Liquibase will also be updated to 4.3.5
  • Cucumber-JVM updated to 6.10.4
  • Json-Unit updated to 2.27.0

Small enhancements

A user token can be resolved also from context map. If nothing was found there, it uses the given one. This refers to the following sentences:

  • that the following users and tokens are existing
  • that the user is {string}

In general the ScenarioStateContext class has now a new method called resolveEntry(key: String). This method tries to read the value from the context map for the given key. If the key was not found, it returns the key itself. This may be helpful for own sentences based on the context map.

Possibility to wait

There is a new sentence that allows you to wait some time before proceeding:

  Scenario: Wait for something
Then I wait for 1000 ms

Examples at: src/test/resources/features/performance/performance.feature

Release 1.35.0

Introduction of date util sentences and extended date validators.

This version introduces some Given sentences to create a date in the past or future. In addition, there is a new matcher that allows to compare this date with a JSON date or a datetime.

Read more at: docs/date_operations.md.

Examples at: src/test/resources/features/date_operations/date_operations.feature

Release 1.34.1

An issue with the new configuration was fixed.

The introduction of the BddProperties class made some problems with not configured properties.

Please ensure also, that you’ve put the library on the configuration scan path:

@ConfigurationPropertiesScan({
        "com.ragin.bdd", "configuration.com.ragin.bdd"
})

Release 1.34.0

Updates

This release updates the Spring dependency to 2.4.5.

It is recommended to update the project also to this version.

New groupId and Maven Central deployment

Because of the deprecation of jcenter, the artifacts are now published on Maven Central.

To be able to do that, the groupId has to be changed to:

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

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

Release 1.32.0

Support for predefined ScenarioContext values

In order to predefine some global ScenarioContext values outside the gherkin definition, it is now possible to add them to the application.yaml/application.properties file.

The key cucumberTests.scenario-context allows to define a set of key/value pairs for the ScenarioContext map:

application.yaml

cucumberTests:
  scenario-context:
    CTX_PRE_DEFINED_USER: Pre Defined
    CTX_PRE_DEFINED_FIRST_ID: abcdefg

application.properties

cucumberTests.scenario-context.CTX_PRE_DEFINED_USER=Pre Defined
cucumberTests.scenario-context.CTX_PRE_DEFINED_FIRST_ID=abcdefg

If many tests require the same data over and over again, it doesn’t make sense to copy and maintain it in every feature.

By defining it in the application file, it can be defined once and used everywhere.

For an example, please have a look at:

Release 1.31.0

Supports dynamic URL’s

This version supports the usage of ScenarioContext variables for all URI parameters.

Now it is allowed to write sentences like:

Scenario: Use dynamic URL
Given that the context contains the following 'key' and 'value' pairs
| ${MY_DYNAMIC_URL} | https://google.com |
And that the API path is "${MY_DYNAMIC_URL}"

Release 1.30.0

Support for polling APIs

The polling configuration is automatically reset before each scenario. It can be configured via the background or directly in the scenario.

When the expected HTTP status code and JSON structure has been sent as a response, polling will stop. This allows an endpoint to be polled until it changes state or fail if the state has not changed during the specified time and retry configuration.

The configuration can be done in to ways.

As a single line configuration:

Scenario: Single line configuration
Given that a request polls every 1 seconds for 5 times

Or as a multiline configuration that supports to specify one of the configurations in the Background and the other in the Scenario (or to have it more readable).

Scenario: Multiline configuration
Given that a requests polls every 1 seconds
And that a requests polls for 5 times

The URL/URI and (if required) body have to be preconfigured. Polling itself does simply use previous set body and path definition. To execute a request it supports the well known authorized and unauthorized phrases and it supports direct JSON or JSON from file:

Authorized request with JSON response file:

Scenario: Authorized request with JSON response file
Given that a request polls every 1 seconds for 5 times
And that the API path is "/api/v1/polling"
When executing an authorized GET poll request until the response code is 200 and the body is equal to file "expected.json"

Unauthorized request with JSON response file:

Scenario: Unauthorized request with JSON response file
Given that a request polls every 1 seconds for 5 times
And that the API path is "/api/v1/polling"
When executing a GET poll request until the response code is 200 and the body is equal to file "expected.json"

Authorized request with direct JSON response:

Scenario: Authorized request with JSON response file
Given that a request polls every 1 seconds for 5 times
And that the API path is "/api/v1/polling"
When executing an authorized GET poll request until the response code is 200 and the body is equal to
"""
    {
      "message": "SUCCESSFUL"
    }
    """

Unauthorized request with direct JSON response:

Scenario: Unauthorized request with JSON response file
Given that a request polls every 1 seconds for 5 times
And that the API path is "/api/v1/polling"
When executing a GET poll request until the response code is 200 and the body is equal to
"""
    {
      "message": "SUCCESSFUL"
    }
    """

Examples can be found at src/test/resources/features/polling/.

Release 1.29.1

Support for database-less applications

This version introduces support for applications that do not have a database. To configure the library to run database-less, it is necessary to set up the following configuration in the application.yaml file:

application.properties:

cucumberTest.databaseless=true

or

application.yaml:

cucumberTest:
  databaseless: true

If the databaseless key is not true or missing, the library tries to instantiate the database related beans.

In some cases it is required to disable the database autoconfiguration of Spring Boot:

application.properties:

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration, org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration

or

application.yaml:

spring:
  autoconfigure:
    exclude: org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration, org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration

or as annotation:


@EnableAutoConfiguration(exclude = {DataSourceAutoConfiguration.class, DataSourceTransactionManagerAutoConfiguration.class, HibernateJpaAutoConfiguration.class})
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        ApplicationContext ctx = SpringApplication.run(Application.class, args);
    }
}

Please also make sure that the @ContextConfiguration annotation does not contain the DatabaseExecutorService.class.

Release 1.28.0

Proxy support

This can be useful to use the cucumber tests together with burp-scanner.

The proxy can be configured with:

application.properties:

cucumberTest.proxy.host=localhost
cucumberTest.proxy.port=8866

or

application.yaml:

cucumberTest:
  proxy:
    host: localhost
    port: 8866

The host can be an IP or a domain. The port must be higher than 0. If a condition is not met, the proxy is not set.

Default is deactivated.

Disable SSL verification

Along with proxy support, it may be necessary to disable SSL validation as well.

This can be configured via:

application.properties:

cucumberTest.ssl.disableCheck=true

or

application.yaml:

cucumberTest:
  ssl:
    disableCheck: true

Default is false.

Release 1.27.0

Code changes

The Java code was refactored to Kotlin. This should make the code more robust and better maintainable.

Enhanced tests

Tests for the database features were added under src/test/resources/features/database/.

Release 1.26.0

Small bugfix release for proper mismatch messages of the matchers.

Release 1.24.0

New features

Validate execution time of requests

Scenario:
Then I ensure that the execution time is less than {long} ms

Validates, that the execution of the Scenario has taken less than [n] ms.

Please have a look to the examples at: src/test/resources/features/performance/.

Release 1.23.0

Dependency updates

This release updates some dependencies.

Set the Bearer token dynamically

To be able to set dynamic bearer token, the following sentence can be used:

Feature: Bearer Token

  Scenario: Set bearer token directly
    Given that the Bearer token is "abcdefg"

This sentence is primary looking into the context map, if there is a key with the given value. If this is not the case, it uses the given string directly as the token.

Please have a look to the examples at: src/test/resources/features/header/

Release 1.22.0

The BddCucumberDateTimeFormat for custom date/time formatters has been changed from List<String> with a list of patterns as string to List<DateTimeFormatter>.

Release 1.21.0

Dependencies

Update of dependencies and Cucumber library 6.8.1.

Add own patterns for ${json-unit.matches:isValidDate}

To add own DateTimeFormatter patterns to extend the ${json-unit.matches:isValidDate} range a new class is required that implements the interface BddCucumberDateTimeFormat. The method pattern() must return the date patterns as List<String>.

To register this custom class it is necessary to add it @ContextConfiguration classes definition.

Example:

Release 1.20.7

Added new DateFormatter for database comparison: yyyy-MM-dd HH:mm:ss.SSSSSS.

Release 1.20.6

The relative file paths and the absolutePath: keyword are now also valid for loading liquibase scripts.

Release 1.20.5

The executor of the Liquibase scripts has sometimes problems with H2 memory databases, that the H2 connection is closed after the JDBC connection is closed.

This problem can now be solved by setting the following properties:

cucumberTest.liquibase.closeConnection=false

or

cucumberTest:
  liquibase:
    closeConnection: false

The default value is false, which means, that the connection will not be closed.

Release 1.20.4

Adds support to define the target server, if the test library should be used for various tests in an outsourced test repository.

It is now possible to overwrite the protocol, host and port in the application.yaml/application.properties:

application.properties:

cucumberTest.server.protocol=http
cucumberTest.server.host=localhost
cucumberTest.server.port=80

or

application.yaml:

cucumberTest:
  server:
    protocol: "http"
    host: "localhost"
    port: 80

All parameters are optional. If nothing is being defined, it uses the default http://localhost:<LocalServerPort>.

Release 1.20.3

Now it is allowed to use full paths instead of only URIs. This may help if between some external systems has to be called.

The library checks if the path starts with http:// or https://. In these cases, it does not add localhost.

Release 1.20.2

This release fixes the problem, that the sentence to set a header value does not resolve the value first from the context.

Now it is possible to use static values or (if the value matches to the context) previously stored parameters.

Example:

src/test/resources/features/header/

Release 1.20.1

The REST template has thrown an exception in case of 5xx response codes.

This version fixes the issue and returns the correct HTTP code and message.

Release 1.20.0

Introducing user

Define user(s)

With the following sentence it is possible to define multiple users:

Feature: User features

  Background:
    Given that the following users and tokens are existing
      | john_doe   | my_auth_token_for_john_doe    |
      | johana_doe | my_auth_token_for_johana_doen |

Now every scenario in this feature can use the user with:

  Scenario: Using authorized user john_doe
Given that the user is "john_doe"

The library selects the right token from the given list and executes the calls with this user. It is also possible to define both in the Background specification. Then all tests will have this user as default:

Feature: User features in global context

  Background:
    Given that the following users and tokens are existing
      | john_doe | my_auth_token_for_john_doe |
    And that the user is "john_doe"

Please have a look to the examples at: src/test/resources/features/user/

Release 1.19.0

Fewer sentences but still compatible and more possibilities

This release introduces the parameter {httpMethod} which replaces all sentences with an HTTP method in the name. Allowed values are:

  • GET
  • POST
  • DELETE
  • PUT
  • PATCH

This reduces the number of Gherkin sentences by 24 and adds 24 new possible sentences because the shorter GET sentences are now also available for all other methods.

Validate only special fields of the response body

Validation of one field

  Scenario: Validate field of the body
Then I ensure that the body of the response contains a field "list[0]" with the value "First"
And I ensure that the body of the response contains a field "$.list[1]" with the value "Second"
Then I ensure that the body of the response contains a field "shouldNotExist" with the value "@bdd_lib_not_exist"

Validation of multiple fields

  Scenario: Validate multiple fields
And I ensure that the body of the response contains the following fields and values
| string           | is a string                 |
| number           | 12                          |
| uuid             | ${json-unit.matches:isUUID} |
| $.number         | @bdd_lib_not 15             |
| list             | ["First","Second"]          |
| list[0]          | First                       |
| $.list[0]        | BDD_TEST_LIST_FIRST_ELEMENT |
| $.list[1]        | Second                      |
| object.firstname | John                        |
| object.lastname  | Doe                         |
| shouldNotExist   | @bdd_lib_not_exist          |

In this case, the fields that should be compared can be given as a data table map. The first column is the field name, the second the expected value.

Description

This sentence compares only the given field of the response. The field can be a JSON path. The library checks if it starts with $.. If it does not start with $. it will be added internally.

To test if a field is NOT present, the reserved word @bdd_lib_not_exist can be used as the value.

To test if a value is NOT the expected value, the reserved word @bdd_lib_not can be used to negate the comparison. It is not possible to use a ! as a negation prefix, because it can also be a valid result.

The library also tries to resolve the value from the context map. If nothing was found, the original value is used.

It is also possible to use JSON-Matcher (user-defined and bdd-cucumber-lib). These are written with the notation ${json-unit.matches:isUUID} (as an example for the UUID-Matcher).

ATTENTION: Only unparameterized custom matchers or bdd lib-matchers can be used for field validation!

Find examples for this feature under: src/test/resources/features/body_validation/.

Reset the scenario context

Scenario: Reset the scenario context
Given that the stored data in the scenario context map has been reset

Reset the context state map.

Release 1.18.0

Configure the JSON compare to ignore extra elements in arrays

Scenario:
Given that the response JSON can contain arrays with extra elements

It is also possible to use the @bdd_lib_json_ignore_new_array_elements annotation on Feature or Scenario level.

With this sentence or annotation, the JSON comparison will ignore new array elements.

See src/test/resources/features/flexible_json/ for examples.

Configure the JSON compare to ignore the order of arrays

Scenario:
Given that the response JSON can contain arrays in a different order

It is also possible to use the @bdd_lib_json_ignore_array_order annotation on Feature or Scenario level.

With this sentence or annotation, the JSON comparison will ignore the order of arrays.

See src/test/resources/features/flexible_json/ for examples.

Configure the JSON compare to ignore extra fields

Scenario:
Given that the response JSON can contain extra fields

It is also possible to use the @bdd_lib_json_ignore_extra_fields annotation on Feature or Scenario level.

With this sentence or annotation, the JSON comparison will ignore new/not defined fields in the response.

See src/test/resources/features/flexible_json/ for examples.

Release 1.17.0

Absolute file path support

Files can be added as a relative path to a previously given base path or with an “absolute” path with the prefix absolutePath:. In the last case, the system is using the base classpath as root.

Validate response HTTP code and body together

Scenario:
Then I ensure that the response code is 201 and the body is equal to
"""
    {
      "field": "value",
    }
    """

In this case, the response status code is part of the sentence, and the JSON is written directly under the sentence and enclosed in three double quotation marks. Here it is also possible to use JSON Unit syntax to validate dynamic elements.

Validate response HTTP code and body together with a JSON file

Scenario:
Then I ensure that the response code is 200 and the body is equal to the file "response.json"

In this case, the response status code, and the JSON file are written together in one sentence. Here it is also possible to use JSON Unit syntax to validate dynamic elements.

Release 1.16.0

  • Changing the body manipulation with creating numbers from <number> characters to <number> bdd_lib_numbers (e.g. 10 bdd_lib_numbers).
  • Adding bdd_lib_uuid to generate random UUIDs
  • Adding a ${json-unit.matches:isValidUUID} which checks, if the string is a valid UUID
  • Fixed Authorization header, that this header is only available once, when it is overwritten
  • Adding a lot of tests as examples

Release 1.15.0

Adding support in the paths to support templates. If the path contains something like:

/api/v1/${dynamicElement}/

In this case, the dynamicElement will be replaced, if it exists in the ScenarioContext.

Support for adding static key/value pairs to the context:

Release 1.14.0

Adding support for the JSON path to the “I set the value of” sentence. It now also tries to resolve the value from the ScenarioContext. If nothing is found, it uses the original value.

Release 1.13.0

Adding support for JSON path to the “I store” sentence.

The JSON path can be used with:

$.firstElement[3].nextElement

The library detects, if the path has the prefix $.. If it is not available, it adds this prefix.

Release 1.12.0

  • Adding support for adding and manipulating headers.
  • Restructured the documentation: HTTP Methods have now their own md files.

Release 1.11.0

  • Adding support for JSON matcher which can compare to values in the ScenarioContext. More information: README.md
  • Adding support for own custom matcher. More information: README.md

Release 1.9.0

  • Correction of the sentence ^that the body of the response is$ to ^that the body of the request is$