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 :
- (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.
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.
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.
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.
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>
buildscripts directory contains the file resmoke.py. With resmoke.py, you can run a subset of the tests in
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.
- 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
--basePortoption 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
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
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
python buildscripts/resmoke.py run --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.
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:
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:
To run a specific dbtest, call:
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
foo_test.cpp to test
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:
Build the tests:
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
scons ./build/unittests/mutable_bson_test ./build/unittests/mutable_bson_test
 We use
cpplint to perform some basic style-checking.