bonsai

Introduction

An embedded MongoDB emulation, in your test JVM.

Bonsai is an embedded MongoDB emulation for Spring Boot and JVM integration tests. It is a driver-level shim over Nitrite that runs your real Spring Data code in-process, with no Docker, no downloaded binaries, and no mongod anywhere in the build.

Overview

Testing against MongoDB usually means one of three trades. Testcontainers gives you a real server and charges you a Docker daemon, an image pull, and container start-up per suite. Flapdoodle skips Docker but downloads a mongod binary and spawns a process. Mocking the repository layer costs nothing and proves nothing. The queries that break in production are exactly the ones a mock never runs.

This library takes the fourth option: emulate MongoDB by implementing the Java driver's own interfaces, backed by the embedded document store Nitrite, and swap the MongoClient bean underneath your application. Nothing about your test changes. Your real repositories, your real MappingMongoConverter, your real @Transactional boundaries all run against an emulation that starts in milliseconds and lives entirely inside the test JVM.

OrderRepositoryIT.java
@SpringBootTest
@EnableMongoEmulator
class OrderRepositoryIT {

    @Autowired
    OrderRepository orderRepository;   // the app's real repository

    @Test
    void savesAndFindsByStatus() {
        orderRepository.save(new Order("ord-1", "CONFIRMED", 4999));

        assertThatCollection("orders")
            .hasDocumentCount(1)
            .containsDocumentSatisfying(d -> d
                .hasField("status", "CONFIRMED")
                .hasJsonPath("$.amount", 4999));
    }
}

How it works

The annotation registers a context initializer that replaces the application's MongoClient and MongoDatabaseFactory beans with shim implementations, neutralises the connection properties so nothing can accidentally dial a real server, and drops every touched database between test methods.

Underneath the shim, four engines do the work a server would: a BSON codec that round-trips documents type-exactly, a filter translator that turns query documents into index-backed reads where it can and predicate scans where it must, an update-operator engine, and an aggregation engine. Transactions are handled by a staging overlay with per-collection commit locking and first-committer-wins validation. The embedded store's own session support is not used at all, because its compensation-based model cannot give the rollback guarantees this library promises.

Anything outside the emulated surface fails fast with MongoTestUnsupportedException, naming the feature and the compatibility matrix row that documents the boundary. A wrong answer that looks right is the one failure mode this library will not ship.

Why you can trust it

The promise is not “an in-memory database that feels like Mongo”. It is narrower and checkable: within the emulated surface, your tests behave the same as they would against real MongoDB, that claim is checked rather than asserted, and everything outside that surface refuses to answer at all. See Supported operations for what the surface is.

A differential lane runs the same scenario corpus twice: once against the shim and once against a real mongod. It captures both observations in canonical Extended JSON, and diffs them. Real MongoDB is the reference: when the two disagree, the shim is wrong by definition. The lane found four genuine divergences during development, all of which became fixes and permanent regression scenarios.

Documentation

Requirements

  • Java 17+
  • Spring Boot 4.1+
  • MongoDB driver 5.5.x
  • JUnit Jupiter 5.13+ / 6.x

The Spring Boot baseline applies to the bonsai-spring-boot module only. The generic harness needs JUnit and the driver, nothing more. The emulation targets the MongoDB 7.x and 8.x server API.

Credit

This library is modelled after spring-kafka-test-utils by the same maintainer: the shared-infrastructure lifecycle, the seed/act/await/assert rhythm, the fluent assertion style, and this documentation site's design all come from there. The MongoDB emulation underneath is entirely new.