Test the MongoDB Server

As you work, you should periodically run the existing test suite to ensure that you have not unintentionally broken anything. If you intend to make a change that will break an existing test, update the test appropriately.

We have three main “categories” of tests [1]: JavaScript tests, (new-style) C++ unit tests, and (old-style) C++ db tests. Avoid writing new db tests whenever possible as we are moving towards deprecating and deleting all db tests in favor of unit tests.

JavaScript tests are mainly for integration testing, while C++ tests are for unit tests. Therefore, when changing a component of the codebase, you will likely want to run a combination of C++ and JavaScript tests.

For more information on writing your own tests, refer to Write Tests for Server Code.

We suggest that you test your changes on whatever operating systems you have access to, as we will test your patch on multiple systems before accepting it.

[1]We use cpplint to perform some basic style-checking.

Running JavaScript Tests

All JavaScript tests are in the jstests directory. These tests exist to test the binaries as is rather than building new “test” binaries. In the jstests directory, subdirectories exist for the different test suites, grouped roughly by what they test. The jstests/core directory is the “default” directory for general-purpose tests.

Execute the JavaScript tests using the mongo shell, as in:

mongo jstests/core/basic1.js
mongo jstests/core/count.js

Different tests assume different environments. For instance, some tests may require authentication and access control, others require or SSL encrypted connections.

The program:mongo shell has helpers to spawn new processes. For example, certain JavaScript tests set up a sharded and/or replicated environment or run other Mongo binaries. For more information on how that happens, see Write Tests for Server Code.

During development, you may wish to run a small selection of tests instead of the full suite. Often, the names of the test files give a good clue as to what they test. Alternatively, to get a targeted subset of test files to run, you can also run the following in the jstests directory where <command> is the shell helper corresponding to the code path you’re changing:

git grep -l <command>


With smoke.py, you can run a subsets of the tests in jstests/. You can find smoke.py in the buildscripts directory.

When smoke.py runs tests, it starts up an instance of mongod, runs the tests, and then shuts down the mongod. You can run smoke.py while running other instances of MongoDB on the same machine; it uses ports in the 30000 range and its own data directories.


By default, smoke.py will run tests that create data in /data/db, which may interfere with other MongoDB instances you are running. To change the directory in which the smoke tests create databases, use --smoke-db-prefix=/some/other/path.

You must run smoke.py from the top-level directory of a MongoDB source repository. This directory must contain at least the mongo and mongod binaries. For certain tests, you will also need to build the tools and mongos.

To run smoke.py, you need a recent version of PyMongo.

To see the possible options for smoke.py, run:

python buildscripts/smoke.py --help

To run specific tests, use the --mode=files option:

python buildscripts/smoke.py --mode=files jstests/core/find1.js

You can specify as many files as you want.

Running C++ DB Tests

All db tests are in the dbtests directory. These tests are “heavy”: they depend on a large portion of the kernel code. In this sense, the old-style “unit tests” are closer to integration tests than true unit tests. Running a db test requires a great deal of setup, for example, initializing the global authorization manager and creating at least one thread.

C++ db tests test functionality that is close to disk. Why? Because this functionality is not modular: currently, MongoDB’s dependency structure does not allow us to isolate close-to-disk functionality. As our dependencies become better-defined and the codebase becomes more modular, we can port more and more db tests over to the new style unit tests.

Compile C++ db tests by calling from the root directory:

scons dbtest

This compiles the source for all db tests into a single executable called dbtest. To list the available old style unit tests, call:

./dbtest --list

To run a specific test, call:

./dbtest <testname>

Running C++ Unit Tests

New-style unit tests are in the same directory as the files they tests. The test files take their name from the files that they test but include _test; e.g. foo_test.cpp to test foo.cpp.

Unlike db tests, the new-style tests are standalone: each one can be an independent SCons target. These tests are enumerated in build/unittests.txt.

To run all new-style C++ unit tests, that you can use SCons:

scons smokeCppUnitTests

In some cases, you may just want to run one or two of the unit tests. Here is an example of explicitly building and running a single C++ unit test:

scons ./build/unittests/mutable_bson_test