diff options
Diffstat (limited to 'googletest/docs/advanced.md')
| -rw-r--r-- | googletest/docs/advanced.md | 132 |
1 files changed, 58 insertions, 74 deletions
diff --git a/googletest/docs/advanced.md b/googletest/docs/advanced.md index 6883784d..8065d196 100644 --- a/googletest/docs/advanced.md +++ b/googletest/docs/advanced.md @@ -3,7 +3,7 @@ ## Introduction -Now that you have read the [googletest Primer](primer) and learned how to write +Now that you have read the [googletest Primer](primer.md) and learned how to write tests using googletest, it's time to learn some new tricks. This document will show you more assertions as well as how to construct complex failure messages, propagate fatal failures, reuse and speed up your test fixtures, and use various @@ -103,13 +103,11 @@ 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 assertion* to get the function arguments printed for free: -| Fatal assertion | Nonfatal assertion | Verifies | -| -------------------- | -------------------- | --------------------------- | -| `ASSERT_PRED1(pred1, | `EXPECT_PRED1(pred1, | `pred1(val1)` is true | -: val1);` : val1);` : : -| `ASSERT_PRED2(pred2, | `EXPECT_PRED2(pred2, | `pred2(val1, val2)` is true | -: val1, val2);` : val1, val2);` : : -| `...` | `...` | ... | +| Fatal assertion | Nonfatal assertion | Verifies | +| ---------------------------------- | ---------------------------------- | --------------------------- | +| `ASSERT_PRED1(pred1, val1);` | `EXPECT_PRED1(pred1, val1);` | `pred1(val1)` is true | +| `ASSERT_PRED2(pred2, val1, val2);` | `EXPECT_PRED2(pred2, val1, val2);` | `pred2(val1, val2)` is true | +| `...` | `...` | ... | 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 @@ -120,7 +118,7 @@ either case, the arguments are evaluated exactly once. Here's an example. Given ```c++ -// Returns true iff m and n have no common divisors except 1. +// Returns true if m and n have no common divisors except 1. bool MutuallyPrime(int m, int n) { ... } const int a = 3; @@ -152,9 +150,9 @@ c is 10 > > 1. If you see a compiler error "no matching function to call" when using > `ASSERT_PRED*` or `EXPECT_PRED*`, please see -> [this](faq#OverloadedPredicate) for how to resolve it. +> [this](faq.md#OverloadedPredicate) for how to resolve it. > 1. Currently we only provide predicate assertions of arity <= 5. If you need -> a higher-arity assertion, let [us](http://g/opensource-gtest) know. +> a higher-arity assertion, let [us](https://github.com/google/googletest/issues) know. **Availability**: Linux, Windows, Mac. @@ -339,12 +337,10 @@ want to learn more, see #### Floating-Point Macros -| Fatal assertion | Nonfatal assertion | Verifies | -| ----------------------- | ----------------------- | ----------------------- | -| `ASSERT_FLOAT_EQ(val1, | `EXPECT_FLOAT_EQ(val1, | the two `float` values | -: val2);` : val2);` : are almost equal : -| `ASSERT_DOUBLE_EQ(val1, | `EXPECT_DOUBLE_EQ(val1, | the two `double` values | -: val2);` : val2);` : are almost equal : +| Fatal assertion | Nonfatal assertion | Verifies | +| ------------------------------- | ------------------------------ | ---------------------------------------- | +| `ASSERT_FLOAT_EQ(val1, val2);` | `EXPECT_FLOAT_EQ(val1,val2);` | the two `float` values are almost equal | +| `ASSERT_DOUBLE_EQ(val1, val2);` | `EXPECT_DOUBLE_EQ(val1, val2);`| the two `double` values are almost equal | By "almost equal" we mean the values are within 4 ULP's from each other. @@ -354,12 +350,9 @@ unsafe and has been deprecated. Please don't use it any more. The following assertions allow you to choose the acceptable error bound: -| Fatal assertion | Nonfatal assertion | Verifies | -| ------------------ | ------------------------ | ------------------------- | -| `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 : +| 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 | **Availability**: Linux, Windows, Mac. @@ -382,15 +375,14 @@ Verifies that `val1` is less than, or almost equal to, `val2`. You can replace ### Asserting Using gMock Matchers -Google-developed C++ mocking framework [gMock](http://go/gmock) comes with a +Google-developed C++ mocking framework [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: -| Fatal assertion | Nonfatal assertion | Verifies | -| ------------------- | ------------------------------ | --------------------- | -| `ASSERT_THAT(value, | `EXPECT_THAT(value, matcher);` | value matches matcher | -: matcher);` : : : +| Fatal assertion | Nonfatal assertion | Verifies | +| ------------------------------ | ------------------------------ | --------------------- | +| `ASSERT_THAT(value, matcher);` | `EXPECT_THAT(value, matcher);` | value matches matcher | For example, `StartsWith(prefix)` is a matcher that matches a string starting with `prefix`, and you can write: @@ -402,17 +394,17 @@ using ::testing::StartsWith; EXPECT_THAT(Foo(), StartsWith("Hello")); ``` -Read this [recipe](http://go/gmockguide#using-matchers-in-gunit-assertions) in +Read this [recipe](../../googlemock/docs/CookBook.md#using-matchers-in-google-test-assertions) in the gMock Cookbook for more details. gMock has a rich set of matchers. You can do many things googletest cannot do alone with them. For a list of matchers gMock provides, read -[this](http://go/gmockguide#using-matchers). Especially useful among them are -some [protocol buffer matchers](http://go/protomatchers). It's easy to write -your [own matchers](http://go/gmockguide#NewMatchers) too. +[this](../../googlemock/docs/CookBook.md#using-matchers). Especially useful among them are +some [protocol buffer matchers](https://github.com/google/nucleus/blob/master/nucleus/testing/protocol-buffer-matchers.h). It's easy to write +your [own matchers](../../googlemock/docs/CookBook.md#writing-new-matchers-quickly) too. For example, you can use gMock's -[EqualsProto](http://cs/#piper///depot/google3/testing/base/public/gmock_utils/protocol-buffer-matchers.h) +[EqualsProto](https://github.com/google/nucleus/blob/master/nucleus/testing/protocol-buffer-matchers.h) to compare protos in your tests: ```c++ @@ -433,7 +425,7 @@ and you're ready to go. (Please read the [previous](#AssertThat) section first if you haven't.) -You can use the gMock [string matchers](http://go/gmockguide#string-matchers) +You can use the gMock [string matchers](../../googlemock/docs/CheatSheet.md#string-matchers) with `EXPECT_THAT()` or `ASSERT_THAT()` to do more string comparison tricks (sub-string, prefix, suffix, regular expression, and etc). For example, @@ -580,7 +572,7 @@ namespace foo { class Bar { // We want googletest to be able to print instances of this. ... // Create a free inline friend function. - friend ::std::ostream& operator<<(::std::ostream& os, const Bar& bar) { + friend std::ostream& operator<<(std::ostream& os, const Bar& bar) { return os << bar.DebugString(); // whatever needed to print bar to os } }; @@ -588,7 +580,7 @@ class Bar { // We want googletest to be able to print instances of this. // If you can't declare the function in the class it's important that the // << operator is defined in the SAME namespace that defines Bar. C++'s look-up // rules rely on that. -::std::ostream& operator<<(::std::ostream& os, const Bar& bar) { +std::ostream& operator<<(std::ostream& os, const Bar& bar) { return os << bar.DebugString(); // whatever needed to print bar to os } @@ -609,7 +601,7 @@ namespace foo { class Bar { ... - friend void PrintTo(const Bar& bar, ::std::ostream* os) { + friend void PrintTo(const Bar& bar, std::ostream* os) { *os << bar.DebugString(); // whatever needed to print bar to os } }; @@ -617,7 +609,7 @@ class Bar { // If you can't declare the function in the class it's important that PrintTo() // is defined in the SAME namespace that defines Bar. C++'s look-up rules rely // on that. -void PrintTo(const Bar& bar, ::std::ostream* os) { +void PrintTo(const Bar& bar, std::ostream* os) { *os << bar.DebugString(); // whatever needed to print bar to os } @@ -657,7 +649,7 @@ _death tests_. More generally, any test that checks that a program terminates Note that if a piece of code throws an exception, we don't consider it "death" for the purpose of death tests, as the caller of the code could catch the exception and avoid the crash. If you want to verify exceptions thrown by your -code, see [Exception Assertions](#ExceptionAssertions). +code, see [Exception Assertions](#exception-assertions). If you want to test `EXPECT_*()/ASSERT_*()` failures in your test code, see Catching Failures @@ -1155,7 +1147,7 @@ test has at least one failure of either kind. In your test code, you can call `RecordProperty("key", value)` to log additional information, where `value` can be either a string or an `int`. The *last* value -recorded for a key will be emitted to the [XML output](#XmlReport) if you +recorded for a key will be emitted to the [XML output](#generating-an-xml-report) if you specify one. For example, the test ```c++ @@ -1396,17 +1388,11 @@ namespace: | Parameter Generator | Behavior | | ---------------------------- | ------------------------------------------- | -| `Range(begin, end [, step])` | Yields values `{begin, begin+step, | -: : begin+step+step, ...}`. The values do not : -: : include `end`. `step` defaults to 1. : +| `Range(begin, end [, step])` | Yields values `{begin, begin+step, begin+step+step, ...}`. The values do not include `end`. `step` defaults to 1. | | `Values(v1, v2, ..., vN)` | Yields values `{v1, v2, ..., vN}`. | -| `ValuesIn(container)` and | Yields values from a C-style array, an | -: `ValuesIn(begin,end)` : STL-style container, or an iterator range : -: : `[begin, end)`. : +| `ValuesIn(container)` and `ValuesIn(begin,end)` | Yields values from a C-style array, an STL-style container, or an iterator range `[begin, end)`. | | `Bool()` | Yields sequence `{false, true}`. | -| `Combine(g1, g2, ..., gN)` | Yields all combinations (Cartesian product) | -: : as std\:\:tuples of the values generated by : -: : the `N` generators. : +| `Combine(g1, g2, ..., gN)` | Yields all combinations (Cartesian product) as std\:\:tuples of the values generated by the `N` generators. | For more details, see the comments at the definitions of these functions. @@ -1438,7 +1424,7 @@ will have these names: * `InstantiationName/FooTest.HasBlahBlah/1` for `"miny"` * `InstantiationName/FooTest.HasBlahBlah/2` for `"moe"` -You can use these names in [`--gtest_filter`](#TestFilter). +You can use these names in [`--gtest_filter`](#running-a-subset-of-the-tests). This statement will instantiate all tests from `FooTest` again, each with parameter values `"cat"` and `"dog"`: @@ -1688,7 +1674,7 @@ To test them, we use the following special techniques: * Both static functions and definitions/declarations in an unnamed namespace are only visible within the same translation unit. To test them, you can `#include` the entire `.cc` file being tested in your `*_test.cc` file. - (#including `.cc` files is not a good way to reuse code - you should not do + (including `.cc` files is not a good way to reuse code - you should not do this in production code!) However, a better approach is to move the private code into the @@ -1726,11 +1712,11 @@ To test them, we use the following special techniques: ```c++ // foo.h -#include "gtest/gtest_prod.h" + #include "gtest/gtest_prod.h" class Foo { ... - private: + private: FRIEND_TEST(FooTest, BarReturnsZeroOnNull); int Bar(void* x); @@ -1779,7 +1765,7 @@ To test them, we use the following special techniques: ``` - ## "Catching" Failures +## "Catching" Failures If you are building a testing utility on top of googletest, you'll want to test your utility. What framework would you use to test it? googletest, of course. @@ -2134,7 +2120,7 @@ $ foo_test --gtest_repeat=1000 --gtest_filter=FooBar.* Repeat the tests whose name matches the filter 1000 times. ``` -If your test program contains [global set-up/tear-down](#GlobalSetUp) code, it +If your test program contains [global set-up/tear-down](#global-set-up-and-tear-down) code, it will be repeated in each iteration as well, as the flakiness may be in it. You can also specify the repeat count by setting the `GTEST_REPEAT` environment variable. @@ -2168,23 +2154,22 @@ random seed and re-shuffle the tests in each iteration. googletest can use colors in its terminal output to make it easier to spot the important information: -... -<span style="color:green">[----------]<span style="color:black"> 1 test from FooTest -<span style="color:green">[ RUN ]<span style="color:black"> FooTest.DoesAbc -<span style="color:green">[ OK ]<span style="color:black"> FooTest.DoesAbc -<span style="color:green">[----------]<span style="color:black"> 2 tests from BarTest -<span style="color:green">[ RUN ]<span style="color:black"> BarTest.HasXyzProperty -<span style="color:green">[ OK ]<span style="color:black"> BarTest.HasXyzProperty -<span style="color:green">[ RUN ]<span style="color:black"> BarTest.ReturnsTrueOnSuccess -... some error messages ... -<span style="color:red">[ FAILED ] <span style="color:black">BarTest.ReturnsTrueOnSuccess -... -<span style="color:green">[==========]<span style="color:black"> 30 tests from 14 test cases ran. -<span style="color:green">[ PASSED ]<span style="color:black"> 28 tests. -<span style="color:red">[ FAILED ]<span style="color:black"> 2 tests, listed below: -<span style="color:red">[ FAILED ]<span style="color:black"> BarTest.ReturnsTrueOnSuccess -<span style="color:red">[ FAILED ]<span style="color:black"> AnotherTest.DoesXyz - +...<br/> +<span style="color:green">[----------]<span style="color:black"> 1 test from FooTest<br/> +<span style="color:green">[ RUN ]<span style="color:black"> FooTest.DoesAbc<br/> +<span style="color:green">[ OK ]<span style="color:black"> FooTest.DoesAbc<br/> +<span style="color:green">[----------]<span style="color:black"> 2 tests from BarTest<br/> +<span style="color:green">[ RUN ]<span style="color:black"> BarTest.HasXyzProperty<br/> +<span style="color:green">[ OK ]<span style="color:black"> BarTest.HasXyzProperty<br/> +<span style="color:green">[ RUN ]<span style="color:black"> BarTest.ReturnsTrueOnSuccess<br/> +... some error messages ...<br/> +<span style="color:red">[ FAILED ] <span style="color:black">BarTest.ReturnsTrueOnSuccess<br/> +...<br/> +<span style="color:green">[==========]<span style="color:black"> 30 tests from 14 test cases ran.<br/> +<span style="color:green">[ PASSED ]<span style="color:black"> 28 tests.<br/> +<span style="color:red">[ FAILED ]<span style="color:black"> 2 tests, listed below:<br/> +<span style="color:red">[ FAILED ]<span style="color:black"> BarTest.ReturnsTrueOnSuccess<br/> +<span style="color:red">[ FAILED ]<span style="color:black"> AnotherTest.DoesXyz<br/> 2 FAILED TESTS You can set the `GTEST_COLOR` environment variable or the `--gtest_color` @@ -2193,8 +2178,7 @@ disable colors, or let googletest decide. When the value is `auto`, googletest 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`. -> -> **Availability**: Linux, Windows, Mac. + **Availability**: Linux, Windows, Mac. #### Suppressing the Elapsed Time |