bonsai

Documentation

MongoDB emulation, without Docker.

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. It also includes a seeding, cleanup, and assertion harness modelled on the maintainer's spring-kafka-test-utils.

Quick start API reference
Current
3.4.0
Java
17+
Spring Boot
4.1+
Server API
7.x / 8.x
pom.xml
<dependency>
    <groupId>io.typecheck</groupId>
    <artifactId>bonsai-spring-boot</artifactId>
    <version>3.4.0</version>
    <scope>test</scope>
</dependency>

For AI coding agents

An agent skill that writes these tests for you.

Drop the bonsai skill into Claude Code, Cursor, Copilot, or any agent that reads skills, and it knows the whole harness: the annotations, seeding, the assertion vocabulary, and how to migrate a suite off Testcontainers or flapdoodle, with no docs pasted into a prompt.

Get the skill

Start with one annotation.

Annotate the test class. Your real repositories, converters, and @Transactional boundaries run against the emulation. Anything it does not emulate fails fast by name rather than answering differently.

  • No Docker, no downloaded binaries, no mongod process anywhere in the build
  • A driver-interface shim over Nitrite, so your real repositories and converters run unchanged
  • Full MongoDB transaction API, including every abort path and the withTransaction retry contract
  • Databases dropped between test methods: no bleed, no ordering surprises
  • Fixture seeding, await helpers, and fluent assertions in one harness
  • Behaviour checked against real MongoDB by a differential test lane, not asserted
  • Anything outside the emulated surface fails fast by name, never with a silently different answer
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));
    }
}

Common tasks

The docs are organized by the work library users usually need to do.

Browse all docs