What does linking GoogleTest's gtest_main library give a test binary, and what must a hand-written main() do instead?
answer
- a ready-made main function
- initialise, then run all
- flags are consumed from argv
- return the runner's result
basics
~20 sgtest_main supplies a main() that calls testing::InitGoogleTest(&argc, argv) and returns RUN_ALL_TESTS(). A hand-written main must do the same: initialise first so --gtest_* flags are parsed, then return RUN_ALL_TESTS()'s result so failures reach the exit code.
solid answer
~40 s`gtest_main` (CMake target `GTest::gtest_main`) is a small library whose `main()` prints `Running main() from` and the path of `gtest_main.cc`, calls `testing::InitGoogleTest(&argc, argv)` and returns `RUN_ALL_TESTS()`. Link it when you need nothing special at start-up. Write your own `main` when you must parse your own options, install a global `Environment` or a custom listener, or initialise a framework first. It must call `InitGoogleTest` **before** `RUN_ALL_TESTS()`: that parses `--gtest_*` flags and **removes** them from `argv`, leaving your own arguments. It must **return** the value of `RUN_ALL_TESTS()` (0 when every test passed, 1 otherwise), which GoogleTest 1.18 declares `[[nodiscard]]`, and call it only once. With GoogleMock, `gmock_main` calls `InitGoogleMock()`, which also initialises GoogleTest and parses `--gmock_*` flags. GoogleTest 1.18 also refuses to compile below C++17.
code
cpp · 13 lines#include <gtest/gtest.h>
#include <cstdio>
static int calls = 0; // one process: survives between --gtest_repeat iterations
TEST(Flaky, FailsFirstTime) { ++calls; EXPECT_NE(calls, 1); }
TEST(Flaky, AlwaysPasses) { SUCCEED(); }
TEST(Other, Passes) { SUCCEED(); }
int main(int argc, char** argv) {
testing::InitGoogleTest(&argc, argv); // parses and removes --gtest_* flags
for (int i = 0; i < argc; ++i) std::printf("argv[%d]=%s\n", i, argv[i]);
return RUN_ALL_TESTS(); // 0 if every test passed, 1 otherwise
}go deeper
Recall that gtest_main provides main, and that a custom main calls InitGoogleTest and then returns RUN_ALL_TESTS().
Explain what InitGoogleTest does to argc and argv, why the exit code matters to CI, and when gmock_main is the right library.
Know the reasons to own main, such as global environments, listeners and framework start-up, and diagnose a binary whose flags are silently ignored.
Decide whether the codebase standardises on gtest_main or one shared custom main, and plan the move to C++17 that GoogleTest 1.17 forced.
## What a GoogleTest binary needs at start-up A GoogleTest program is an ordinary executable. The `TEST`, `TEST_F` and `TEST_P` macros only **register** tests in static tables; something still has to parse the command line and run them. That is the job of two calls in `main()`: 1. `testing::InitGoogleTest(&argc, argv)` reads the `--gtest_*` flags (and the matching `GTEST_*` environment variables), stores them, and removes the recognised flags from `argv`; 2. `RUN_ALL_TESTS()` runs every selected test and returns `0` if all passed, `1` otherwise. ## What `gtest_main` gives you `gtest_main` is a separate library built with GoogleTest, linked as `-lgtest_main` or through CMake's imported target `GTest::gtest_main`. Its whole `main()` is: ```cpp int main(int argc, char **argv) { printf("Running main() from %s\n", __FILE__); testing::InitGoogleTest(&argc, argv); return RUN_ALL_TESTS(); } ``` The first line of a test run, `Running main() from` followed by the path of `gtest_main.cc`, tells you which `main` you got. The mocking library has its twin, `gmock_main`, which calls `testing::InitGoogleMock(&argc, argv)` instead; that call initialises GoogleTest too, so a GoogleMock binary never needs both. ## Writing your own `main` There are good reasons to own `main`: - the binary takes its own options, such as a path to fixture data; - a global `testing::Environment` must be registered with `AddGlobalTestEnvironment` before the run; - a custom event listener should replace or extend the console printer; - a framework, a logging system or a GPU context must be initialised before any test runs. The rules for a correct one: | Rule | Why | |---|---| | Call `InitGoogleTest` before `RUN_ALL_TESTS()` | otherwise `--gtest_filter`, `--gtest_repeat` and the rest are ignored, and the run ends with an `IMPORTANT NOTICE - DO NOT IGNORE` message calling the program invalid | | Parse your own flags **after** `InitGoogleTest` | it strips the `--gtest_*` flags, so your parser sees only your arguments; the example prints `argv[1]=--my_flag` and nothing else | | `return RUN_ALL_TESTS();` | CI decides pass or fail from the exit code; GoogleTest 1.18 declares the function `[[nodiscard]]`, so clang warns `ignoring return value of function declared with 'nodiscard' attribute` | | Call `RUN_ALL_TESTS()` once | the header says so: it tears down and deletes installed environments | | Use `InitGoogleMock` when the binary uses mocks | `InitGoogleTest` leaves `--gmock_*` flags such as `--gmock_default_mock_behavior` unparsed in `argv` | ## The language-standard floor GoogleTest 1.17 and later require **C++17**. In 1.18 the check is a hard `#error` in `gtest-port.h`: building with `-std=c++14` stops with `error: C++ versions less than C++17 are not supported.` before anything else. The CMake quickstart therefore sets `CMAKE_CXX_STANDARD 17` and `CMAKE_CXX_STANDARD_REQUIRED ON` before adding GoogleTest. A project pinned to C++14 must stay on an older GoogleTest release. ## Common mistakes - **Two `main` functions.** Linking `gtest_main` and also defining `main` in a test file is a trap: with static libraries the linker may quietly take yours, which hides which one runs. Pick one. - **Returning 0 unconditionally.** `RUN_ALL_TESTS(); return 0;` turns every failing build green. - **Expecting your parser to see `--gtest_filter`.** It is gone from `argv` once `InitGoogleTest` returns. - **Forgetting the exit code under a wrapper script.** A shell pipeline such as `./tests | tee log` reports `tee`'s status unless `pipefail` is set. The example's run shows the full loop: `--my_flag` survives, the `--gtest_filter` is applied (`Note: Google Test filter = Flaky.*`), one test fails, and the process exits with status 1. ## Wiring the choice in CMake CMake's `FindGTest` module and GoogleTest's own package both provide imported targets, and the choice of `main` is a choice of target: ```cmake # GoogleTest supplies main() target_link_libraries(flaky_test PRIVATE GTest::gtest_main) # the test sources supply main() target_link_libraries(flaky_runner PRIVATE GTest::gtest) # mocks plus a supplied main() that calls InitGoogleMock target_link_libraries(thermostat_test PRIVATE GTest::gmock_main) ``` The `FindGTest` documentation states the rule directly: link `GTest::gtest_main` only if GoogleTest should supply `main()`, and link only `GTest::gtest` when the project brings its own. Mixing them up is the usual source of the two-`main` confusion above. A team that needs the same start-up code in many test binaries can put one custom `main` in a small shared library and link that instead of `gtest_main`, so every binary initialises the same way.
- A test binary prints IMPORTANT NOTICE - DO NOT IGNORE at the end of the run. What is wrong?Its `main()` called `RUN_ALL_TESTS()` without calling `testing::InitGoogleTest()` first. The run still happens, but command-line flags such as `--gtest_filter` were never parsed, and GoogleTest warns that it may start enforcing initialisation. Add `testing::InitGoogleTest(&argc, argv);` (or `InitGoogleMock`) before the run.
- Your binary uses GoogleMock and a custom main. Which initialiser should it call?`testing::InitGoogleMock(&argc, argv)`. It initialises GoogleTest as well, so `--gtest_*` flags still work, and it additionally parses `--gmock_*` flags such as `--gmock_verbose` and `--gmock_default_mock_behavior`. Calling only `InitGoogleTest` leaves those flags in `argv`, unapplied.
- Returning 0 from main after calling RUN_ALL_TESTS()
- Calling RUN_ALL_TESTS() without InitGoogleTest() first
- Expecting a custom option parser to see --gtest_filter after initialisation
- Linking gtest_main and also defining main in a test file
- Thinking GoogleTest 1.18 still builds in C++14 mode
Assumes GoogleTest 1.18: RUN_ALL_TESTS() is declared [[nodiscard]] and gtest-port.h rejects language modes older than C++17.