How do I mock MongoDB queries in tests?

Record your application once against a real MongoDB with Keploy. It captures each operation, its filter, and the BSON documents the server returned at the wire protocol, then answers the same operations from that recording during tests.

Can Keploy mock MongoDB aggregation pipelines?

Yes. The pipeline and its result are captured together during recording, so replay returns exactly what mongod computed. Unlike a hand-written stub, the recorded result is tied to the specific pipeline that produced it.

Does Keploy preserve ObjectId and Decimal128 types?

Yes. Keploy records the BSON response as the server sent it, so ObjectId, Decimal128, Long, and Date replay as their real types. That keeps driver-level conversion and serialisation bugs visible instead of hidden behind flattened strings.

Does Keploy work with mongoose and PyMongo?

Yes, and identically. Capture happens at the MongoDB wire protocol beneath the driver, so mongoose, the official Node driver, PyMongo, Motor, and the Go and Java drivers all record and replay the same documents.

Can Keploy mock MongoDB transactions?

Yes. Session start, transaction commit, and abort are protocol-level commands, so a multi-document transaction replays in the same order with the same responses and write results it originally received from the server.

Keploy as a MongoDB testing framework

Keploy mocks MongoDB by recording its wire protocol beneath your driver, capturing the exact documents and BSON types each query returned, then replaying them during tests. No mongod binary is downloaded, no replica set is started, and no collection is seeded.

Generate MongoDB tests free

keploy record -c "npm start"

18.4K+

1.2M+300M+mocks createdSlack

What Keploy gives a MongoDB team

Captured at the MongoDB wire protocol

Keploy reads the protocol beneath your driver, so each operation replays with the BSON documents mongod actually returned, together with its cursor and write-result metadata.

Below the Node, PyMongo, Go, and Java drivers
Filters and options captured per operation
Cursor and write results preserved
Sessions and transactions replay in order

Try Keploy for free Explore the docs

The problem

Why MongoDB integration tests slow teams down

The friction is rarely the assertions. It is everything around them — spinning up dependencies, keeping mocks honest, and repairing tests after every refactor.

Book a call Explore the docs

Three ways to do it

Testing MongoDB: by hand, with mongodb-memory-server, or with Keploy

mongodb-memory-server runs a real mongod, and downloads one into every environment to do it. Keploy records a real server once and replays its responses with no binary and no boot.

By hand

mongodb-memory-server

With Keploy

Select any row for the full comparison, with code.

Get started Book a call

Same coverage, three costs

What you write for MongoDB vs what Keploy records

All three produce the same assertion. Only the third still passes after the next refactor without anyone editing it.

By hand2–4 hours

orderRepo.stub.js

hand-written

// Hand-written stub: BSON types are flattened to plain JS.

const orders = {

ord_1: {

// The driver would return an ObjectId here, not a string.

_id: 'ord_1',

amountMinor: 4200,

state: 'NEW',

createdAt: '2026-09-01T09:00:00Z',

},

};

module.exports = {

findOne: async ({ _id }) => orders[_id] ?? null,

// Nothing evaluates this pipeline. The answer is just typed out.

aggregate: async () => [

{ _id: 'NEW', count: 1, total: 4200 },

],

updateOne: async ({ _id }, { $set }) => {

Object.assign(orders[_id], $set);

return { modifiedCount: 1 };

},

};

The aggregate stub returns the expected answer regardless of the pipeline passed in, so a stage in the wrong order is undetectable.

mongodb-memory-server1–2 hours

orderRepo.memory.test.js

tool-assisted

// mongodb-memory-server: a real mongod, downloaded per environment.

const { MongoMemoryServer } = require('mongodb-memory-server');

const { MongoClient } = require('mongodb');

let mongod, client, db;

beforeAll(async () => {

// Fetches a platform-specific mongod binary on a cold cache.

mongod = await MongoMemoryServer.create();

client = await MongoClient.connect(mongod.getUri());

db = client.db('orders');

await db.collection('orders').insertMany(seedDocuments);

});

afterAll(async () => {

await client.close();

await mongod.stop();

});

it('summarises orders by state', async () => {

const result = await db.collection('orders').aggregate([

{ $match: { state: 'NEW' } },

{ $group: { _id: '$state', total: { $sum: '$amountMinor' } } },

]).toArray();

expect(result[0].total).toBe(4200);

});

Real aggregation semantics — and a binary download, a server boot, and a seed step before the first assertion in every environment.

With Keploy~5 minutes

mocks.yaml

auto-generated

# Recorded with: keploy record -c 'npm start'

# The MongoDB response, captured at the wire protocol.

version: api.keploy.io/v1beta1

kind: Mongo

name: mock-3

spec:

request:

collection: orders

operation: find

filter:

_id: "ObjectId('66f1a2c4e1b2c3d4e5f60718')"

response:

# BSON types preserved exactly as the server sent them.

documents:

- _id: "ObjectId('66f1a2c4e1b2c3d4e5f60718')"

amountMinor: "NumberLong(4200)"

state: "NEW"

createdAt: "ISODate('2026-09-01T09:00:00Z')"

cursor_id: 0

ok: 1

ObjectId, NumberLong, and ISODate replay as the BSON types mongod sent, so driver conversion is exercised rather than assumed.

Times are estimates for authoring one endpoint’s coverage from scratch, not measurements.

Explore the docs Request a trial

Keploy vs the alternatives

MongoDB testing tools, compared

The options a team on document and wide-column stores actually reaches for, and where each one genuinely wins. Select a row for the full comparison.

Keploy

Testcontainers

mongodb-memory-server

mongomock

Fongo

Postman

SmartBear ReadyAPI

Best in classStrongPartialNot covered

Assessments reflect each tool’s documented behaviour, not benchmark measurements.

Request a trial Book a call

How it works

Record your MongoDB app once, replay it forever

Keploy sits below your MongoDB process at the network layer. It watches the calls your app already makes, then serves them back on replay so tests run with no dependencies attached.

Your MongoDB appGET/api/v1/orders/{id}200

RecordingKeploy proxyeBPF · userspace

Node.jsThe official driver and mongoose

PythonPyMongo and Motor

Gomongo-driver

JavaThe MongoDB Java driver and Spring Data MongoDB

+4 more MongoDB clients

An example shape of a captured call. Your own endpoints and dependencies come from your real traffic, so nothing here has to be written by hand.

Try Keploy for free Request a trial

Mock coverage

MongoDB clients Keploy records, driver by driver

Keploy captures MongoDB at the wire protocol, so 6 of these 8 clients need no adapter, no test double, and no MongoDB instance in CI.

Auto-mocked
Node.jsView page
The official driver and mongoose
Auto-mocked
PythonView page
PyMongo and Motor
Auto-mocked
GoView page
mongo-driver
Auto-mocked
JavaView page
The MongoDB Java driver and Spring Data MongoDB
Auto-mocked
ExpressView page
Route handlers using mongoose models
Auto-mocked
Spring BootView page
Spring Data MongoDB repositories
Partial
.NET
The MongoDB .NET driver
Partial
Rust
The mongodb crate

Explore the docs Book a call

Quick start

Your first MongoDB test suite in under five minutes

Every command below runs against your existing MongoDB service. Nothing in your source tree changes.

1
1Install the Keploy CLI
One binary on the recording machine. Nothing is installed into MongoDB and no driver wrapper is needed.
curl -sSL https://keploy.io/install.sh | bash
2
2Record with your development MongoDB reachable
Run the app as usual. Every find, insert, update, and aggregate is captured with the documents mongod returned.
keploy record -c "npm start"
3
3Exercise the paths that hit the database
Aggregation pipelines, transactions, and cursor-based reads all record with their filters and responses.
curl localhost:3000/orders/ord_1
curl localhost:3000/orders/summary?state=NEW
4
4Replay with MongoDB stopped
Shut mongod down and run the suite. If replay passes, every operation your code performs is answered by a recorded mock.
keploy test -c "npm start" --delay 10