Quickstart — Kotlin & JUnit 5

This guide walks through setting up Kensa in a Kotlin project with JUnit 5 and writing your first test.

1. Add Dependencies

build.gradle.kts

dependencies {
    testImplementation("dev.kensa:kensa-junit:<version>")

    // Pick one assertions bridge (or use multiple)
    testImplementation("dev.kensa:kensa-kotest:<version>")      // Kotest matchers
    testImplementation("dev.kensa:kensa-assertj:<version>")     // AssertJ
    testImplementation("dev.kensa:kensa-hamkrest:<version>")    // HamKrest
}

Find the latest version on GitHub releases.

Kensa registers itself automatically via the JUnit Platform ServiceLoader — no @ExtendWith needed.

2. Write a Test

Implement KensaTest and mix in an assertions bridge. Test methods follow the Given–When–Then structure using the given(), whenever(), and then() DSL.

import dev.kensa.Action
import dev.kensa.ActionContext
import dev.kensa.GivensContext
import dev.kensa.RenderedValue
import dev.kensa.StateCollector
import dev.kensa.junit.KensaTest
import dev.kensa.kotest.WithKotest
import io.kotest.matchers.shouldBe
import org.junit.jupiter.api.Test

class LoanDecisionTest : KensaTest, WithKotest {

    @RenderedValue
    private val applicantName = "Alice"

    @RenderedValue
    private val requestedAmount = 10_000

    private val service = LoanService()
    private lateinit var result: LoanResult

    @Test
    fun canApproveLoanForApplicantWithGoodCredit() {
        given(anApplicantWithGoodCredit())
        whenever(theLoanServiceProcessesTheApplication())
        then(theLoanResult()) { status shouldBe LoanStatus.Approved }
    }

    @Test
    fun canDeclineLoanForApplicantWithPoorCredit() {
        given(anApplicantWithPoorCredit())
        whenever(theLoanServiceProcessesTheApplication())
        then(theLoanResult()) { status shouldBe LoanStatus.Declined }
    }

    // --- Givens ---

    private fun anApplicantWithGoodCredit() = Action<GivensContext> {
        it.fixtures.add(Applicant(applicantName, creditScore = 750, amount = requestedAmount))
    }

    private fun anApplicantWithPoorCredit() = Action<GivensContext> {
        it.fixtures.add(Applicant(applicantName, creditScore = 300, amount = requestedAmount))
    }

    // --- Action ---

    private fun theLoanServiceProcessesTheApplication() = Action<ActionContext> { ctx ->
        val applicant = ctx.fixtures.get<Applicant>()
        result = service.process(applicant)
    }

    // --- State ---

    private fun theLoanResult() = StateCollector { result }
}

What's happening here

Element	Purpose
KensaTest	Provides the Given–When–Then DSL; registers the JUnit extension
WithKotest	Adds then() / and() overloads that accept Kotest matchers
@RenderedValue	Field value is captured and shown in the HTML report
Action<GivensContext>	Lambda that runs during given() — sets up fixtures
Action<ActionContext>	Lambda that runs during whenever() — exercises the system
StateCollector<T>	Lambda that returns a value for then() to assert against

3. Chain Multiple Steps

Use and() to chain additional setup or assertions:

@Test
fun canApproveLoanWithUnderwritingApproval() {
    given(anApplicantWithGoodCredit())
    and(anApprovalFromUnderwriting())

    whenever(theLoanServiceProcessesTheApplication())

    then(theLoanResult()) { status shouldBe LoanStatus.Approved }
    and(theLoanReference()) { shouldStartWith("LN-") }
}

4. Record Interactions (Sequence Diagrams)

Capture calls between components in your whenever() action using interactions.capture(). Kensa renders these as a sequence diagram in the HTML report.

private fun theLoanServiceProcessesTheApplication() = Action<ActionContext> { ctx ->
    val applicant = ctx.fixtures.get<Applicant>()

    ctx.interactions.capture(
        from(Client).to(LoanService).with("process(${applicant.name})", "Loan Request")
    )

    result = service.process(applicant)

    ctx.interactions.capture(
        from(LoanService).to(Client).with(result, "Loan Result")
    )
}

5. Run & View the Report

Run your tests normally with Gradle:

./gradlew test

By default, reports are written to a kensa-output directory in the system temp folder. Configure a fixed location in your test setup:

Kensa.konfigure {
    outputDir = Path("build/kensa")
}

Then open index.html in a browser, or use the Kensa CLI to serve them:

kensa --dir build/kensa

---

Other Frameworks

Kensa also supports Kotest and TestNG. The Given-When-Then DSL is identical — only the dependency and setup differs. See the Java Quickstart for Java-specific setup, or browse the example projects on GitHub.