diff options
Diffstat (limited to 'googletest/docs')
-rw-r--r-- | googletest/docs/advanced.md | 41 | ||||
-rw-r--r-- | googletest/docs/pkgconfig.md | 71 |
2 files changed, 34 insertions, 78 deletions
diff --git a/googletest/docs/advanced.md b/googletest/docs/advanced.md index 8ce1f3e..7ca40fe 100644 --- a/googletest/docs/advanced.md +++ b/googletest/docs/advanced.md @@ -401,7 +401,7 @@ alone with them. For a list of matchers gMock provides, read 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 @@ -638,6 +638,7 @@ Fatal assertion | Nonfatal assertion ------------------------------------------------ | ------------------------------------------------ | -------- `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, @@ -862,7 +863,7 @@ restored afterwards, so you need not do that yourself. For example: ```c++ int main(int argc, char** argv) { - InitGoogle(argv[0], &argc, &argv, true); + ::testing::InitGoogleTest(&argc, argv); ::testing::FLAGS_gtest_death_test_style = "fast"; return RUN_ALL_TESTS(); } @@ -1775,7 +1776,7 @@ In frameworks that report a failure by throwing an exception, you could catch 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++ @@ -1923,8 +1924,8 @@ To obtain a `TestInfo` object for the currently running test, call ``` `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 @@ -2115,6 +2116,15 @@ For example: 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 @@ -2251,6 +2261,12 @@ 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`. +#### 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 @@ -2272,8 +2288,7 @@ environment variable to `0`. 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 @@ -2552,6 +2567,18 @@ IMPORTANT: The exact format of the JSON document is subject to change. ### 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 diff --git a/googletest/docs/pkgconfig.md b/googletest/docs/pkgconfig.md index 117166c..b9bef3f 100644 --- a/googletest/docs/pkgconfig.md +++ b/googletest/docs/pkgconfig.md @@ -45,77 +45,6 @@ splitting the pkg-config `Cflags` variable into include dirs and macros for goes for using `_LDFLAGS` over the more commonplace `_LIBRARIES`, which happens to discard `-L` flags and `-pthread`. -### Autotools - -Finding GoogleTest in Autoconf and using it from Automake is also fairly easy: - -In your `configure.ac`: - -``` -AC_PREREQ([2.69]) -AC_INIT([my_gtest_pkgconfig], [0.0.1]) -AC_CONFIG_SRCDIR([samples/sample3_unittest.cc]) -AC_PROG_CXX - -PKG_CHECK_MODULES([GTEST], [gtest_main]) - -AM_INIT_AUTOMAKE([foreign subdir-objects]) -AC_CONFIG_FILES([Makefile]) -AC_OUTPUT -``` - -and in your `Makefile.am`: - -``` -check_PROGRAMS = testapp -TESTS = $(check_PROGRAMS) - -testapp_SOURCES = samples/sample3_unittest.cc -testapp_CXXFLAGS = $(GTEST_CFLAGS) -testapp_LDADD = $(GTEST_LIBS) -``` - -### Meson - -Meson natively uses pkgconfig to query dependencies: - -``` -project('my_gtest_pkgconfig', 'cpp', version : '0.0.1') - -gtest_dep = dependency('gtest_main') - -testapp = executable( - 'testapp', - files(['samples/sample3_unittest.cc']), - dependencies : gtest_dep, - install : false) - -test('first_and_only_test', testapp) -``` - -### Plain Makefiles - -Since `pkg-config` is a small Unix command-line utility, it can be used in -handwritten `Makefile`s too: - -```makefile -GTEST_CFLAGS = `pkg-config --cflags gtest_main` -GTEST_LIBS = `pkg-config --libs gtest_main` - -.PHONY: tests all - -tests: all - ./testapp - -all: testapp - -testapp: testapp.o - $(CXX) $(CXXFLAGS) $(LDFLAGS) $< -o $@ $(GTEST_LIBS) - -testapp.o: samples/sample3_unittest.cc - $(CXX) $(CPPFLAGS) $(CXXFLAGS) $< -c -o $@ $(GTEST_CFLAGS) -``` - ### Help! pkg-config can't find GoogleTest! Let's say you have a `CMakeLists.txt` along the lines of the one in this |