Test the MongoDB Server

As you work, you should periodically run the existing test suites 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 for integration testing.
  • (new-style) C++ unit tests for unit tests.
  • (old-style) C++ dbtests for unit tests. Avoid writing new dbtests whenever possible as we are moving towards deprecating and deleting all dbtests in favor of unit tests.

When changing a component of the codebase, you will likely want to run a combination of the 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.

Test Using mongo Shell

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 may require SSL encrypted connections.

The mongo shell has helpers to spawn new processes. For example, certain JavaScript tests set up a sharded and/or replicated environment or run other MongoDB binaries. For details, 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 can help you determine which tests to run as the names of these files can often indicate what they test. Alternatively, to get a targeted subset of test files to run, you can run the following operation in the jstests directory; the <command> is the shell helper corresponding to the code path you’re changing:

git grep -l <command>

Test Using resmoke.py

The buildscripts directory contains the file resmoke.py. With resmoke.py, you can run a subset of the tests in jstests/.

For most test suites, resmoke.py starts up an instance of mongod, runs the tests, and then shuts down the mongod. You can run resmoke.py while running other instances of mongod on the same machine; resmoke.py will find unused ports for any mongod instances it starts and provide them with their own data directories.


  • Tests which use shell helpers to spawn new processes do not acquire unused ports, but instead use ports in the 29000+ range. As such, they may conflict with other processes.
  • By default, resmoke.py will use a subdirectory of /data/db for the dbpath of any mongod processes it starts; this may interfere with other MongoDB instances you are running. To change the directory in which resmoke.py will create databases, use --dbpathPrefix=/some/other/path.

You must run resmoke.py from the top-level directory of a MongoDB source repository. At minimum, this directory must contain the mongo and mongod binaries. For certain tests, you will also need to build the tools (see Build MongoDB Tools From Source) and the mongos binary, and put them in this directory as well.

To run remoke.py, you need a recent version of PyMongo and PyYaml.

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

python buildscripts/resmoke.py --help

To run specific tests, simply list them:

python buildscripts/resmoke.py jstests/core/find1.js jstests/core/explain*.js

You can specify as many files as you want.

We have also defined test suite configurations in the buildscripts/resmokeconfig/suites directory. To see which suites are available, run:

python buildscripts/resmoke.py --listSuites

To run a specific suite, use:

python buildscripts/resmoke.py --suites=<SUITE>

You can also run multiple suites by specifying a comma-separated list:

python buildscripts/resmoke.py --suites=<SUITE1>,<SUITE2>

Suites that start their own MongoDB processes, such as sharding and replica_sets, cannot be run in parallel. This is because tests that start their own processes will always try to use the same set of ports for their processes.

Other suites can, however, be run in parallel; e.g. core (and all variants, such as core_auth and core_small_oplog_rs), unittests, and dbtest.

To run the tests in parallel, specify the number of jobs using the --jobs option:

python buildscripts/resmoke.py --suites=<SUITE> --jobs=<N>


Although running the tests in parallel can, in some cases, significantly decrease execution time, use with caution. When resmoke.py needs to start a mongod or any other MongoDB deployment, it will set up one per job, which can be resource intensive.

Running dbtests

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

Compile C++ dbtests by calling from the root directory:

scons dbtest

This compiles the source for all dbtests 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 test. 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 dbtests, the new-style tests are standalone: each one is an independent SCons target. These tests are enumerated in build/unittests.txt, which is generated by SCons upon building the unittests target.

To run all new-style C++ unit tests:

  1. Build the tests:

    scons unittests
  2. Use resmoke.py to run all of them. To decrease the execution time, specify multiple jobs:

    python buildscripts/resmoke.py --suites=unittests --jobs=<N>

In some cases, you may just want to run one or two of the unit tests. For example, the following explicitly builds and runs a single C++ unit test mutable_bson_test:

scons ./build/unittests/mutable_bson_test