Start

Installation

One test-scoped dependency. Pick the module that matches your application, and the rest arrives transitively.

Availability

All artefacts publish under the io.typecheck group in test scope, on a single version train: the four modules and the BOM release together with the same version, even when a module has no changes. Mixed-version combinations are never supported and never tested.

Which module

Your project	Depend on	Notes
Spring Boot application	`bonsai-spring-boot`	Includes bonsai-junit and bonsai-core transitively, including the shared assertions and date matchers.
Plain Java or Kotlin, no Spring	`bonsai-junit`	The JUnit harness, seeding, readers, and the whole assertions package, including Java-time equality and date matchers.
Multi-module build	`bonsai-bom`	Import the BOM once, then declare modules without versions.
File-backed durability	`bonsai-durability`	Opt-in, alongside a harness. Only needed for `bonsai.durability.directory`.

There is one more module, bonsai-core, which holds the engine and the driver shim. You never depend on it directly. It arrives underneath whichever harness you chose.

Spring Boot applications

pom.xml

<dependency>
    <groupId>io.typecheck</groupId>
    <artifactId>bonsai-spring-boot</artifactId>
    <version>3.5.2</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>io.typecheck</groupId>
    <artifactId>bonsai-spring-boot</artifactId>
    <version>3.5.2</version>
    <scope>test</scope>
</dependency>

Spring test properties

After adding the dependency, choose a test database in a test profile. Create one of the files below under src/test/resources/, then activate it with @ActiveProfiles("test"). The spring.mongodb.* namespace is Spring Boot 4's MongoDB configuration; bonsai.* controls the test harness.

src/test/resources/application-test.yml

spring:
  mongodb:
    database: orders

bonsai:
  collections: orders,outbox,billing.invoices
  cleanup: drop-databases

spring:
  mongodb:
    database: orders

bonsai:
  collections: orders,outbox,billing.invoices
  cleanup: drop-databases

spring.mongodb.database=orders sets the database used by Spring Data and unqualified Bonsai collection names. bonsai.collections optionally pre-creates collections; billing.invoices uses the separate billing database. bonsai.cleanup=drop-databases removes test data after each method and recreates declared collections.

All of these settings are optional. Bonsai uses the existing spring.mongodb.database, then a database in spring.mongodb.uri, and falls back to test. Collections are created on demand and touched databases are dropped between methods. An explicit @EnableMongoEmulator(defaultDatabase = "...") overrides the configured database. The old spring.data.mongodb.* keys do not configure the Boot 4 harness.

OrderRepositoryIT.java

import io.typecheck.bonsai.spring.EnableMongoEmulator;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;

@SpringBootTest
@ActiveProfiles("test")
@EnableMongoEmulator
class OrderRepositoryIT {
    // Test your application repositories as usual.
}

import io.typecheck.bonsai.spring.EnableMongoEmulator;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;

@SpringBootTest
@ActiveProfiles("test")
@EnableMongoEmulator
class OrderRepositoryIT {
    // Test your application repositories as usual.
}

Plain JUnit applications

If your tests drive the MongoDB driver directly rather than through Spring Data, the generic harness is all you need. It has no Spring on its classpath at all.

pom.xml

<dependency>
    <groupId>io.typecheck</groupId>
    <artifactId>bonsai-junit</artifactId>
    <version>3.5.2</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>io.typecheck</groupId>
    <artifactId>bonsai-junit</artifactId>
    <version>3.5.2</version>
    <scope>test</scope>
</dependency>

Multi-module builds

pom.xml (parent)

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.typecheck</groupId>
            <artifactId>bonsai-bom</artifactId>
            <version>3.5.2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.typecheck</groupId>
            <artifactId>bonsai-bom</artifactId>
            <version>3.5.2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Optional durability

The harness is in-memory by default, and that is what almost every suite wants. If you set bonsai.durability.directory to keep the backing store on disk between runs, the embedded store needs a persistence adapter that the default classpath deliberately does not carry. Add bonsai-durability at test scope and it arrives transitively, at the version Bonsai was built against. There are no hand-picked org.dizitart coordinates in your build.

pom.xml

<dependency>
    <groupId>io.typecheck</groupId>
    <artifactId>bonsai-durability</artifactId>
    <version>3.5.2</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>io.typecheck</groupId>
    <artifactId>bonsai-durability</artifactId>
    <version>3.5.2</version>
    <scope>test</scope>
</dependency>

It carries no code of its own: its only job is to deliver nitrite-mvstore-adapter version-aligned with the store the shim embeds. Without it, enabling durability fails at runtime.

Requirements

Java 17 or later. The build targets release 17; the CI matrix runs 17 and 21.
Spring Boot 4.1 or later, for the Spring module only. Your own BOM wins. The library imports the Boot BOM inside its own module, not into yours.
MongoDB Java driver 5.5.x. The shim implements the driver interfaces, so the driver version is part of the contract rather than a floating transitive.
JUnit Jupiter 5.13+ or 6.x. Both harnesses are Jupiter extensions; the reactor builds on 6.1.3. The floor is 5.13 because the class-scoped teardown uses the AutoCloseable store-close introduced there.

The emulated server API targets MongoDB 7.x and 8.x. That is the behaviour the differential lane compares against.

What arrives on the test classpath

The engine brings an embedded document store, the MongoDB sync driver, and SLF4J. The harness adds AssertJ, Hamcrest, and JsonPath, because the assertion API is built on them. Nothing brings Docker, a container runtime, or a downloaded server binary. That is the point of the library, and it is enforced by the build rather than left to discipline.

Migrating from mongo-test-utils 1.x

Bonsai is the same library under a new name and a new owner group. The 2.0.0 rename touched everything a consumer touches, and nothing else: the engine, the emulated surface, the cleanup model, the seeding rules and the assertion vocabulary are unchanged from 1.3.0. A migration is a find-and-replace, and the table below is the whole of it.

Do it in one commit. The old and new packages cannot be mixed in a single test class, because the annotation and its extension must come from the same generation.

1.x (mongo-test-utils)	2.x+ (Bonsai)
io.gitlab.guisseppe (groupId)	io.typecheck
spring-mongo-test-utils	bonsai-spring-boot
mongo-test-utils	bonsai-junit
mongo-test-utils-core	bonsai-core
mongo-test-utils-bom	bonsai-bom
org.dizitart:nitrite-mvstore-adapter	io.typecheck:bonsai-durability
io.gitlab.guisseppe.mongo.test	io.typecheck.bonsai
io.gitlab.guisseppe.mongo.test.assertions	io.typecheck.bonsai.assertions
io.gitlab.guisseppe.mongo.test.junit	io.typecheck.bonsai.junit
io.gitlab.guisseppe.mongo.test.core.*	io.typecheck.bonsai.core.*
io.gitlab.guisseppe.spring.mongo.test	io.typecheck.bonsai.spring
@MongoTestServer	@EnableMongoEmulator
spring.mongodb.test.*	bonsai.*
mongo.test.durability.directory	bonsai.durability.directory

The annotation kept its two variants. io.typecheck.bonsai.spring.EnableMongoEmulator is the Spring Boot one; io.typecheck.bonsai.junit.EnableMongoEmulator is the plain JUnit 5 one. If you were on spring-mongo-test-utils, you want the .spring import.
@MongoSeed and @MongoSeeds kept their names and moved to io.typecheck.bonsai.junit.
Spring's own connection properties did not change. spring.mongodb.uri and spring.mongodb.database belong to Spring, not to this library; the harness still publishes and neutralises those exact names. Only the library's own spring.mongodb.test.* namespace became bonsai.*.
Durability is now an artefact, not a hand-added dependency. Drop the manual org.dizitart:nitrite-mvstore-adapter entry and depend on io.typecheck:bonsai-durability instead.
1.x is not withdrawn. The old coordinates remain on Maven Central; they simply stop receiving releases.