stove
Stove
End-to-end tests in Kotlin for JVM and non-JVM applications.
Run your application with its dependencies, test complete use cases, and see what happened when they fail.
Get started · Setup wizard · Documentation · Recipes · Try the dashboard · Release notes
An end-to-end test suite can become a small framework of its own. There is code to boot the application, connect its dependencies, prepare data, wait for background work, and explain what went wrong. Start another service or switch application frameworks, and much of that work starts over.
Stove exists to make that work reusable. It brings application startup, dependency configuration, assertions, and diagnostics into one test lifecycle. You describe the environment your application needs, then write tests around its use cases.
That same approach works across Spring Boot, Ktor, Micronaut, and Quarkus, and extends to applications in other languages. Your test suite can keep a familiar shape as the stack around it changes.
What a Stove test looks like
Call your application, then check its database and messages in the same test:
stove {
http {
postAndExpectBodilessResponse("/orders", body = CreateOrderRequest(userId, productId).some()) {
it.status shouldBe 201
}
}
postgresql {
shouldQuery<Order>("SELECT status FROM orders WHERE user_id = '$userId'", mapper = { row ->
Order(row.string("status"))
}) {
it.single().status shouldBe "CONFIRMED"
}
}
kafka {
shouldBePublished<OrderCreatedEvent> {
actual.userId == userId
}
}
}
The HTTP, PostgreSQL, and Kafka blocks give the test direct access to each part of the flow. Add the systems your application uses, including mocks for external services you want to control.
For JVM applications running in the test process, you can set a breakpoint in your application code and step through the request from the test. You can also access application beans when a test needs them. Applications running as a separate process, in a container, or in an existing environment use the same style of assertions.
Get started
Stove is distributed as a set of libraries on Maven Central, consumed with the com.trendyol:stove-bom BOM.
Tests are written in Kotlin, even when the application is Java, Scala, Go, Python, or another language. Stove supports JDK 17+ as a consumer; the repository's own build uses newer JDKs. You'll need Docker for dependencies started through Testcontainers; provided instances let you use infrastructure you already have.
Add Stove to your application
Replace x.y.z with the latest release from the Releases page or the badge above.
// build.gradle.kts
val stoveVersion = "x.y.z"
dependencies {
testImplementation(platform("com.trendyol:stove-bom:$stoveVersion"))
testImplementation("com.trendyol:stove")
testImplementation("com.trendyol:stove-spring") // or -ktor / -micronaut / -quarkus
testImplementation("com.trendyol:stove-extensions-kotest") // or -extensions-junit
testImplementation("com.trendyol:stove-http")
testImplementation("com.trendyol:stove-postgres")
testImplementation("com.trendyol:stove-kafka")
}
Keep the BOM, every com.trendyol:stove-*, and stove-server (if you use the dashboard) on the same version. The Getting Started guide walks through a complete setup with Kotest or JUnit. Choose how you want to run your app:
| Application | Setup guide |
|---|---|
| In the test JVM | Spring Boot, Ktor, Micronaut, Quarkus |
| A separate process | Polyglot testing |
| A container | Container runner |
| Already running | Provided application |
Run the Spring showcase
Try a complete setup with the Spring showcase. With JDK 25 and Docker running:
git clone https://github.com/Trendyol/stove.git
cd stove/recipes/jvm
./gradlew :kotlin-recipes:spring-showcase:e2eTest
The first run downloads dependencies and container images. See the Stove configuration for the complete test environment.
When a test fails
Stove keeps the evidence from a failed test together in the console report: operations, inputs, outputs, and system snapshots. With tracing enabled, you can follow the request into your application:
EXECUTION TRACE (Call Chain)
✓ POST /orders
✓ OrderController.create
✓ OrderService.placeOrder
✓ SELECT inventory
✗ POST /payments/charge — PaymentTimeoutException
✓ orders.created publish
Here, the payment call is where the investigation starts. From there, inspect the mock response, the database state, or the surrounding trace. When a Test Fails walks through that process.
Dashboard and Stove Server
Try the interactive demo → (no install, everything stays in your browser)
Browse sample applications and historical runs, inspect a failing checkout, follow its trace, compare expected and actual values, and open Kafka, OIDC, and database snapshots. The demo uses the same dashboard as Stove Server. You can replay a test, try the SQL workbench, change retention, and reset the sample data.
For your own tests, Stove Server collects this evidence and keeps it available after the run. It is a separate, optional binary — not part of the com.trendyol:stove-* libraries — distributed via Homebrew and Docker, and only needed if you want the dashboard, tracing storage, and MCP tools. Use it locally while developing or share a server with your team and CI jobs; see the Dashboard guide for installation.
Supported systems
Register only what your tests need. Each link covers dependencies, configuration, and assertions.
| Area | Modules |
|---|---|
| Databases | PostgreSQL, MySQL, MSSQL, MongoDB, Couchbase, Cassandra |
| Search and cache | Elasticsearch, Redis |
| Messaging | Kafka |
| Clients | HTTP and WebSockets, gRPC |
| Mocks | WireMock, gRPC mock server, OIDC |
| Diagnostics | Reporting, Tracing, Dashboard |
Need something else? Write a custom system to give it the same lifecycle and test DSL.
Working with coding agents
The evidence in the dashboard is also available to coding agents through the server's read-only MCP tools. An agent can inspect a failed run, follow its trace, and look at the recorded system state while helping you investigate.
Run stove skills install in your repository to install the Stove agent skill. It covers setup, assertions, and failure investigation. See the MCP guide for configuration and usage.
Common questions
Does Stove replace Testcontainers?
No. Stove uses Testcontainers to manage dependency containers and adds application startup, configuration, assertions, and diagnostics around them.
Can I connect to infrastructure I already have?
Yes. The databases, Redis, Elasticsearch, and Kafka support provided instances through .provided(...) factories. Swap SystemOptions(...) for SystemOptions.provided(...) and supply connection details; Stove connects to existing infrastructure (a shared CI database, dev cluster, or staging broker) instead of starting a container. The DSL and assertions stay the same, but Stove does not create, isolate, pause, or destroy the dependency — you own its lifecycle.
Can I reuse containers locally?
Yes: Stove { keepDependenciesRunning() } keeps reusable dependency containers running between suites. This reduces container startup work; the application and tests still need to start.
When does cleanup run?
A system's cleanup callback runs when Stove stops at suite teardown. It does not reset state between individual tests. Migrations run during system startup.
Can tests run in parallel?
Yes, when their state and assertions are isolated. Use distinct IDs and filter queries and event assertions by those IDs. Shared tables, topics, mock stubs, and application state can still cause interference; use separate schemas, resources, or suites where needed.
Community
Used at Trendyol. Using Stove elsewhere? Open a PR to add your company.
Issues and contributions are welcome. See CONTRIBUTING.md for local checks and CI, or explore the example recipes in this repository for more working setups.
Licensed under Apache 2.0. APIs are evolving; check the release notes when upgrading.
