mongodb-sandbox

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

Purpose

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;

Related Modules

If mongodb-sandbox isn't your 🍵 cup of tea, alternative modules to consider might include;

• mongodb-memory-server

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

• mongodb-prebuilt
• portfinder
• mongodb-topology-manager

Installation

npm install --save-dev mongodb-sandbox

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

Features

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.

Examples

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);

  before(lifecycle.beforeAll);
  beforeEach(lifecycle.beforeEach);
  afterEach(lifecycle.afterEach);
  after(lifecycle.afterAll);
});


describe('the Sandbox', () => {
  it('is running', () => {
    expect(sandbox.isRunning).to.equal(true);
  });

  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.

Documentation

Please consult the JSDocs.

TODO

• Test Framework Examples for
  • mocha
  • tape
  • ava ... though be warned...
  • jest
  • Your Favorite
• 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.

License

WTFPL. Copyright (C) 2004 Sam Hocevar sam@hocevar.net