How it works

The driver surface is wide but shallow: the library implements the subset Spring Data actually calls: find, insert, update, replace, delete, count, distinct, aggregate, index management, drop, sessions and the iterables. Everything else throws MongoTestUnsupportedException, naming the method and the compatibility-matrix row that documents the boundary.

The engines

Five components do the work a server would. They are ordinary Java classes over documents that fit in memory, which is definitionally true in an integration test.

BsonDocumentCodec: documents and _id

Each org.bson.Document is walked recursively into a Nitrite Document. ObjectId, Decimal128, Binary, Date, UUID and Pattern are stored directly; a BSON null becomes a Java null. Mongo's _id never touches Nitrite's own _id. It lives in the reserved field __mid, backed by a unique index, and every query, update and sort that mentions _id is rewritten on the way in and back on the way out. An insert with no _id gets a real ObjectId, written back into the caller's document instance exactly as the driver does. An application document that contains a field literally named __mid is rejected rather than silently mangled.

BsonFilterTranslator: two tiers, and index-backed reads

Query translation is a two-tier strategy. Tier 1 compiles operators with a native equivalent: implicit and explicit $eq, $ne, $gt/$gte/$lt/$lte, $in/$nin, $and/$or/$not/$nor, $exists, $regex, $elemMatch and dotted paths. Tier 2 compiles the rest: $size, $all, $type, $mod, array-position paths, and the BSON type-bracket comparison rules, into predicate lambdas that evaluate MongoDB semantics over the document. Correct, at the price of a scan.

Reads are index-backed without giving that correctness up. The translator has a second compilation that produces a fluent leaf AND the whole predicate form: the leaf only has to be a superset of what MongoDB matches, so the store's planner can elect it for an index scan while the predicate, still the authority on missing/null, array, regex-type and cross-numeric rules, filters whatever the index returned. A conjunct qualifies only when it is top-level, undotted, on a single-field index, and compares against a non-null scalar.

The effect is that an _id point lookup stays flat as a collection grows rather than degrading linearly with a full predicate scan.

UpdateOperatorEngine: update operators

Nitrite can only deep-merge, so MongoDB's update operators run in the shim: match documents through the translated filter, apply the operators to the materialised document in Java, write the whole document back under the per-collection lock. The set covers $set, $unset, $inc, $mul, $min, $max, $rename, $setOnInsert, $currentDate, $push with its modifiers, $addToSet, $pull, $pullAll and $pop, plus upserts built from the filter-derived seed document.

AggregationEngine: pipelines as staged transforms

A pipeline is a sequence of transforms over a cursor, so the engine runs it as Java stages over materialised documents: $match (which reuses the filter translator, so a pre-$group match still hits indexes), $project, $sort, $skip, $limit, $count, $unwind, $group, $addFields, $replaceRoot, $sortByCount and the equality form of $lookup. Stages outside that set fail fast by name. This is deliberately a test-grade engine: correctness first, over data that fits in memory.

TransactionEngine: overlay, commit lock, sharding

The embedded store's own session support is not used at all. Each active transaction owns a staging overlay per touched namespace. It tracks pending inserts, updates and deletes keyed by _id, plus the revision of every document it read or wrote. Reads through the session see base state plus overlay; reads outside it never see uncommitted state. Commit validates the recorded revisions against current state, snapshots the affected documents, and applies the overlay; a version conflict aborts with a TransientTransactionError label, so withTransaction retry loops genuinely execute and are genuinely testable.

Because uncommitted writes never touch the store, abortTransaction() is a pure in-memory discard: there is no compensation logic to get wrong and no window in which another reader observes half-applied state. Mutual exclusion is per-collection rather than process-wide wherever the store provides its own locking. Commits on disjoint collection sets proceed concurrently, overlapping sets still serialize.

The full session API, every abort path, and where the emulation stops are covered on the Transactions page.

Why Nitrite

Underneath the engines is Nitrite (org.dizitart:nitrite), an embedded NoSQL document store. It was chosen for what it costs, not for how MongoDB-shaped it is:

• Pure Java, in-process. No Docker daemon, no downloaded binary, no spawned mongod, no port to collide with. The store starts inside the test JVM in milliseconds.
• In-memory by default. The in-memory store is built into the core artefact. No storage adapter is needed for the default mode.
• Apache-2.0, and light. Java 11 bytecode, with slf4j, jasypt and commons-codec as its only compile dependencies.
• The right primitives. Collections of documents, fluent filters, compound sort with skip and limit, inclusion projection, unique / non-unique / full-text / compound indexes, per-collection event listeners, thread-safe collections, and a query plan the library can assert index usage against in its own tests.

Nitrite is not MongoDB-compatible

This is the honest part, and it is worth stating plainly: Nitrite has a MongoDB-flavoured API, and that is all. It is not a MongoDB implementation, it does not speak the wire protocol, and several of its behaviours are the opposite of MongoDB's. Every one of those gaps is closed above it, in the shim. This is precisely why the shim exists rather than a thin adapter.

How the fidelity claim is proven

None of the above is worth anything as an assertion. The promise is not “an in-memory database that feels like MongoDB”. It is that your tests behave the same as they would against real MongoDB, and that the claim is checked.

A differential lane runs a backend-agnostic scenario corpus twice: once against the shim and once against a real mongod. Testcontainers runs where a Docker runtime exists, a flapdoodle-launched server as the Docker-less fallback. Both observations are captured in the same canonical Extended JSON form and diffed. Real MongoDB is the reference backend: when the two disagree, the shim is wrong by definition, and the divergence has exactly four permitted resolutions: a shim fix, a fail-fast guard plus a matrix row, a reviewed normalization rule, or a documented surprise about MongoDB itself. “Close enough” is not a verdict.

The corpus covers BSON data types, query operators, update operators, collation, aggregation, indexes, transactions, the Spring surface, error-signature parity and the driver surface, alongside a property-based generative lane. The emulation targets the MongoDB 7.x and 8.x server API, and the two lines also cross-check each other: if they ever disagree, that is flagged independently of the shim.

Separately, the performance lane enforces byte-for-byte integrity under load. Each workload is replayed deterministically against both backends, then every document in every touched collection is read back, serialized with one fixed canonical Extended JSON writer, and compared byte for byte. A widened Int32, a reordered key, a lost Binary subtype or a differently rounded Date fails the run.

Where the guarantee stops is documented as explicitly as the guarantee itself: Supported operations lists what the emulation covers and every boundary that fails fast, and the compatibility matrix names every edge and the key its error carries, with a fourth category, “silently different”, that is empty by policy. If you would rather verify the claim on your own codebase than take either page's word for it, that is what passthrough mode is for.