diff options
Diffstat (limited to 'docs/advanced.md')
| -rw-r--r-- | docs/advanced.md | 166 |
1 files changed, 101 insertions, 65 deletions
diff --git a/docs/advanced.md b/docs/advanced.md index 7e998cc..d703a7b 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -349,7 +349,8 @@ void AbslStringify(Sink& sink, EnumWithStringify e) { {: .callout .note} Note: `AbslStringify()` utilizes a generic "sink" buffer to construct its string. For more information about supported operations on `AbslStringify()`'s -sink, see go/abslstringify. +sink, see +[the `AbslStringify()` documentation](https://abseil.io/docs/cpp/guides/abslstringify). `AbslStringify()` can also use `absl::StrFormat`'s catch-all `%v` type specifier within its own format strings to perform type deduction. `Point` above could be @@ -403,7 +404,53 @@ EXPECT_TRUE(IsCorrectPointIntVector(point_ints)) ``` For more details regarding `AbslStringify()` and its integration with other -libraries, see go/abslstringify. +libraries, see +[the documentation](https://abseil.io/docs/cpp/guides/abslstringify). + +## Regular Expression Syntax + +When built with Bazel and using Abseil, GoogleTest uses the +[RE2](https://github.com/google/re2/wiki/Syntax) syntax. Otherwise, for POSIX +systems (Linux, Cygwin, Mac), GoogleTest uses the +[POSIX extended regular expression](https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html#tag_09_04) +syntax. To learn about POSIX syntax, you may want to read this +[Wikipedia entry](https://en.wikipedia.org/wiki/Regular_expression#POSIX_extended). + +On Windows, GoogleTest uses its own simple regular expression implementation. It +lacks many features. For example, we don't support union (`"x|y"`), grouping +(`"(xy)"`), brackets (`"[xy]"`), and repetition count (`"x{5,7}"`), among +others. Below is what we do support (`A` denotes a literal character, period +(`.`), or a single `\\ ` escape sequence; `x` and `y` denote regular +expressions.): + +Expression | Meaning +---------- | -------------------------------------------------------------- +`c` | matches any literal character `c` +`\\d` | matches any decimal digit +`\\D` | matches any character that's not a decimal digit +`\\f` | matches `\f` +`\\n` | matches `\n` +`\\r` | matches `\r` +`\\s` | matches any ASCII whitespace, including `\n` +`\\S` | matches any character that's not a whitespace +`\\t` | matches `\t` +`\\v` | matches `\v` +`\\w` | matches any letter, `_`, or decimal digit +`\\W` | matches any character that `\\w` doesn't match +`\\c` | matches any literal character `c`, which must be a punctuation +`.` | matches any single character except `\n` +`A?` | matches 0 or 1 occurrences of `A` +`A*` | matches 0 or many occurrences of `A` +`A+` | matches 1 or many occurrences of `A` +`^` | matches the beginning of a string (not that of each line) +`$` | matches the end of a string (not that of each line) +`xy` | matches `x` followed by `y` + +To help you determine which capability is available on your system, GoogleTest +defines macros to govern which regular expression it is using. The macros are: +`GTEST_USES_SIMPLE_RE=1` or `GTEST_USES_POSIX_RE=1`. If you want your death +tests to work in all cases, you can either `#if` on these macros or use the more +limited syntax only. ## Death Tests @@ -416,7 +463,7 @@ corruption, security holes, or worse. Hence it is vitally important to test that such assertion statements work as expected. Since these precondition checks cause the processes to die, we call such tests -_death tests_. More generally, any test that checks that a program terminates +*death tests*. More generally, any test that checks that a program terminates (except by throwing an exception) in an expected fashion is also a death test. Note that if a piece of code throws an exception, we don't consider it "death" @@ -462,6 +509,12 @@ verifies that: exit with exit code 0, and * calling `KillProcess()` kills the process with signal `SIGKILL`. +{: .callout .warning} +Warning: If your death test contains mocks and is expecting a specific exit +code, then you must allow the mock objects to be leaked via `Mock::AllowLeak`. +This is because the mock leak detector will exit with its own error code if it +detects a leak. + The test function body may contain other assertions and statements as well, if necessary. @@ -503,51 +556,6 @@ TEST_F(FooDeathTest, DoesThat) { } ``` -### Regular Expression Syntax - -When built with Bazel and using Abseil, GoogleTest uses the -[RE2](https://github.com/google/re2/wiki/Syntax) syntax. Otherwise, for POSIX -systems (Linux, Cygwin, Mac), GoogleTest uses the -[POSIX extended regular expression](https://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html#tag_09_04) -syntax. To learn about POSIX syntax, you may want to read this -[Wikipedia entry](https://en.wikipedia.org/wiki/Regular_expression#POSIX_extended). - -On Windows, GoogleTest uses its own simple regular expression implementation. It -lacks many features. For example, we don't support union (`"x|y"`), grouping -(`"(xy)"`), brackets (`"[xy]"`), and repetition count (`"x{5,7}"`), among -others. Below is what we do support (`A` denotes a literal character, period -(`.`), or a single `\\ ` escape sequence; `x` and `y` denote regular -expressions.): - -Expression | Meaning ----------- | -------------------------------------------------------------- -`c` | matches any literal character `c` -`\\d` | matches any decimal digit -`\\D` | matches any character that's not a decimal digit -`\\f` | matches `\f` -`\\n` | matches `\n` -`\\r` | matches `\r` -`\\s` | matches any ASCII whitespace, including `\n` -`\\S` | matches any character that's not a whitespace -`\\t` | matches `\t` -`\\v` | matches `\v` -`\\w` | matches any letter, `_`, or decimal digit -`\\W` | matches any character that `\\w` doesn't match -`\\c` | matches any literal character `c`, which must be a punctuation -`.` | matches any single character except `\n` -`A?` | matches 0 or 1 occurrences of `A` -`A*` | matches 0 or many occurrences of `A` -`A+` | matches 1 or many occurrences of `A` -`^` | matches the beginning of a string (not that of each line) -`$` | matches the end of a string (not that of each line) -`xy` | matches `x` followed by `y` - -To help you determine which capability is available on your system, GoogleTest -defines macros to govern which regular expression it is using. The macros are: -`GTEST_USES_SIMPLE_RE=1` or `GTEST_USES_POSIX_RE=1`. If you want your death -tests to work in all cases, you can either `#if` on these macros or use the more -limited syntax only. - ### How It Works See [Death Assertions](reference/assertions.md#death) in the Assertions @@ -727,7 +735,7 @@ Some tips on using `SCOPED_TRACE`: ### Propagating Fatal Failures A common pitfall when using `ASSERT_*` and `FAIL*` is not understanding that -when they fail they only abort the _current function_, not the entire test. For +when they fail they only abort the *current function*, not the entire test. For example, the following test will segfault: ```c++ @@ -1442,17 +1450,19 @@ are two cases to consider: 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 - this in production code!) - - However, a better approach is to move the private code into the - `foo::internal` namespace, where `foo` is the namespace your project - normally uses, and put the private declarations in a `*-internal.h` file. - Your production `.cc` files and your tests are allowed to include this - internal header, but your clients are not. This way, you can fully test your - internal implementation without leaking it to your clients. + are only visible within the same translation unit. To test them, move the + private code into the `foo::internal` namespace, where `foo` is the + namespace your project normally uses, and put the private declarations in a + `*-internal.h` file. Your production `.cc` files and your tests are allowed + to include this internal header, but your clients are not. This way, you can + fully test your internal implementation without leaking it to your clients. + +{: .callout .note} +NOTE: It is also technically *possible* to `#include` the entire `.cc` file +being tested in your `*_test.cc` file to test static functions and +definitions/declarations in an unnamed namespace. However, this technique is +**not recommended** by this documentation and it is only presented here for the +sake of completeness. * Private class members are only accessible from within the class or by friends. To access a class' private members, you can declare your test @@ -1465,10 +1475,7 @@ To test them, we use the following special techniques: Another way to test private members is to refactor them into an implementation class, which is then declared in a `*-internal.h` file. Your - clients aren't allowed to include this header but your tests can. Such is - called the - [Pimpl](https://www.gamedev.net/articles/programming/general-and-gameplay-programming/the-c-pimpl-r1794/) - (Private Implementation) idiom. + clients aren't allowed to include this header but your tests can. Or, you can declare an individual test as a friend of your class by adding this line in the class body: @@ -1923,6 +1930,35 @@ the `--gtest_also_run_disabled_tests` flag or set the You can combine this with the `--gtest_filter` flag to further select which disabled tests to run. +### Enforcing Having At Least One Test Case + +A not uncommon programmer mistake is to write a test program that has no test +case linked in. This can happen, for example, when you put test case definitions +in a library and the library is not marked as "always link". + +To catch such mistakes, run the test program with the +`--gtest_fail_if_no_test_linked` flag or set the `GTEST_FAIL_IF_NO_TEST_LINKED` +environment variable to a value other than `0`. Now the program will fail if no +test case is linked in. + +Note that *any* test case linked in makes the program valid for the purpose of +this check. In particular, even a disabled test case suffices. + +### Enforcing Running At Least One Test Case + +In addition to enforcing that tests are defined in the binary with +`--gtest_fail_if_no_test_linked`, it is also possible to enforce that a test +case was actually executed to ensure that resources are not consumed by tests +that do nothing. + +To catch such optimization opportunities, run the test program with the +`--gtest_fail_if_no_test_selected` flag or set the +`GTEST_FAIL_IF_NO_TEST_SELECTED` environment variable to a value other than `0`. + +A test is considered selected if it begins to run, even if it is later skipped +via `GTEST_SKIP`. Thus, `DISABLED` tests do not count as selected and neither do +tests that are not matched by `--gtest_filter`. + ### Repeating the Tests Once in a while you'll run into a test whose result is hit-or-miss. Perhaps it @@ -2382,7 +2418,7 @@ IMPORTANT: The exact format of the JSON document is subject to change. #### Detecting Test Premature Exit -Google Test implements the _premature-exit-file_ protocol for test runners to +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 |