Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Launch a stand-alone MongoDB Topology for use within a Test Suite.

Build status License


mongodb-sandbox provides an easy way to run a self-contained MongoDB Topology within the runtime execution of a Test Suite, participating in its lifecycle hooks;

If mongodb-sandbox isn't your ๐Ÿต cup of tea, alternative modules to consider might include;

mongodb-sandbox was inspired by Mockgoose, a module which has since been deprecated. At its core, mongodb-sandbox is an assemblage of


npm install --save-dev mongodb-sandbox

This module supports Node.js 6.x and above.


All Collections in the Sandbox Database get purged at the end of every Test Case.

As a safety measure, immediately after launching its Topology's daemon, the Lifecycle connects to the Sandbox and detects the presence of Documents. After all, if it's truly a volatile Sandbox, then no Documents should be found, right? If any are found, then it's possible that the Client has connected to a "real" Database by mistake;

  • the Test Suite gets terminated
  • the "real" Database is left untouched

MongoDB binaries are automatically downloaded, if not already present. By default, each version of the binaries is cached locally to ensure that your Test Suite runs quickly on subsequent launches.

The binaries are downloaded on-demand, vs. during 'postinstall'. Your first Test Suite execution will take some extra time on launch. The Test Case timeout is programatically extended to 90s to accomodate the time spent on

  • downloading the MongoDB binaries
  • launching the Topology

The module produces additional logging via debug.

// when running the Test Suite for your project ...
DEBUG=mongodb-sandbox npm test

Documentation is generated by jsdoc-to-markdown.


Please consult the JSDocs for additional Examples.

Here are ways to embed a Lifecycle into your Test Framework, and within a Test Case, connect your own MongoClient instance to the Sandbox.

The trick here is to capture the Test Framework context and provide it to the Lifecycle so that it can extend the Test Case timeout, as mentioned in Features.

Example for the Mocha Framework

In mocha, use a before block to capture the Test Framework context, construct your Lifecycle around it, and then register the rest of the hooks into the Framework.

const { expect } = require('chai');
const { MongoClient } = require('mongodb');
const { createSandbox } = require('mongodb-sandbox');

const sandbox = createSandbox();

before(function() {
  const lifecycle = sandbox.lifecycle(this);


describe('the Sandbox', () => {
  it('is running', () => {

  it('can be pinged', () => {
    const { url } = sandbox.config;

    return MongoClient.connect(url, { useNewUrlParser: true })
    .then((client) => {
      return client.db().admin().ping()
      .then((response) => {
        expect(response).to.deep.equal({ ok: 1 });

        return client.close();

Examples for other Frameworks

Please submit a Pull Request if you come up with a good one ๐Ÿ‘ .

That'll likely involve

  • enhancing the Lifecycle to detect & adjust the Test Framework context
  • adding a good-lookin' Example
  • checking it off the TODO list โ˜‘๏ธ

Configuration Options

Please consult the JSDocs.


Please consult the JSDocs.


  • Test Framework Examples for
  • Auto-timeout extension for Test Frameworks
    • mocha
    • tape
    • ava
    • jest
    • Your Favorite
  • Multi-process concurrency support, because this
  • Support for ReplicaSet Topology (Server-only for now)

Why Mocha?

C'mon buddy, that's the "nobody ever got fired for buying IBM equipment" of JavaScript testing frameworks. Couldn't you use something a bit cooler?

Honestly, I tried, but

  • tape doesn't seem to have the necessary Lifecycle hook support.
  • ava's multi-process concurrency makes it incredibly difficult to start up a Sandbox, particularly at the juncture of allocating & reserving a unique port. So for the moment, ava and other concurrent-running Test Frameworks are not supported pending a TODO.
  • I find jest to be too opinionated and React-focused.

Whereas mocha is perfectly suited for the job at hand.

So that's why.


WTFPL. Copyright (C) 2004 Sam Hocevar


Launch a stand-alone MongoDB Topology for use within a Test Suite.







No packages published