3party/googletest
0
0
Fork 0
mirror of https://github.com/google/googletest.git synced 2024-12-27 10:11:03 +08:00
Code Issues Projects Releases Wiki Activity

Documentation sync in preparation to including docs with full source sync

Browse Source
This commit is contained in:
Gennadiy Civil 2019-06-24 13:52:17 -04:00
parent 834dff3b52
commit 437e1008c9
2 changed files with 37 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
googletest/docs/advanced.md
View File

@ -1,13 +1,14 @@
# Advanced googletest Topics # Advanced googletest Topics
<!-- GOOGLETEST_CM0015 DO NOT DELETE -->
## Introduction ## Introduction
Now that you have read the [googletest Primer](primer.md) and learned how to write Now that you have read the [googletest Primer](primer.md) and learned how to
tests using googletest, it's time to learn some new tricks. This document will write tests using googletest, it's time to learn some new tricks. This document
show you more assertions as well as how to construct complex failure messages, will show you more assertions as well as how to construct complex failure
propagate fatal failures, reuse and speed up your test fixtures, and use various messages, propagate fatal failures, reuse and speed up your test fixtures, and
flags with your tests. use various flags with your tests.
## More Assertions ## More Assertions
@ -103,11 +104,13 @@ If you already have a function or functor that returns `bool` (or a type that
can be implicitly converted to `bool`), you can use it in a *predicate can be implicitly converted to `bool`), you can use it in a *predicate
assertion* to get the function arguments printed for free: assertion* to get the function arguments printed for free:
| Fatal assertion | Nonfatal assertion | Verifies | | Fatal assertion | Nonfatal assertion | Verifies |
| ---------------------------------- | ---------------------------------- | --------------------------- | | -------------------- | -------------------- | --------------------------- |
| `ASSERT_PRED1(pred1, val1);` | `EXPECT_PRED1(pred1, val1);` | `pred1(val1)` is true | | `ASSERT_PRED1(pred1, | `EXPECT_PRED1(pred1, | `pred1(val1)` is true |
| `ASSERT_PRED2(pred2, val1, val2);` | `EXPECT_PRED2(pred2, val1, val2);` | `pred2(val1, val2)` is true | : val1);` : val1);` : :
| `...` | `...` | ... | | `ASSERT_PRED2(pred2, | `EXPECT_PRED2(pred2, | `pred2(val1, val2)` is true |
: val1, val2);` : val1, val2);` : :
| `...` | `...` | ... |
In the above, `predn` is an `n`-ary predicate function or functor, where `val1`, In the above, `predn` is an `n`-ary predicate function or functor, where `val1`,
`val2`, ..., and `valn` are its arguments. The assertion succeeds if the `val2`, ..., and `valn` are its arguments. The assertion succeeds if the
@ -337,22 +340,23 @@ want to learn more, see
#### Floating-Point Macros #### Floating-Point Macros
| Fatal assertion | Nonfatal assertion | Verifies | | Fatal assertion | Nonfatal assertion | Verifies |
| ------------------------------- | ------------------------------ | ---------------------------------------- | | ----------------------- | ----------------------- | ----------------------- |
| `ASSERT_FLOAT_EQ(val1, val2);` | `EXPECT_FLOAT_EQ(val1,val2);` | the two `float` values are almost equal | | `ASSERT_FLOAT_EQ(val1, | `EXPECT_FLOAT_EQ(val1, | the two `float` values |
| `ASSERT_DOUBLE_EQ(val1, val2);` | `EXPECT_DOUBLE_EQ(val1, val2);`| the two `double` values are almost equal | : val2);` : val2);` : are almost equal :
| `ASSERT_DOUBLE_EQ(val1, | `EXPECT_DOUBLE_EQ(val1, | the two `double` values |
: val2);` : val2);` : are almost equal :
By "almost equal" we mean the values are within 4 ULP's from each other. By "almost equal" we mean the values are within 4 ULP's from each other.
NOTE: `CHECK_DOUBLE_EQ()` in `base/logging.h` uses a fixed absolute error bound,
so its result may differ from that of the googletest macros. That macro is
unsafe and has been deprecated. Please don't use it any more.
The following assertions allow you to choose the acceptable error bound: The following assertions allow you to choose the acceptable error bound:
| Fatal assertion | Nonfatal assertion | Verifies | | Fatal assertion | Nonfatal assertion | Verifies |
| ------------------------------------- | ------------------------------------- | ------------------------- | | ------------------ | ------------------------ | ------------------------- |
| `ASSERT_NEAR(val1, val2, abs_error);` | `EXPECT_NEAR(val1, val2, abs_error);` | the difference between `val1` and `val2` doesn't exceed the given absolute error | | `ASSERT_NEAR(val1, | `EXPECT_NEAR(val1, val2, | the difference between |
: val2, abs_error);` : abs_error);` : `val1` and `val2` doesn't :
: : : exceed the given absolute :
: : : error :
**Availability**: Linux, Windows, Mac. **Availability**: Linux, Windows, Mac.

26
googletest/docs/primer.md
View File

@ -193,8 +193,7 @@ objects, you should use `ASSERT_EQ`.
When doing pointer comparisons use `*_EQ(ptr, nullptr)` and `*_NE(ptr, nullptr)` When doing pointer comparisons use `*_EQ(ptr, nullptr)` and `*_NE(ptr, nullptr)`
instead of `*_EQ(ptr, NULL)` and `*_NE(ptr, NULL)`. This is because `nullptr` is instead of `*_EQ(ptr, NULL)` and `*_NE(ptr, NULL)`. This is because `nullptr` is
typed while `NULL` is not. See [FAQ](faq.md#why-does-googletest-support-expect_eqnull-ptr-and-assert_eqnull-ptr-but-not-expect_nenull-ptr-and-assert_nenull-ptr) typed while `NULL` is not. See [FAQ](faq.md)for more details.
for more details.
If you're working with floating point numbers, you may want to use the floating If you're working with floating point numbers, you may want to use the floating
point variations of some of these macros in order to avoid problems caused by point variations of some of these macros in order to avoid problems caused by
@ -295,8 +294,8 @@ should be in the same test suite; in other words, the first argument to their
suite `FactorialTest`. suite `FactorialTest`.
When naming your test suites and tests, you should follow the same convention as When naming your test suites and tests, you should follow the same convention as
for [naming functions and for
classes](https://google.github.io/styleguide/cppguide.html#Function_Names). [naming functions and classes](https://google.github.io/styleguide/cppguide.html#Function_Names).
**Availability**: Linux, Windows, Mac. **Availability**: Linux, Windows, Mac.
@ -318,7 +317,7 @@ To create a fixture:
1. If necessary, write a destructor or `TearDown()` function to release any 1. If necessary, write a destructor or `TearDown()` function to release any
resources you allocated in `SetUp()` . To learn when you should use the resources you allocated in `SetUp()` . To learn when you should use the
constructor/destructor and when you should use `SetUp()/TearDown()`, read constructor/destructor and when you should use `SetUp()/TearDown()`, read
this [FAQ](faq.md#should-i-use-the-constructordestructor-of-the-test-fixture-or-setupteardown) entry. the [FAQ](faq.md).
1. If needed, define subroutines for your tests to share. 1. If needed, define subroutines for your tests to share.
When using a fixture, use `TEST_F()` instead of `TEST()` as it allows you to When using a fixture, use `TEST_F()` instead of `TEST()` as it allows you to
@ -432,7 +431,6 @@ When these tests run, the following happens:
**Availability**: Linux, Windows, Mac. **Availability**: Linux, Windows, Mac.
## Invoking the Tests ## Invoking the Tests
`TEST()` and `TEST_F()` implicitly register their tests with googletest. So, `TEST()` and `TEST_F()` implicitly register their tests with googletest. So,
@ -446,7 +444,7 @@ different test suites, or even different source files.
When invoked, the `RUN_ALL_TESTS()` macro: When invoked, the `RUN_ALL_TESTS()` macro:
1. Saves the state of all googletest flags * Saves the state of all googletest flags
* Creates a test fixture object for the first test. * Creates a test fixture object for the first test.
@ -458,7 +456,7 @@ When invoked, the `RUN_ALL_TESTS()` macro:
* Deletes the fixture. * Deletes the fixture.
* Restores the state of all googletest flags * Restores the state of all all googletest flags
* Repeats the above steps for the next test, until all tests have run. * Repeats the above steps for the next test, until all tests have run.
@ -471,15 +469,17 @@ If a fatal failure happens the subsequent steps will be skipped.
> return the value of `RUN_ALL_TESTS()`. > return the value of `RUN_ALL_TESTS()`.
> >
> Also, you should call `RUN_ALL_TESTS()` only **once**. Calling it more than > Also, you should call `RUN_ALL_TESTS()` only **once**. Calling it more than
> once conflicts with some advanced googletest features (e.g. thread-safe [death > once conflicts with some advanced googletest features (e.g. thread-safe
> tests](advanced.md#death-tests)) and thus is not supported. > [death tests](advanced.md#death-tests)) and thus is not supported.
**Availability**: Linux, Windows, Mac. **Availability**: Linux, Windows, Mac.
## Writing the main() Function ## Writing the main() Function
Write your own main() function, which should Write your own main() function, which should return the value of
return the value of `RUN_ALL_TESTS()` `RUN_ALL_TESTS()`
You can start from this boilerplate:
```c++ ```c++
#include "this/package/foo.h" #include "this/package/foo.h"
@ -538,7 +538,6 @@ int main(int argc, char **argv) {
} }
``` ```
The `::testing::InitGoogleTest()` function parses the command line for The `::testing::InitGoogleTest()` function parses the command line for
googletest flags, and removes all recognized flags. This allows the user to googletest flags, and removes all recognized flags. This allows the user to
control a test program's behavior via various flags, which we'll cover in control a test program's behavior via various flags, which we'll cover in
@ -555,7 +554,6 @@ gtest\_main library and you are good to go.
NOTE: `ParseGUnitFlags()` is deprecated in favor of `InitGoogleTest()`. NOTE: `ParseGUnitFlags()` is deprecated in favor of `InitGoogleTest()`.
## Known Limitations ## Known Limitations
* Google Test is designed to be thread-safe. The implementation is thread-safe * Google Test is designed to be thread-safe. The implementation is thread-safe