skip to content

Test Runner Flags

gtest_main supplies main, InitGoogleTest parses flags, and --gtest_filter, repeat and shuffle find flaky tests. Interviewers ask how the suite reaches CTest and CI reports.

on this pageshow

explore

questions

5

What does linking GoogleTest's gtest_main library give a test binary, and what must a hand-written main() do instead?

level: juniorimportance: must knowfreq 70%

answer

  1. a ready-made main function
  2. initialise, then run all
  3. flags are consumed from argv
  4. return the runner's result

basics

~20 s

gtest_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
cpp
#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

for a junior

Recall that gtest_main provides main, and that a custom main calls InitGoogleTest and then returns RUN_ALL_TESTS().

for a middle

Explain what InitGoogleTest does to argc and argv, why the exit code matters to CI, and when gmock_main is the right library.

for a senior

Know the reasons to own main, such as global environments, listeners and framework start-up, and diagnose a binary whose flags are silently ignored.

for a principal

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.

open as a page

How does GoogleTest's --gtest_filter flag select tests, including negative patterns and the names of parameterized tests?

level: middleimportance: must knowfreq 65%

basics

~20 s

--gtest_filter takes colon-separated wildcard patterns matched against full names like Suite.Test; an optional dash introduces patterns to exclude. * and ? are the only wildcards. Parameterized tests carry their prefix and index, as in Small/Sizes.Fits/0.

open as a page

How do you make a GoogleTest binary write a JUnit-style XML report, and what does the report hold after a --gtest_repeat run?

level: middleimportance: should knowfreq 50%

basics

~20 s

Pass --gtest_output=xml:path (or set GTEST_OUTPUT); plain xml writes test_detail.xml, and a path ending in / names a directory where the file is named after the binary. With --gtest_repeat the file is rewritten after every iteration, so it shows only the last one.

open as a page

In CMake's GoogleTest module, how do gtest_discover_tests and gtest_add_tests differ, and when does each one find the tests?

level: seniorimportance: should knowfreq 45%

basics

~20 s

gtest_add_tests finds tests at configure time by scanning sources with a regular expression, so a parameterized test stays one wildcard entry. gtest_discover_tests runs the built binary with --gtest_list_tests after the build or before testing, registering every instantiation.

open as a page

A CI job must run a flaky GoogleTest subset 100 times in random order. Which flags do that, and how do you replay the exact order of a failing iteration?

level: seniorimportance: should knowfreq 50%

basics

~10 s

Run with --gtest_filter=<subset> --gtest_repeat=100 --gtest_shuffle. Each iteration prints its seed, and the seed rises by one per iteration. Replay a failure with the same filter, --gtest_shuffle and --gtest_random_seed set to that iteration's printed seed.

open as a page