3.5 KiB
Fail Points
Fail points are test-only configurable hooks that can be triggered at runtime. Fail points allow tests to change behavior at pre-defined points to block threads, choose rarely executed branches, enhance diagnostics, or achieve any number of other aims. Fail points can be enabled, configured, and disabled via command request to a remote process or via an API within the same process.
For more on what test-only means and how to enable the configureFailPoint command, see test_commands.
Using Fail Points
A fail point must first be defined using MONGO_FAIL_POINT_DEFINE(myFailPoint). This statement
adds the fail point to a registry and allows it to be evaluated in code. There are three common
patterns for evaluating a fail point:
- Exercise a rarely used branch:
if (whenPigsFly || myFailPoint.shouldFail()) { ... } - Block until the fail point is unset:
myFailPoint.pauseWhileSet(); - Use the fail point's payload to perform custom behavior:
myFailPoint.execute([](const BSONObj& data) { useMyPayload(data); };
For more complete usage, see the fail point header or the fail point tests.
Configuring and Waiting on Fail Points
Fail point configuration involves choosing a "mode" for activation (e.g., "alwaysOn") and optionally
providing additional data in the form of a BSON object. For the vast majority of cases, this is done
by issuing a configureFailPoint command request. This is made easier in JavaScript using the
configureFailPoint helper from fail_point_util.js. Fail points can also be
useful in C++ unit tests and integration tests. To configure fail points on the local process, use
a FailPointEnableBlock to enable and configure the fail point for a given block scope. Finally,
a fail point can also be set via setParameter by its name prefixed with "failpoint." (e.g.,
"failpoint.myFailPoint").
Users can also wait until a fail point has been evaluated a certain number of times over its
lifetime. A waitForFailPoint command request will send a response back when the fail point has
been evaluated the given number of times. For ease of use, the configureFailPoint JavaScript
helper returns an object that can be used to wait a certain amount of times from when the fail
point was enabled. In C++ tests, users can invoke FailPoint::waitForTimesEntered() for similar
behavior. FailPointEnableBlock records the amount of times the fail point had been evaluated when
it was constructed, accessible via FailPointEnableBlock::initialTimesEntered().
For JavaScript examples, see the fail point JavaScript test. For the command implementations, see here.
The failCommand Fail Point
The failCommand fail point is a special fail point used to mock arbitrary response behaviors to
requests filtered by command, appName, etc. It is most often used to simulate specific conditions
between nodes like invalid replica set configurations. For examples of use, see the
failCommand JavaScript tests.