# How to List All Available Tests Without Running Them in GoogleTest

> Discover how to list all GoogleTest tests without running them using the --gtest_list_tests flag. Get a clear overview of your test suite efficiently.

- Repository: [Google/googletest](https://github.com/google/googletest)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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:

```bash
./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`](https://github.com/google/googletest/blob/main/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:

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

```

### Capture to File

Redirect the output for processing in CI scripts:

```bash
./my_test_binary --gtest_list_tests > test_inventory.txt

```

### Filtered Listing

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

```bash
./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`](https://github.com/google/googletest/blob/main/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`](https://github.com/google/googletest/blob/main/docs/advanced.md), this format is stable and machine-parseable for test discovery in build systems and IDEs.