How to List All Available Tests Without Running Them in GoogleTest

Use the --gtest_list_tests command-line flag to print every test suite and test name without executing any test code.

GoogleTest provides a built-in mechanism to inventory your test suite before execution. This feature is essential for CI pipelines, test selection scripts, and debugging large codebases in the google/googletest repository.

The --gtest_list_tests Command-Line Flag

GoogleTest exposes a boolean flag --gtest_list_tests that instructs the test runner to enumerate all registered tests and exit immediately. When this flag is present, the framework skips the normal test iteration flow entirely, ensuring zero test code executes.

Run this flag with any compiled test binary:

./my_test_binary --gtest_list_tests

The output follows a hierarchical structure:

TestMath.
  HandlesPositiveNumbers
  HandlesNegativeNumbers
TestString.
  IsEmpty
  ContainsSubstring

Each test suite appears on its own line ending with a period, followed by indented test names belonging to that suite.

How It Works Under the Hood

The implementation spans the core headers and source files of the GoogleTest library.

Flag Declaration in gtest-port.h

The flag is declared in googletest/include/gtest/internal/gtest-port.h using the internal macro GTEST_DECLARE_bool_(list_tests) at line 85. This macro registers the boolean variable within GoogleTest's custom flag parsing system, making it available as a command-line option.

Execution Flow in gtest.cc

During initialization, the test runner checks this flag value in googletest/src/gtest.cc (lines 3414-3422). If list_tests is true, the framework invokes the ListTests routine before any test iteration begins. This early return path prevents the UnitTestImpl::RunAllTests() method from entering the execution loop, guaranteeing no test fixtures or test bodies run.

Output Formatting

The actual printing logic resides in PrettyUnitTestResultPrinter::OnTestIterationStart. This method iterates over the registered TestInfo objects collected during the RUN_ALL_TESTS() registration phase. It emits the suite name, then recursively prints each associated test name with two-space indentation, producing the plain-text format suitable for piping into grep, awk, or other shell tools.

Practical Usage Examples

Basic Listing

Build your test binary and list all available tests:

mkdir build && cd build
cmake .. && make
./my_test_binary --gtest_list_tests

Capture to File

Redirect the output for processing in CI scripts:

./my_test_binary --gtest_list_tests > test_inventory.txt

Filtered Listing

Combine with --gtest_filter to preview a subset before running:

./my_test_binary --gtest_filter=TestMath.* --gtest_list_tests

This prints only the tests matching the filter pattern without executing them.

Summary

• Use --gtest_list_tests to generate a complete inventory of your GoogleTest suite without execution overhead.
• The flag is declared in gtest-port.h and processed in gtest.cc via the ListTests function.
• Output formatting is handled by PrettyUnitTestResultPrinter::OnTestIterationStart, producing plain text suitable for automation.
• This flag overrides all other execution parameters and has no corresponding environment variable equivalent.

Frequently Asked Questions

Can I list tests using an environment variable instead of a flag?

No. According to the GoogleTest source code, --gtest_list_tests must be passed as a command-line argument. There is no GTEST_LIST_TESTS environment variable support in the implementation within googletest/src/gtest.cc.

Does --gtest_list_tests execute test fixtures or SetUp/TearDown methods?

No. The framework checks the flag value early in the initialization phase before constructing test objects or invoking any fixture methods. The ListTests routine returns immediately after printing, bypassing the RunAllTests execution loop entirely.

What output format does --gtest_list_tests produce?

The output is plain text where each test suite name ends with a period and appears on its own line, followed by its constituent test names indented by two spaces. As documented in docs/advanced.md, this format is stable and machine-parseable for test discovery in build systems and IDEs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}