jongodb
In-memory MongoDB-compatible backend for fast Spring integration tests.
jongodb is designed for the fast path in local development and routine CI:
- use
jongodb as the default test backend for common Spring Data MongoDB paths
- keep Testcontainers or real
mongod as the high-fidelity fallback profile
It targets fast, deterministic Spring Boot test execution without Docker/container bootstrap.
It supports both in-process test bootstrap and standalone TCP launcher mode.
It is not a production MongoDB replacement.
Why This Project Exists
Container-based integration tests are useful for production fidelity, but they are often slower and more environment-sensitive during day-to-day development.
jongodb provides a different tradeoff:
- faster local/CI test feedback
- deterministic in-process behavior
- explicit support boundary for unsupported MongoDB features
Recommended Adoption Model
Use two lanes instead of forcing one tool to satisfy every test:
- default lane:
jongodb for common CRUD, repository/template, and single-process transaction flows
- fallback lane: Testcontainers or real
mongod for unsupported features and deployment-level behavior
This keeps the common suite fast without pretending partial compatibility is full parity.
Value for Spring Boot Test Suites
Typical gains when replacing Testcontainers for supported scenarios:
- lower startup overhead (no image pull/container bootstrap)
- fewer environment-related flakes (Docker daemon/network/port state)
- faster debug loops for service-level integration tests
- simpler test infrastructure in CI and local dev
This is most useful for:
- CRUD-heavy service tests
- repository/template behavior tests
- transaction envelope flows in a single-process test runtime
jongodb vs Testcontainers
| Topic |
jongodb |
MongoDB Testcontainers |
| Startup/runtime overhead |
Low (in-process) |
Higher (container bootstrap + networking) |
| Determinism |
High for supported feature paths |
Good, but depends on container/runtime environment |
| Feature fidelity vs real MongoDB |
Partial by design |
High |
| Infra requirement |
No Docker required |
Docker required |
| Best fit |
Fast development and CI feedback loops |
High-fidelity compatibility checks |
Recommended strategy:
- default profile:
jongodb
- high-fidelity profile: Testcontainers/real
mongod for unsupported or deployment-level behavior
Why This Can Work As A Default Lane
jongodb is optimized around test-suite ergonomics, not full database emulation:
- direct Spring test wiring via annotation, initializer, or
@DynamicPropertySource
- explicit compatibility boundary documented in
docs/COMPATIBILITY.md
- deterministic unsupported-path signaling instead of silent behavioral drift
- standalone launcher mode for tools that expect a
mongodb:// URI
When to Use / Not Use
| Decision |
Use when... |
| Use |
You need fast deterministic integration tests with common MongoDB command paths |
| Use |
You want to remove container startup cost in routine CI/local runs |
| Do not use |
You require full MongoDB parity (replica set, distributed semantics, advanced unsupported operators) |
| Do not use |
Your test harness strictly depends on external mongodb:// runtime behavior |
Quick Start
1) Add dependency
dependencies {
testImplementation("io.github.midagedev:jongodb:<version>")
}
Replace <version> with the latest published version from Maven Central.
2) Spring Boot integration
Single-hook annotation style:
@SpringBootTest
@JongodbMongoTest
class MyIntegrationTest {
}
Initializer style:
@SpringBootTest
@ContextConfiguration(initializers = JongodbMongoInitializer.class)
class MyIntegrationTest {
}
Dynamic property style:
@SpringBootTest
class MyIntegrationTest {
@DynamicPropertySource
static void mongoProps(DynamicPropertyRegistry registry) {
JongodbMongoDynamicPropertySupport.register(registry);
}
}
3) Run tests
gradle test
Requirements:
Standalone TCP Launcher
jongodb can run as a standalone TCP process and expose a standard mongodb:// URI.
For detailed launcher usage (Java/binary runtime selection and framework examples), see:
packages/memory-server/README.md
Node Adapter
Node adapter package: @jongodb/memory-server (source under packages/memory-server).
Current state:
- framework-agnostic runtime helper (
./runtime)
- launcher modes:
auto / binary / java
- standalone launcher process management
- optional single-node replica-set semantic profile (
topologyProfile=singleNodeReplicaSet)
- platform binary package targets: darwin-arm64, linux-x64-gnu, win32-x64
- Jest/Vitest/Nest-Jest helpers
- CI release workflow:
.github/workflows/npm-node-release.yml
Node runtime note:
- default
auto mode: binary first, then Java classpath fallback
- Java runtime requires
classpath option or JONGODB_CLASSPATH
- detailed usage/examples:
packages/memory-server/README.md
- migration guide from
mongodb-memory-server: docs/NODE_MIGRATION_FROM_MONGODB_MEMORY_SERVER.md
Transaction Contract (Current)
Supported in current scope:
- single transaction-manager flow with one or multiple MongoTemplate/Repository paths
- transactional commit/abort lifecycle (
startTransaction / commitTransaction / abortTransaction)
- transaction-scoped snapshot reads for
find, aggregate, and countDocuments
- out-of-transaction writes in different namespaces are preserved at commit
- out-of-transaction writes in same namespace with different
_id are preserved at commit
Deterministic conflict policy:
- if transactional and non-transactional writes target the same
_id, commit applies the transactional version
Out of scope:
- distributed transaction semantics
- multi-node replica-set deployment behavior (elections/lag/step-down)
- advanced retry semantics across real process/network faults
Compatibility Snapshot
This project targets integration-test compatibility for common Spring data paths, not full MongoDB parity.
| Area |
Current level |
Notes |
| Command surface |
25 handlers |
Mix of Supported and Partial |
| Query language |
Core comparison/logical/array/regex + partial $expr (including $add subset) |
Advanced parity incomplete |
| Aggregation |
Core stages, analytics accumulators, UTC $dateTrunc, $setWindowFields sequence subset, and minimal $graphLookup |
Full operator coverage not implemented |
| Transactions |
Single-process session/transaction flow |
Namespace-aware commit merge + snapshot reads (find/aggregate/countDocuments) + deterministic retry labels/contracts |
| Deployment profile |
Standalone + single-node replica-set semantic profile |
Replica-set profile exposes primary-only handshake/URI semantics for driver compatibility |
| Wire protocol |
OP_MSG + OP_QUERY |
In-process ingress and standalone TCP launcher mode, with OP_QUERY namespace-based $db fallback |
Support manifest summary:
Supported: 7
Partial: 7
Unsupported: 0
Release-candidate certification evidence for v0.1.9 (2026-05-09; commit b44be73):
- Official Suite Sharded: run
25603109902 (total=1292, mismatch=0, error=0, strict gate)
- R3 Failure Ledger: run
25603109886 (failureCount=0)
- Complex Query Certification: run
25603109905 (packVersion=complex-query-pack-v3, mismatchCount=0, unsupportedByPolicyCount=0)
- R3 External Canary: run
25603109900 (projectCount=3, canaryFail=0, rollbackSuccess=3)
Details:
docs/SUPPORT_MATRIX.md
docs/COMPATIBILITY.md
Migration Notes
From Testcontainers
Before:
@Container
static MongoDBContainer mongo = new MongoDBContainer("mongo:7");
@DynamicPropertySource
static void mongoProps(DynamicPropertyRegistry registry) {
registry.add("spring.data.mongodb.uri", mongo::getReplicaSetUrl);
}
After:
@DynamicPropertySource
static void mongoProps(DynamicPropertyRegistry registry) {
JongodbMongoDynamicPropertySupport.register(registry);
}
Implemented Command Handlers
hello, isMaster, ping, buildInfo, getParameter
insert, find, distinct, aggregate, getMore, killCursors
createIndexes, listIndexes, listCollections, drop, dropDatabase
update, delete, bulkWrite
findAndModify, countDocuments, replaceOne, findOneAndUpdate, findOneAndReplace
commitTransaction, abortTransaction
Known Limitations
- partial query and aggregation parity
- collation and TTL runtime semantics are subset-only, not full server parity
- limited update operator coverage
- no multi-node replica-set or sharded topology semantics
Unsupported branches are standardized progressively as:
codeName=NotImplemented
errorLabels=["UnsupportedFeature"]
Documentation
- Usage:
docs/USAGE.md
- Spring integration:
docs/SPRING_TESTING.md
- Fixture manifest:
docs/FIXTURE_MANIFEST.md
- Fixture playbook:
docs/FIXTURE_PLAYBOOK.md
- Compatibility boundary:
docs/COMPATIBILITY.md
- Complex-query certification:
docs/COMPLEX_QUERY_CERTIFICATION.md
- Support matrix:
docs/SUPPORT_MATRIX.md
- Compatibility scorecard:
docs/COMPATIBILITY_SCORECARD.md
- Release checklist:
docs/RELEASE_CHECKLIST.md
- Roadmap:
docs/ROADMAP.md
- Changelog:
CHANGELOG.md
- Contributing:
CONTRIBUTING.md
- Research notes:
docs/research/README.md
Release Process (Maintainers)
- Push tag
vX.Y.Z.
- Ensure CI test gates are green (
CI Test Suite and compatibility workflows as needed).
- GitHub Actions workflow
.github/workflows/maven-central-release.yml publishes to Maven Central.
- Workflow creates GitHub Release notes.
Required secrets:
MAVEN_CENTRAL_USERNAME
MAVEN_CENTRAL_PASSWORD
GPG_PUBLIC_KEY
GPG_SECRET_KEY
GPG_PASSPHRASE