Reference

Core API

bonsai-core holds the engine and the driver shim, and is almost entirely internal. These are the types that legitimately reach user code.

MongoTestUnsupportedException

Thrown whenever the shim is asked to perform an operation it deliberately does not emulate. It extends the driver's own MongoException, so code that already handles driver failures sees it as one.

Java

package io.typecheck.bonsai.core;

public class MongoTestUnsupportedException extends MongoException {

    public MongoTestUnsupportedException(String feature, String matrixKey);

    /** Human-readable name of the unsupported feature, e.g. "aggregation stage $facet". */
    public String feature();

    /** Stable key of the compatibility-matrix row documenting this boundary. */
    public String matrixKey();
}

package io.typecheck.bonsai.core;

public class MongoTestUnsupportedException extends MongoException {

    public MongoTestUnsupportedException(String feature, String matrixKey);

    /** Human-readable name of the unsupported feature, e.g. "aggregation stage $facet". */
    public String feature();

    /** Stable key of the compatibility-matrix row documenting this boundary. */
    public String matrixKey();
}

The message is built to be actionable on its own:

Unsupported by bonsai: aggregation stage $facet (see compatibility matrix: aggregation.facet)

The matrix key is stable and machine-readable, so a test can assert on the boundary rather than on message text, and the compatibility matrix documents every key the shim can raise, family by family.

The seed SPI

Implement SeedPlaceholders to supply bindings for ${...} placeholders from a class, and name it in @MongoSeed(placeholders = ...). Under Spring, the provider is resolved as a bean when one exists, so it can be dependency-injected.

Java

package io.typecheck.bonsai.core.seed;

@FunctionalInterface
public interface SeedPlaceholders {
    Map<String, Object> placeholders();
}

@FunctionalInterface
public interface PlaceholderResolver {
    Optional<Object> resolve(String name);
}

public final class PlaceholderEngine {
    public PlaceholderEngine(List<PlaceholderResolver> resolvers);
    public static PlaceholderEngine of(PlaceholderResolver... resolvers);
    public Prepared prepare(FixtureSource source);
    public Set<String> seenNames();
}

package io.typecheck.bonsai.core.seed;

@FunctionalInterface
public interface SeedPlaceholders {
    Map<String, Object> placeholders();
}

@FunctionalInterface
public interface PlaceholderResolver {
    Optional<Object> resolve(String name);
}

public final class PlaceholderEngine {
    public PlaceholderEngine(List<PlaceholderResolver> resolvers);
    public static PlaceholderEngine of(PlaceholderResolver... resolvers);
    public Prepared prepare(FixtureSource source);
    public Set<String> seenNames();
}

PlaceholderResolver is the lower-level interface the engine composes: the supplied resolvers are consulted in order and the first non-empty Optional wins. See Seeding & placeholders for the complete resolution order.

Fixture exceptions

All fixture failures descend from FixtureException, so one catch covers them. UnresolvedPlaceholdersException is the one worth handling specifically: it carries every unresolved placeholder, each with its source and JSON path, rather than failing on the first.

Java

package io.typecheck.bonsai.core.seed;

public class FixtureException extends RuntimeException { }
public class FixtureParseException extends FixtureException { }
public class PlaceholderException extends FixtureException { }

public class UnresolvedPlaceholdersException extends PlaceholderException {
    public String source();
    public List<Unresolved> unresolved();

    public record Unresolved(String path, String name) { }
}

package io.typecheck.bonsai.core.seed;

public class FixtureException extends RuntimeException { }
public class FixtureParseException extends FixtureException { }
public class PlaceholderException extends FixtureException { }

public class UnresolvedPlaceholdersException extends PlaceholderException {
    public String source();
    public List<Unresolved> unresolved();

    public record Unresolved(String path, String name) { }
}

Seed value types

Java

package io.typecheck.bonsai.core.seed;

public record SeedUnit(String database, String collection, List<Document> documents) {
    public String namespace();
}

public record FixtureSource(String name, String content) { }

package io.typecheck.bonsai.core.seed;

public record SeedUnit(String database, String collection, List<Document> documents) {
    public String namespace();
}

public record FixtureSource(String name, String content) { }

EmbeddedMongoServer

The JVM-wide embedded store: one instance serving every logical database every harness context asks for. The harness drives it; you would only touch it when building test infrastructure of your own.

Java

package io.typecheck.bonsai.core.shim;

public final class EmbeddedMongoServer {

    /** System property enabling the optional file-backed store debug mode. */
    public static final String DURABILITY_DIRECTORY_PROPERTY = "bonsai.durability.directory";

    public static EmbeddedMongoServer instance();

    public MongoClient client(String contextId, CoreServices services);
    public void dropDatabases(String contextId);
    public Set<String> touchedDatabases(String contextId);
    public boolean isClosed();
    public void close();
}

package io.typecheck.bonsai.core.shim;

public final class EmbeddedMongoServer {

    /** System property enabling the optional file-backed store debug mode. */
    public static final String DURABILITY_DIRECTORY_PROPERTY = "bonsai.durability.directory";

    public static EmbeddedMongoServer instance();

    public MongoClient client(String contextId, CoreServices services);
    public void dropDatabases(String contextId);
    public Set<String> touchedDatabases(String contextId);
    public boolean isClosed();
    public void close();
}

DURABILITY_DIRECTORY_PROPERTY is the system property behind the file-backed debug mode, the generic-harness equivalent of bonsai.durability.directory.