<!-- GOOGLETEST_CM0016 DO NOT DELETE -->
+<!-- GOOGLETEST_CM0035 DO NOT DELETE -->
+
## Introduction
Now that you have read the [googletest Primer](primer.md) and learned how to
example, if you define `IsEven()` as:
```c++
-::testing::AssertionResult IsEven(int n) {
+testing::AssertionResult IsEven(int n) {
if ((n % 2) == 0)
- return ::testing::AssertionSuccess();
+ return testing::AssertionSuccess();
else
- return ::testing::AssertionFailure() << n << " is odd";
+ return testing::AssertionFailure() << n << " is odd";
}
```
success message:
```c++
-::testing::AssertionResult IsEven(int n) {
+testing::AssertionResult IsEven(int n) {
if ((n % 2) == 0)
- return ::testing::AssertionSuccess() << n << " is even";
+ return testing::AssertionSuccess() << n << " is even";
else
- return ::testing::AssertionFailure() << n << " is odd";
+ return testing::AssertionFailure() << n << " is odd";
}
```
(`pred_formatn`), which is a function or functor with the signature:
```c++
-::testing::AssertionResult PredicateFormattern(const char* expr1,
- const char* expr2,
- ...
- const char* exprn,
- T1 val1,
- T2 val2,
- ...
- Tn valn);
+testing::AssertionResult PredicateFormattern(const char* expr1,
+ const char* expr2,
+ ...
+ const char* exprn,
+ T1 val1,
+ T2 val2,
+ ...
+ Tn valn);
```
where `val1`, `val2`, ..., and `valn` are the values of the predicate arguments,
int SmallestPrimeCommonDivisor(int m, int n) { ... }
// A predicate-formatter for asserting that two integers are mutually prime.
-::testing::AssertionResult AssertMutuallyPrime(const char* m_expr,
- const char* n_expr,
- int m,
- int n) {
- if (MutuallyPrime(m, n)) return ::testing::AssertionSuccess();
+testing::AssertionResult AssertMutuallyPrime(const char* m_expr,
+ const char* n_expr,
+ int m,
+ int n) {
+ if (MutuallyPrime(m, n)) return testing::AssertionSuccess();
- return ::testing::AssertionFailure() << m_expr << " and " << n_expr
+ return testing::AssertionFailure() << m_expr << " and " << n_expr
<< " (" << m << " and " << n << ") are not mutually prime, "
<< "as they have a common divisor " << SmallestPrimeCommonDivisor(m, n);
}
etc).
```c++
-EXPECT_PRED_FORMAT2(::testing::FloatLE, val1, val2);
-EXPECT_PRED_FORMAT2(::testing::DoubleLE, val1, val2);
+EXPECT_PRED_FORMAT2(testing::FloatLE, val1, val2);
+EXPECT_PRED_FORMAT2(testing::DoubleLE, val1, val2);
```
Verifies that `val1` is less than, or almost equal to, `val2`. You can replace
### Asserting Using gMock Matchers
-[gMock](../../googlemock) comes with a library of matchers for validating
-arguments passed to mock objects. A gMock *matcher* is basically a predicate
-that knows how to describe itself. It can be used in these assertion macros:
+[gMock](../../googlemock) comes with
+[a library of matchers](../../googlemock/docs/cheat_sheet.md#MatcherList) for
+validating arguments passed to mock objects. A gMock *matcher* is basically a
+predicate that knows how to describe itself. It can be used in these assertion
+macros:
<!-- mdformat off(github rendering does not support multiline tables) -->
your [own matchers](../../googlemock/docs/cook_book.md#NewMatchers) too.
gMock is bundled with googletest, so you don't need to add any build dependency
-in order to take advantage of this. Just include `"testing/base/public/gmock.h"`
+in order to take advantage of this. Just include `"gmock/gmock.h"`
and you're ready to go.
### More String Assertions
```c++
// Currently still in //template/prototemplate/testing:xpath_matcher
#include "template/prototemplate/testing/xpath_matcher.h"
-using prototemplate::testing::MatchesXPath;
+using ::prototemplate::testing::MatchesXPath;
EXPECT_THAT(html_string, MatchesXPath("//a[text()='click here']"));
```
```c++
template <typename T> class Foo {
public:
- void Bar() { ::testing::StaticAssertTypeEq<int, T>(); }
+ void Bar() { testing::StaticAssertTypeEq<int, T>(); }
};
```
[constructor/destructor vs. `SetUp`/`TearDown`](faq.md#CtorVsSetUp)
WARNING: A fatal assertion in a helper function (private void-returning method)
-called from a constructor or destructor does not does not terminate the current
-test, as your intuition might suggest: it merely returns from the constructor or
+called from a constructor or destructor does not terminate the current test, as
+your intuition might suggest: it merely returns from the constructor or
destructor early, possibly leaving your object in a partially-constructed or
partially-destructed state! You almost certainly want to `abort` or use
`SetUp`/`TearDown` instead.
vector<pair<Bar, int> > bar_ints = GetBarIntVector();
EXPECT_TRUE(IsCorrectBarIntVector(bar_ints))
- << "bar_ints = " << ::testing::PrintToString(bar_ints);
+ << "bar_ints = " << testing::PrintToString(bar_ints);
```
## Death Tests
------------------------------------------------ | ------------------------------------------------ | --------
`ASSERT_DEATH(statement, matcher);` | `EXPECT_DEATH(statement, matcher);` | `statement` crashes with the given error
`ASSERT_DEATH_IF_SUPPORTED(statement, matcher);` | `EXPECT_DEATH_IF_SUPPORTED(statement, matcher);` | if death tests are supported, verifies that `statement` crashes with the given error; otherwise verifies nothing
+`ASSERT_DEBUG_DEATH(statement, matcher);` | `EXPECT_DEBUG_DEATH(statement, matcher);` | `statement` crashes with the given error **in debug mode**. When not in debug (i.e. `NDEBUG` is defined), this just executes `statement`
`ASSERT_EXIT(statement, predicate, matcher);` | `EXPECT_EXIT(statement, predicate, matcher);` | `statement` exits with the given error, and its exit code matches `predicate`
where `statement` is a statement that is expected to cause the process to die,
code.
```c++
-::testing::KilledBySignal(signal_number) // Not available on Windows.
+testing::KilledBySignal(signal_number) // Not available on Windows.
```
This expression is `true` if the program was killed by the given signal.
}
TEST(MyDeathTest, NormalExit) {
- EXPECT_EXIT(NormalExit(), ::testing::ExitedWithCode(0), "Success");
+ EXPECT_EXIT(NormalExit(), testing::ExitedWithCode(0), "Success");
}
TEST(MyDeathTest, KillMyself) {
- EXPECT_EXIT(KillMyself(), ::testing::KilledBySignal(SIGKILL),
+ EXPECT_EXIT(KillMyself(), testing::KilledBySignal(SIGKILL),
"Sending myself unblockable signal");
}
```
duplicating its code:
```c++
-class FooTest : public ::testing::Test { ... };
+class FooTest : public testing::Test { ... };
using FooDeathTest = FooTest;
Under the hood, `ASSERT_EXIT()` spawns a new process and executes the death test
statement in that process. The details of how precisely that happens depend on
-the platform and the variable ::testing::GTEST_FLAG(death_test_style) (which is
+the platform and the variable `::testing::GTEST_FLAG(death_test_style)` (which is
initialized from the command-line flag `--gtest_death_test_style`).
* On POSIX systems, `fork()` (or `clone()` on Linux) is used to spawn the
```c++
int main(int argc, char** argv) {
- InitGoogle(argv[0], &argc, &argv, true);
- ::testing::FLAGS_gtest_death_test_style = "fast";
+ testing::InitGoogleTest(&argc, argv);
+ testing::FLAGS_gtest_death_test_style = "fast";
return RUN_ALL_TESTS();
}
TEST(MyDeathTest, TestOne) {
- ::testing::FLAGS_gtest_death_test_style = "threadsafe";
+ testing::FLAGS_gtest_death_test_style = "threadsafe";
// This test is run in the "threadsafe" style:
ASSERT_DEATH(ThisShouldDie(), "");
}
## Using Assertions in Sub-routines
+Note: If you want to put a series of test assertions in a subroutine to check
+for a complex condition, consider using
+[a custom GMock matcher](../../googlemock/docs/cook_book.md#NewMatchers)
+instead. This lets you provide a more readable error message in case of failure
+and avoid all of the issues described below.
+
### Adding Traces to Assertions
If a test sub-routine is called from several places, when an assertion inside it
// in Subroutine() to abort the entire test.
// The actual behavior: the function goes on after Subroutine() returns.
- int* p = NULL;
+ int* p = nullptr;
*p = 3; // Segfault!
}
```
fixture, you must add the `::testing::Test::` prefix, as in:
```c++
-if (::testing::Test::HasFatalFailure()) return;
+if (testing::Test::HasFatalFailure()) return;
```
Similarly, `HasNonfatalFailure()` returns `true` if the current test has at
Here's an example of per-test-suite set-up and tear-down:
```c++
-class FooTest : public ::testing::Test {
+class FooTest : public testing::Test {
protected:
// Per-test-suite set-up.
// Called before the first test in this test suite.
// Can be omitted if not needed.
static void TearDownTestSuite() {
delete shared_resource_;
- shared_resource_ = NULL;
+ shared_resource_ = nullptr;
}
// You can define per-test set-up logic as usual.
static T* shared_resource_;
};
-T* FooTest::shared_resource_ = NULL;
+T* FooTest::shared_resource_ = nullptr;
TEST_F(FooTest, Test1) {
... you can refer to shared_resource_ here ...
environment, which knows how to set-up and tear-down:
```c++
-class Environment : public ::testing::Environment {
+class Environment : public testing::Environment {
public:
~Environment() override {}
variable like this:
```c++
-::testing::Environment* const foo_env =
- ::testing::AddGlobalTestEnvironment(new FooEnvironment);
+testing::Environment* const foo_env =
+ testing::AddGlobalTestEnvironment(new FooEnvironment);
```
However, we strongly recommend you to write your own `main()` and call
NOTE: The code above must be placed at global or namespace scope, not at
function scope.
-NOTE: Don't forget this step! If you do your test will silently pass, but none
-of its suites will ever run!
-
-There is work in progress to make omitting `INSTANTIATE_TEST_SUITE_P` show up
-under the `GoogleTestVerification` test suite and to then make that an error.
-If you have a test suite where that omission is not an error, for example it is
-in a library that may be linked in for other reason or where the list of test
-cases is dynamic and may be empty, then this check can be suppressed by tagging
-the test suite:
+Per default, every `TEST_P` without a corresponding `INSTANTIATE_TEST_SUITE_P`
+causes a failing test in test suite `GoogleTestVerification`. If you have a test
+suite where that omission is not an error, for example it is in a library that
+may be linked in for other reason or where the list of test cases is dynamic and
+may be empty, then this check can be suppressed by tagging the test suite:
```c++
GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST(FooTest);
```c++
enum class MyType { MY_FOO = 0, MY_BAR = 1 };
-class MyTestSuite : public testing::TestWithParam<std::tuple<MyType, string>> {
+class MyTestSuite : public testing::TestWithParam<std::tuple<MyType, std::string>> {
};
INSTANTIATE_TEST_SUITE_P(
testing::Values(MyType::VALUE_0, MyType::VALUE_1),
testing::ValuesIn("", "")),
[](const testing::TestParamInfo<MyTestSuite::ParamType>& info) {
- string name = absl::StrCat(
+ std::string name = absl::StrCat(
std::get<0>(info.param) == MY_FOO ? "Foo" : "Bar", "_",
std::get<1>(info.param));
absl::c_replace_if(name, [](char c) { return !std::isalnum(c); }, '_');
```c++
template <typename T>
-class FooTest : public ::testing::Test {
+class FooTest : public testing::Test {
public:
...
- typedef std::list<T> List;
+ using List = std::list<T>;
static T shared_;
T value_;
};
```c++
template <typename T>
-class FooTest : public ::testing::Test {
+class FooTest : public testing::Test {
...
};
```
source files and instantiate it multiple times.
```c++
-typedef ::testing::Types<char, int, unsigned int> MyTypes;
+using MyTypes = ::testing::Types<char, int, unsigned int>;
INSTANTIATE_TYPED_TEST_SUITE_P(My, FooTest, MyTypes);
```
```c++
namespace my_namespace {
- class FooTest : public ::testing::Test {
+ class FooTest : public testing::Test {
protected:
...
};
the exception and assert on it. But googletest doesn't use exceptions, so how do
we test that a piece of code generates an expected failure?
-gunit-spi.h contains some constructs to do this. After #including this header,
+`"gtest/gtest-spi.h"` contains some constructs to do this. After #including this header,
you can use
```c++
Use case example:
```c++
-class MyFixture : public ::testing::Test {
+class MyFixture : public testing::Test {
public:
// All of these optional, just like in regular macro usage.
static void SetUpTestSuite() { ... }
void RegisterMyTests(const std::vector<int>& values) {
for (int v : values) {
- ::testing::RegisterTest(
+ testing::RegisterTest(
"MyFixture", ("Test" + std::to_string(v)).c_str(), nullptr,
std::to_string(v).c_str(),
__FILE__, __LINE__,
```c++
// Gets information about the currently running test.
// Do NOT delete the returned object - it's managed by the UnitTest class.
- const ::testing::TestInfo* const test_info =
- ::testing::UnitTest::GetInstance()->current_test_info();
+ const testing::TestInfo* const test_info =
+ testing::UnitTest::GetInstance()->current_test_info();
printf("We are in test %s of test suite %s.\n",
test_info->name(),
```
`current_test_info()` returns a null pointer if no test is running. In
-particular, you cannot find the test suite name in `TestSuiteSetUp()`,
-`TestSuiteTearDown()` (where you know the test suite name implicitly), or
+particular, you cannot find the test suite name in `SetUpTestSuite()`,
+`TearDownTestSuite()` (where you know the test suite name implicitly), or
functions called from them.
## Extending googletest by Handling Test Events
Here's an example:
```c++
- class MinimalistPrinter : public ::testing::EmptyTestEventListener {
+ class MinimalistPrinter : public testing::EmptyTestEventListener {
// Called before a test starts.
- virtual void OnTestStart(const ::testing::TestInfo& test_info) {
+ virtual void OnTestStart(const testing::TestInfo& test_info) {
printf("*** Test %s.%s starting.\n",
test_info.test_suite_name(), test_info.name());
}
// Called after a failed assertion or a SUCCESS().
- virtual void OnTestPartResult(const ::testing::TestPartResult& test_part_result) {
+ virtual void OnTestPartResult(const testing::TestPartResult& test_part_result) {
printf("%s in %s:%d\n%s\n",
test_part_result.failed() ? "*** Failure" : "Success",
test_part_result.file_name(),
}
// Called after a test ends.
- virtual void OnTestEnd(const ::testing::TestInfo& test_info) {
+ virtual void OnTestEnd(const testing::TestInfo& test_info) {
printf("*** Test %s.%s ending.\n",
test_info.test_suite_name(), test_info.name());
}
```c++
int main(int argc, char** argv) {
- ::testing::InitGoogleTest(&argc, argv);
+ testing::InitGoogleTest(&argc, argv);
// Gets hold of the event listener list.
- ::testing::TestEventListeners& listeners =
- ::testing::UnitTest::GetInstance()->listeners();
+ testing::TestEventListeners& listeners =
+ testing::UnitTest::GetInstance()->listeners();
// Adds a listener to the end. googletest takes the ownership.
listeners.Append(new MinimalistPrinter);
return RUN_ALL_TESTS();
everything in test suite `FooTest` except `FooTest.Bar` and everything in
test suite `BarTest` except `BarTest.Foo`.
+#### Stop test execution upon first failure
+
+By default, a googletest program runs all tests the user has defined. In some
+cases (e.g. iterative test development & execution) it may be desirable stop
+test execution upon first failure (trading improved latency for completeness).
+If `GTEST_FAIL_FAST` environment variable or `--gtest_fail_fast` flag is set,
+the test runner will stop execution as soon as the first test failure is
+found.
+
#### Temporarily Disabling Tests
If you have a broken test that you cannot fix right away, you can add the
// Tests that Foo does Abc.
TEST(FooTest, DISABLED_DoesAbc) { ... }
-class DISABLED_BarTest : public ::testing::Test { ... };
+class DISABLED_BarTest : public testing::Test { ... };
// Tests that Bar does Xyz.
TEST_F(DISABLED_BarTest, DoesXyz) { ... }
will use colors if and only if the output goes to a terminal and (on non-Windows
platforms) the `TERM` environment variable is set to `xterm` or `xterm-color`.
+#### Suppressing test passes
+
+By default, googletest prints 1 line of output for each test, indicating if it
+passed or failed. To show only test failures, run the test program with
+`--gtest_brief=1`, or set the GTEST_BRIEF environment variable to `1`.
+
#### Suppressing the Elapsed Time
By default, googletest prints the time it takes to run each test. To disable
googletest can emit a detailed XML report to a file in addition to its normal
textual output. The report contains the duration of each test, and thus can help
-you identify slow tests. The report is also used by the http://unittest
-dashboard to show per-test-method error messages.
+you identify slow tests.
To generate the XML report, set the `GTEST_OUTPUT` environment variable or the
`--gtest_output` flag to the string `"xml:path_to_output_file"`, which will
### Controlling How Failures Are Reported
+#### Detecting Test Premature Exit
+
+Google Test implements the _premature-exit-file_ protocol for test runners
+to catch any kind of unexpected exits of test programs. Upon start,
+Google Test creates the file which will be automatically deleted after
+all work has been finished. Then, the test runner can check if this file
+exists. In case the file remains undeleted, the inspected test has exited
+prematurely.
+
+This feature is enabled only if the `TEST_PREMATURE_EXIT_FILE` environment
+variable has been set.
+
#### Turning Assertion Failures into Break-Points
When running test programs under a debugger, it's very convenient if the
exception is thrown. To achieve that, set the `GTEST_CATCH_EXCEPTIONS`
environment variable to `0`, or use the `--gtest_catch_exceptions=0` flag when
running the tests.
+
+### Sanitizer Integration
+
+The
+[Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html),
+[Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer),
+and
+[Thread Sanitizer](https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual)
+all provide weak functions that you can override to trigger explicit failures
+when they detect sanitizer errors, such as creating a reference from `nullptr`.
+To override these functions, place definitions for them in a source file that
+you compile as part of your main binary:
+
+```
+extern "C" {
+void __ubsan_on_report() {
+ FAIL() << "Encountered an undefined behavior sanitizer error";
+}
+void __asan_on_error() {
+ FAIL() << "Encountered an address sanitizer error";
+}
+void __tsan_on_report() {
+ FAIL() << "Encountered a thread sanitizer error";
+}
+} // extern "C"
+```
+
+After compiling your project with one of the sanitizers enabled, if a particular
+test triggers a sanitizer error, googletest will report that it failed.
projects / ceph.git / blobdiff