Note: this doc is being continuously updated while changes are being made to the unit test framework.

Overview

Features

The MongoDB unit test framework is a thin layer built atop GoogleTest, so most GoogleTest features (see Google Test documentation) are available for use aside from anything listed out in Banned Features. The unit testing framework also includes enhanced reporting of test output (see Enhanced Reporting of Test Output).

The core unittest features can be accessed by including the mongo/unittest/unittest.h header and using the mongo_cc_unit_test bazel rule.

GoogleTest Features

Parameterized tests

Parameterized tests are a GoogleTest feature that allows the same test logic to be run with different values or types (see GoogleTest docs on Value-Parameterized Tests and Typed Tests).

class TestFixture :
    public testing::TestWithParam<mongo::repl::ReadConcernLevel> {
};

INSTANTIATE_TEST_SUITE_P(TestSuite,
                         TestFixture,
                         testing::Values(ReadConcernLevel::kLocalReadConcern,
                                         ReadConcernLevel::kMajorityReadConcern));

TEST_P(TestFixture, MongoTest) {
    ...
    sendRead(GetParam()); // Uses either ReadConcernLevel::kLocalReadConcern or
                          // ReadConcernLevel::kMajorityReadConcern
}

GoogleMock

GoogleMock can be used by including the mongo/unittest/unittest.h header. You should never directly include <gmock/gmock.h>. There are matchers for common mongo types such as BSONObj in mongo/unittest/matcher.h.

Banned Features

• ASSERT_DEATH - should not be used. Use DEATH_TEST instead (see Death Tests).

Upcoming Features

• IDE Integration
• Color output (Evergreen support, filter out color when terminal not detected)
• Output filtering/formatting
• New APIs to help with unit testing developer experience

Throwing Assertions

Unlike GoogleTest's fatal test assertions, which implements fatal assertions with return;, we throw an exception when our fatal assertions are triggered. This is to avoid limitations of GoogleTest fatal assertions, such as no fatal assertions allowed in non-void helper functions.

Enhanced Reporting of Test Output

The Enhanced Reporter improves test reporting by colorizing and formatting output, maintaining a progress indicator, printing enhanced failure information, and suppressing log output on passing tests.

These command line flags may be used to configure the Enhanced Reporter:

• --showEachTest - turns off any suppresion of log output.
• --enhancedReporter=<true/false> - enable all of the Enhanced Reporter behavior described above.

Death Tests

The MongoDB unit testing framework uses DEATH_TEST (with DEATH_TEST_F, DEATH_TEST_REGEX, and DEATH_TEST_REGEX_F variants) to test code that is expected to cause the process to terminate. This should replace all uses of the ASSERT_DEATH macro from GoogleTest (see unittest/death_test.h for more details).

Similar to GoogleTest, DEATH_TEST test suite names should be suffixed with DeathTest. For instance, for a death test intending to be associated with SuiteName should use SuiteNameDeathTest (see GoogleTest's Death Test naming).

TEST(SuiteName, TestName) {
    ...
}

DEATH_TEST(SuiteNameDeathTest, TestName) {
    ...
}

using FixtureNameDeathTest = FixtureName;
DEATH_TEST_F(FixtureNameDeathTest, TestName) {
    ...
}