106 lines
4.0 KiB
Markdown
106 lines
4.0 KiB
Markdown
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][google_test_docs]) are available for use aside from anything
|
|
listed out in [Banned Features](#banned-features). The unit testing framework also includes
|
|
enhanced reporting of test output (see
|
|
[Enhanced Reporting of Test Output](#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][value_parameterized_tests] and [Typed Tests][typed_tests]).
|
|
|
|
```cpp
|
|
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](#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][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][death_test_naming]).
|
|
|
|
```cpp
|
|
TEST(SuiteName, TestName) {
|
|
...
|
|
}
|
|
|
|
DEATH_TEST(SuiteNameDeathTest, TestName) {
|
|
...
|
|
}
|
|
|
|
using FixtureNameDeathTest = FixtureName;
|
|
DEATH_TEST_F(FixtureNameDeathTest, TestName) {
|
|
...
|
|
}
|
|
```
|
|
|
|
[death_test_naming]: https://github.com/google/googletest/blob/main/docs/advanced.md#death-test-naming
|
|
[death_test_h]: ../src/mongo/unittest/death_test.h
|
|
[google_test_docs]: https://github.com/google/googletest/blob/main/docs/primer.md
|
|
[value_parameterized_tests]: https://github.com/google/googletest/blob/main/docs/advanced.md#value-parameterized-tests
|
|
[typed_tests]: https://github.com/google/googletest/blob/main/docs/advanced.md#typed-tests
|