DEV Community: Paul Brooks

A Cucumber Alternative for Kotlin and Java

Paul Brooks — Thu, 01 Oct 2026 19:53:56 +0000

Cucumber earns its place on one kind of test: an acceptance test whose output someone outside the development team reads. A tester, an analyst, a product owner. That reader is the only reason to put Given-When-Then on a test at all. Unit tests are code, and developers can read code.

I wrote Kensa for that reader, and it works the same in Kotlin and Java. This post takes a Cucumber scenario, moves it to Kensa, and maps the rest of Cucumber's concepts across, so you can see what a move involves before you start one. If you want the argument for dropping feature files first, that's in BDD Without Gherkin.

One scenario, before and after

The scenario comes from Clearwave, an example order service that provisions voice and broadband through two suppliers. One supplier rejects the order. In Cucumber:

Feature: Order Service

  Scenario: Order is rejected by FibreVision
    Given OpenNetwork will complete the order
    And FibreVision will reject the order
    When a voice and broadband order is placed
    Then the order confirmation should be pending
    And eventually FibreVision should report the order rejected

With step definitions along these lines:

Kotlin

class OrderSteps(private val world: OrderWorld) {

    @Given("{word} will reject the order")
    fun supplierWillRejectTheOrder(supplier: String) {
        stubFor(supplier).primeOrder(world.trackingId, OrderScenario.Rejected)
    }

    @When("a voice and broadband order is placed")
    fun aVoiceAndBroadbandOrderIsPlaced() {
        world.confirmation = orderService.place(world.anOrder())
    }

    // and three more
}

Java

public class OrderSteps {
    private final OrderWorld world;

    public OrderSteps(OrderWorld world) {
        this.world = world;
    }

    @Given("{word} will reject the order")
    public void supplierWillRejectTheOrder(String supplier) {
        stubFor(supplier).primeOrder(world.getTrackingId(), OrderScenario.Rejected.INSTANCE);
    }

    @When("a voice and broadband order is placed")
    public void aVoiceAndBroadbandOrderIsPlaced() {
        world.setConfirmation(orderService.place(world.anOrder()));
    }

    // and three more
}

The same test in Kensa, as it stands in the example project:

Kotlin

@Test
fun `order is rejected by fibre vision`() {
    given(openNetworkWillCompleteTheOrder())
    and(fibreVisionWillRejectTheOrder())

    whenever(aVoiceAndBroadbandOrderIsPlaced())

    then(theOrderConfirmation(), shouldBePending())
    thenEventuallyFibreVisionNotifications(shouldBeRejected(
        supplier = fixtures[broadbandSupplier],
    ))
}

Java

@Test
void orderIsRejectedByFibreVision() {
    given(openNetworkWillCompleteTheOrder());
    and(fibreVisionWillRejectTheOrder());

    whenever(aVoiceAndBroadbandOrderIsPlaced());

    then(theOrderConfirmation(), shouldBePending());
    thenEventually(Duration.ofSeconds(10), fibreVisionNotifications(), shouldBeRejected(
        fixtures(BROADBAND_SUPPLIER)
    ));
}

Kensa parses that method at runtime and renders it as the scenario. Each call becomes a sentence, and the broadband supplier fixture renders as the value it held on this run, so the report says FibreVision, not the name of a variable.

Each step definition becomes a function:

Kotlin

private fun fibreVisionWillRejectTheOrder() = Action<GivensContext> { (fixtures) ->
    fibreVisionStub.primeOrder(fixtures[trackingId], OrderScenario.Rejected)
}

Java

private Action<GivensContext> fibreVisionWillRejectTheOrder() {
    return ctx -> fibreVisionStub.primeOrder(ctx.getFixtures().get(TRACKING_ID), OrderScenario.Rejected.INSTANCE);
}

The body is the step definition's body. What's gone is the string that bound it. The method name is the sentence, so there's no regular expression to match and nothing for a rename to break.

The function can live in the test class, as it does here, or anywhere the tests can call it. A step used across several test classes goes in a base class or a shared helper, the same way you'd share any other code, and it reads the same in every report that uses it.

Everything else Cucumber gives you

Cucumber	Kensa
Feature file and step definitions	The test method, rendered as sentences
Step definition	A function returning an `Action` or a `StateCollector`, in the test class or shared
Feature description	`@Notes` on the test class, with markdown and links
`Background`	A `SetupStep`, written once and passed to `given`
Scenario Outline and Examples	`@ParameterizedTest`, with `@ParameterizedTestDescription` naming each row
Data table	`@ExpandableRenderedValue(renderAs = Tabular)`
World or scenario context	Fixtures for inputs, captured outputs for results
Tags	Your framework's tags, plus `@Issue` and `@Epic`
Hooks	Your framework's lifecycle, unchanged

A few of those are worth a sentence more.

Fixtures replace the World. A Cucumber World is a bag of mutable state that the steps write to and read from. Kensa fixtures are declared once, typed, created lazily and fresh for each test, and they can depend on each other. A tracking ID, a customer, an address built from both. Because they're named, the report shows each one by name wherever the test uses it.

Fresh fixtures make parallel runs safe. Nothing is shared between tests, so they can run at the same time against the same deployed services. Clearwave gives every test its own trackingId fixture and sends it as a header on each request. The supplier stubs use it to route primed responses and captured messages back to the test that caused them, so each report shows only its own traffic while the whole suite runs in parallel. The report's overview shows what that saved: wall clock against total elapsed, and the speed-up.

Scenario Outlines become parameterised tests. Each row of the examples table is an invocation, and @ParameterizedTestDescription gives each one a readable label in the report instead of a list of arguments.

Tags link to the ticket. @Issue("PROJ-42") puts a badge on the test that opens the ticket, and the report can be filtered by issue or epic. If the acceptance criteria were written in Jira, the person who wrote them can get from there to what ran.

What the report adds

This is where a move stops being a translation.

A Cucumber report shows the scenario, green or red. An acceptance test against a running system does more than that. It sends requests, the system talks to other services, and responses come back. Kensa records those interactions while the test runs. The order test above captures the order request, the confirmation, and each notification the two supplier stubs send back. The report shows them as a sequence diagram drawn from that traffic, and each message opens to its full payload.

For the reader this post started with, that's the difference. They can see what the system did, in order, with the data, without opening the code. The Clearwave example report has this test in it, as OrderServiceTest and OrderServiceJavaTest, along with the rest of the suite.

Moving a suite across

You don't have to do it in one go. Cucumber JVM and Kensa both run on the JUnit Platform, so one build can run both suites while you move scenarios over one at a time. Most of the work is moving step definition bodies into functions and deleting the strings.

There's a cost. Kensa is opinionated about how a test reads, since the test body is what the reader sees. It has more machinery than a test library, and it doesn't have Cucumber's twenty years of Stack Overflow answers.

When Kensa isn't the answer

If nobody outside the team reads the output, you don't need Cucumber or Kensa. Write plain tests. BDD in Kotlin covers the wider field.

Kensa is open source. The Kotlin and Java quickstarts take about five minutes.

BDD in Kotlin: The Options, and How to Choose

Paul Brooks — Wed, 16 Sep 2026 08:27:34 +0000

I've been writing acceptance tests on the JVM since 2009. Concordion first, then Cucumber on the teams around me, then Yatspec, and eventually I wrote my own.

Yatspec's trick was that it read the test method itself. You wrote:

given(orchestration.sends(anOrder));

and the report showed:

Given orchestration sends an order

No feature file, no step definitions, no glue. The test was the sentence.

That's the idea I've been chasing ever since, and it's why I wrote Kensa. So this is a biased guide. It's also a short one.

The question that decides it

Everyone starts by comparing syntax. That's the wrong place to start.

The question is: who reads the output, and do they have to?

If the answer is "the developers", don't add a framework. Kotest or JUnit with well-named tests does everything you want, and anything layered on top is costing you time for nothing.

If the answer is "a tester, an analyst or a product owner, and they'll make a decision from it", you need an artefact for someone who can't read Kotlin. That's a different problem, and it's the one every tool below is trying to solve.

The field, briefly

Cucumber and JBehave. Scenarios in Gherkin, step definitions matched to the text. The feature file is readable by anyone and can exist before the code, which is real value when scenarios are genuinely written together up front. The cost is three things to maintain instead of one, bound by text your IDE can't refactor. Rename a method and the .feature file doesn't follow. And the report shows you the Gherkin, not what ran.

Kotest BehaviorSpec. Given-When-Then with no extra dependency, no separate files, and refactoring works because it's all just code. For tests developers read it's the right answer and I use it myself. The output is a test result, which is exactly no use to a product owner.

Spek. Kotlin-native, Gherkin-shaped DSL. Last release was 2.0.19 in August 2022. Fine if you're on it.

JGiven. Readable text derived from method names, so refactoring keeps them in sync. That instinct is correct, and it's the same one behind Yatspec and Kensa. The cost is stage classes: every scenario needs Given, When and Then defined as separate types, and a method name can't carry a runtime value.

Serenity BDD. The closest to what Kensa is for, and the one I haven't used in anger. It generates a substantial report aimed at the same reader, with results by requirement and screenshots through the run. The cost is how much framework you take on, most of it WebDriver and Screenplay, and a report that's static once written.

Concordion. Where I started. The specification is a document written for the reader, which is a genuinely different artefact and the thing the rest of the field misses.

Every one of those produces something a person can read. None of them produces something a person can ask a question of, and that gap is most of why I kept going.

"But our analysts write the specifications"

This is the argument I hear most often for Cucumber, and for years I thought it settled the matter.

The assumption underneath it is that if non-developers write Given-When-Then, they have to write it somewhere the test tooling can read. That isn't true. Think about where those sentences actually get written on your project. It's the ticket. Someone writes acceptance criteria in Jira as Given/When/Then, because that's where the work is described and that's the tool the business already lives in. Nobody opens the repository to write a .feature file. If they do, it's a developer typing up what the ticket already said.

So the specification exists, and it's already somewhere shared and readable. What Gherkin adds is a second copy of it in your source tree, the step definitions to bind it, and the job of keeping all three in agreement.

Close the loop instead. The ticket's Given/When/Then gets implemented as the test, in the same words, carrying the reference:

@Issue("PROJ-42")
@Test
fun `refund is processed within 24 hours`() {
    given(anOrderPaidBy(card))

    whenever(aRefundIsRequested())

    then(theRefund(), isProcessedWithin(24.hours))
}

Set issueTrackerUrl once and the report badge links back to the ticket. The ticket links forward to the report. An analyst opens what they wrote, clicks through, and sees what the system actually did.

Outside in

Kensa is built for acceptance tests. Not unit tests with better names. The system under test is a deployed application or a set of services, and the test sits outside it. You push a message in, you wait, and you verify what came back and what the system did on the way.

That means no special build. No test profile exposing a generated key so an assertion can find it, no reaching into a repository to check a row landed. If the only way to observe something is from inside the application, the test doesn't get to see it either, which is also the position you're in when it misbehaves in production.

Testing that way makes the report harder to build and far more useful. The evidence worth showing isn't the test's own variables, it's the traffic: the request that went in, the messages that crossed between services, their payloads, headers and queue names, and the response that came back.

Nothing in that diagram was drawn by hand or declared anywhere. It's the six interactions the test observed crossing between the customer, the service under test and its two suppliers.

Outside in includes a browser, since a click is as external as a queue message. Kensa puts Playwright or Selenium behind a driver-agnostic user object, so tests read as theUser.submitsTheApplication() rather than as selectors, and labelled screenshots collect into their own tab. And if the thing outside your test is a Spring service, the Spring Boot starter takes the wiring: one annotation for the boilerplate, kensa.* properties from application.yml, and automatic capture of MockMvc, WebTestClient, RestTemplate and WebClient traffic.

What a test looks like

class CheckoutTest : KensaTest, WithKotest {

    @RenderedValue
    private val itemCount = 3

    private val checkout = CheckoutService()
    private lateinit var basket: Basket
    private lateinit var order: Order

    @Test
    fun `customer checks out a full basket`() {
        given(aBasketOf(itemCount))

        whenever(theCustomerChecksOut())

        then(theOrder()) { status shouldBe Created }
    }

    private fun aBasketOf(count: Int) = Action<GivensContext> {
        basket = Basket.of(count)
    }

    private fun theCustomerChecksOut() = Action<ActionContext> {
        order = checkout.submit(basket)
    }

    private fun theOrder() = StateCollector { order }
}

That's the whole file. Kensa parses it at runtime and renders those three lines as sentences with the real values substituted in, so the report shows what the fixtures actually produced on this run rather than the names of the variables that held them.

That example is deliberately minimal. Constructing CheckoutService() in the test keeps it to one readable file, and it is not how you would run this for real. In a working acceptance suite the service is deployed, its collaborators are stubs running as singletons in the environment, and the test reaches all of them over the wire.

Because the report is generated rather than written, you can interrogate it. Open a captured message and read the payload:

Collapse the assertions you don't care about. Follow a rendered value back to the fixture that produced it. Filter to the tests touching the thing you're chasing. There's one artefact, it can't drift from the code, and refactoring just works.

Zoom out and the same run reads as a whole: what passed, where the time went, and which services did the talking.

The participants panel is the one no other tool has an equivalent for. Five services, 260 messages captured, and the shape of who talks to whom, none of it declared anywhere. It is just the traffic the tests observed, counted.

Every screenshot here is from the Clearwave example report, which is published and live. Go and click around it rather than taking my word for any of this.

There's more machinery here than in a test library, and it's opinionated about structure. It also doesn't have Cucumber's twenty years of Stack Overflow answers.

The compiler plugin sounds like more of that than it is. It's Kotlin only, Java capture goes through the runtime instead, the Gradle plugin applies it for you, and you only need it for the richer capture: @RenderedValue substitution and expandable sentences, parameterised ones included.

So which one

Only developers read it. Kotest BehaviorSpec or plain JUnit. Don't add a framework.

You're testing a deployed system from outside it. Kensa. Services exchanging messages, no test hooks in the application, the report assembled from the traffic.

Non-developers write the scenarios. Kensa, and this is the case people get wrong most often. Implement the ticket's Given/When/Then as the test, link the two with @Issue, skip the feature file. The only version that genuinely needs Gherkin is one where non-developers execute the features themselves, which is rarer than the marketing suggests.

You're already deep in Cucumber and want a better report. Serenity is the shortest path from where you're standing.

You want a hand-authored document. Concordion, if static is genuinely what you want.

The thing I'd push back on hardest is the assumption that BDD means Gherkin. It doesn't, and it never did. Gherkin is one way of getting a readable specification, and a good one if a non-developer is holding the pen. If nobody outside your team ever writes a .feature file, and on most teams I've seen nobody does, you're paying the whole cost of the format for none of its benefit.

Write the test once. Make the report readable. That's the whole idea.

Kensa is open source. The Kotlin quickstart takes about five minutes.

BDD Without Gherkin

Paul Brooks — Sat, 12 Sep 2026 09:23:52 +0000

I've been writing acceptance tests in Given-When-Then since 2009 and I've never written a feature file by choice. So when someone asks whether you can do BDD without Gherkin, my answer is that I've never done it any other way.

Cucumber has been the default for long enough that the two have merged in people's heads. They shouldn't have. BDD is a way of specifying behaviour. Gherkin is a file format one family of tools uses to do it.

What Gherkin is for

It does one job. A non-developer can write a scenario in plain text and run it without touching code.

If that is what happens on your project, keep Cucumber. A tester or an analyst who opens the repository, writes .feature files and runs them is getting exactly what the format was built for.

I've never seen it. What I've seen, on every team, is that the scenario gets written in the ticket. Someone puts acceptance criteria in Jira as Given/When/Then because that's where the work is described and that's the tool they already use. Then a developer types the same words into a feature file and writes step definitions to bind them. The "analysts write the specs" argument turns out to describe a copy step.

What it costs

Three things to keep in agreement instead of one: the feature file, the step definitions and the code. The IDE can refactor two of them. The third is text, and it's the one people read.

Binding by regular expression. Rename a method and the .feature file doesn't follow. Reword a step and the match silently changes.

Glue. Step definitions are where the logic actually lives, and they're neither specification nor test. They accumulate.

And the report shows you the Gherkin, coloured green or red. Not what the system did. For an acceptance test, what the system did is the whole point: the request that went in, the messages between services, the response that came back. The feature file can't carry any of that.

Why it looked like a good idea

Cucumber arrived around 2008. Refactoring support in IDEs was patchy and parsing test source at runtime wasn't practical, so a plain-text file bound to code by matchers was a reasonable answer to the constraints of the time. I don't think it was ever a great answer. It was the available one. The constraints are gone and the costs stayed.

What's left when you drop it

Everything that mattered.

You still write one concrete example per test, with a given, a when and a then. You still use the words from the ticket, so "refund is processed within 24 hours" is the acceptance criterion, the test name and the line in the report. The test still runs in CI and fails when the behaviour changes.

The thing you have to work for is the readable output. Gherkin promised living documentation and delivered a feature file with colours. If a product owner is going to read the result, you need something generated from what actually ran, in language they can follow. That's where the choice of tool matters.

How to do it on the JVM

If only developers read the output, don't add anything. Kotest's BehaviorSpec or JUnit with good method names gives you Given-When-Then in code, refactoring works, and the result is a test result. I use it myself for that.

If someone who can't read Kotlin needs the output, there are two approaches.

JGiven derives the sentences from method names. given().a_paid_order() becomes "Given a paid order" and refactoring keeps them in sync. The cost is stage classes for every scenario, and a method name can't carry a runtime value.

Yatspec's approach, and the one Kensa takes, is to read the test method itself. The test is ordinary Kotlin:

@Issue("PROJ-42")
@Test
fun `refund is processed within 24 hours`() {
    given(anOrderPaidBy(card))

    whenever(aRefundIsRequested())

    then(theRefund(), isProcessedWithin(24.hours))
}

Kensa parses that at runtime and renders the three lines as sentences with this run's values in them. @Issue links the report back to the ticket, so the analyst who wrote the Given/When/Then in Jira can open it and see what the system did. One artefact. It can't drift from the code because it is the code.

Because the report is generated, it can also carry what the feature file couldn't: the messages the test saw between services, their payloads, and a sequence diagram drawn from that traffic. The Clearwave example report is live if you want to see one.

So

Gherkin is one way to write examples down, and a good one if someone outside the team is holding the pen. If nobody is, you're paying for the format and getting nothing from it. Keep the Given-When-Then. Use the words from the ticket. Generate the report from the test that ran.

Kensa is open source. The Kotlin quickstart takes about five minutes. BDD in Kotlin: the options, and how to choose covers the wider field.