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 writing-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.

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 writing-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 use ports in a configurable range for any mongod instances it starts and provide them with their own data directories.

note

• By default, resmoke.py will use ports in the 20000+ range. If you have other programs running in that port range, the starting port is configurable via the --basePort option to resmoke.py
• 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 /contributors/tutorial/build-tools-from-source) and the mongos binary, and put them in this directory as well.

To run resmoke.py, install its pip dependencies defined in etc/pip/dev-requirements.txt.

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

python buildscripts/resmoke.py run --help

To run specific tests, simply list them:

python buildscripts/resmoke.py run 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 list-suites

To run a specific suite, use:

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

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

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

To run specific tests using a suite's configuration, just specify the test name(s) after specifying the suite:

python buildscripts/resmoke.py run --suites=<SUITE> path/to/tests/*.js

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

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

note

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. You can run all the dbtests in parallel by using `resmoke.py`:

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

To list the available dbtests, call:

./dbtest --list

To run a specific dbtest, 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 run --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
./build/unittests/mutable_bson_test

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