# GoogleTest Command-Line Flags: Complete Guide to Controlling Test Execution

> Master GoogleTest command-line flags to filter tests, format output, manage execution, and configure behavior without code changes. Boost your testing efficiency today.

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

---

**GoogleTest provides a comprehensive set of `--gtest_*` command-line flags that allow you to filter tests, control output formats, manage execution flow, and configure runtime behavior without modifying source code.**

The `google/googletest` framework parses these flags through `testing::InitGoogleTest()`, which removes recognized options from `argv` before your `main()` function proceeds. All flag definitions reside in `googletest/src/gtest.cc`, where they are registered using macros like `GTEST_DECLARE_bool_()` and `GTEST_DECLARE_string_()` to control test discovery, repetition, and reporting.

## Test Selection Flags

### Filtering and Listing Tests

The **`--gtest_filter`** flag accepts a pattern string supporting wildcards (`*`) and exclusions (`-`) to execute only matching test cases. This operates on the fully qualified test name (TestSuiteName.TestName).

```bash

# Run only math-related tests, excluding slow variants

./my_test --gtest_filter="MathTest.*-MathTest.*Slow"

```

Use **`--gtest_list_tests`** to print all discovered tests without executing them, useful for CI pipelines or verification of test registration.

```bash
./my_test --gtest_list_tests

```

To include tests prefixed with `DISABLED_`, add **`--gtest_also_run_disabled_tests`**. By default, GoogleTest skips disabled tests during execution.

## Execution Control Flags

### Repetition and Shuffling

The **`--gtest_repeat=<N>`** flag runs the entire test suite `N` times, or indefinitely when set to `-1`. Combine with **`--gtest_recreate_environments_when_repeating=1`** to tear down and rebuild global test environments between repetitions.

```bash

# Run tests 100 times with fresh environments

./my_test --gtest_repeat=100 --gtest_recreate_environments_when_repeating=1

```

Enable **`--gtest_shuffle`** to randomize test execution order. The **`--gtest_random_seed=<seed>`** flag explicitly sets the random seed for reproducible shuffling or parameterized test generation.

## Output and Formatting Flags

### Report Generation and Display Options

GoogleTest supports structured output through **`--gtest_output`**, accepting either `xml` or `json` formats with optional file paths.

```bash

# Generate JSON report to specific directory

./my_test --gtest_output=json:./reports/

# Generate XML with automatic timestamp filename

./my_test --gtest_output=xml

```

Control console presentation with these boolean and enum flags:

- **`--gtest_color=auto|yes|no`** – Force or suppress ANSI color codes
- **`--gtest_brief=1`** – Print only test names without timing or stack traces
- **`--gtest_print_time=0`** – Suppress elapsed time per test (useful for deterministic output)
- **`--gtest_print_utf8=0`** – Disable UTF-8 character printing in test output

## Failure Handling and Debugging Flags

### Immediate Failure and Exception Control

The **`--gtest_break_on_failure`** flag (aliased as **`--gtest_fail_fast`**) immediately terminates the test run upon the first assertion failure. This is essential for debugging failures that cause cascading errors in subsequent tests.

```bash

# Stop on first failure with disabled colors for log files

./my_test --gtest_break_on_failure --gtest_color=no

```

Additional safety flags include:

- **`--gtest_fail_if_no_test_linked`** – Returns failure exit code when no tests are linked to the binary
- **`--gtest_fail_if_no_test_selected`** – Fails when `--gtest_filter` matches zero tests (prevents silent CI success on typos)
- **`--gtest_catch_exceptions=0`** – Disable exception catching to allow debugging of test crashes

Use **`--gtest_stack_trace_depth=<max>`** to limit the depth of stack traces printed on assertion failures (default is implementation-defined).

## Death Test Configuration Flags

For tests using `ASSERT_DEATH` or `EXPECT_DEATH`, **`--gtest_death_test_style`** selects the implementation approach:

- **`fast`** – Faster execution but potentially unsafe with threads
- **`threadsafe`** – Safer for multi-threaded environments (default)
- **`strict`** – Additional validation of death test conditions

The **`--gtest_internal_run_death_test`** flag is reserved for internal use by GoogleTest's subprocess spawning mechanism when executing death tests.

## How Flag Parsing Works

According to the `google/googletest` source code, `testing::InitGoogleTest()` iterates over the `argc`/`argv` array, identifies arguments prefixed with `--gtest_`, and strips them from the command line before returning control to your `main()` function. The parsed values populate global variables (such as `g_test_filter` and `g_print_time`) that the framework consults throughout execution in `googletest/src/gtest.cc`.

Include the public header [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h) to access the initialization function:

```cpp
#include <gtest/gtest.h>

int main(int argc, char** argv) {
  ::testing::InitGoogleTest(&argc, argv);
  return RUN_ALL_TESTS();
}

```

## Summary

- **Test Selection**: Use `--gtest_filter` for pattern matching, `--gtest_list_tests` for discovery, and `--gtest_also_run_disabled_tests` to override `DISABLED_` prefixes.
- **Execution Flow**: Control repetition with `--gtest_repeat`, randomization with `--gtest_shuffle`, and environment lifecycle with `--gtest_recreate_environments_when_repeating`.
- **Output Control**: Generate structured reports via `--gtest_output`, suppress metadata with `--gtest_brief`, and manage color/time display with `--gtest_color` and `--gtest_print_time`.
- **Failure Handling**: Stop immediately using `--gtest_break_on_failure`, catch exceptions selectively with `--gtest_catch_exceptions`, and prevent silent failures using `--gtest_fail_if_no_test_selected`.
- **Death Tests**: Configure thread safety using `--gtest_death_test_style=threadsafe|fast|strict`.

## Frequently Asked Questions

### How do I run only specific tests in GoogleTest?

Use the `--gtest_filter` flag with wildcard patterns. Positive patterns include tests, while negative patterns prefixed with `-` exclude them. For example, `--gtest_filter="FooTest.*:BarTest.*-FooTest.Flaky"` runs all tests in `FooTest` and `BarTest` except `FooTest.Flaky`.

### What is the difference between `--gtest_break_on_failure` and `--gtest_fail_fast`?

These flags are aliases for the same functionality. Both immediately terminate the test executable upon the first assertion failure. This behavior is implemented in `googletest/src/gtest.cc` and is useful for debugging or preventing resource waste in continuous integration pipelines after a failure occurs.

### Can GoogleTest output results in JSON format?

Yes, use `--gtest_output=json[:<path>]` to generate JSON reports. If you omit the path, GoogleTest creates a file in the current directory with a timestamp. This flag is documented in [`docs/advanced.md`](https://github.com/google/googletest/blob/main/docs/advanced.md) along with the XML output option, and is parsed by `InitGoogleTest()` to configure the `XmlUnitTestResultPrinter` or `JsonUnitTestResultPrinter` classes.

### How do I prevent GoogleTest from catching C++ exceptions in tests?

Pass `--gtest_catch_exceptions=0` on the command line. By default, GoogleTest catches exceptions to report them as test failures, but disabling this allows exceptions to propagate to the debugger or crash handler. This is particularly useful when debugging unexpected crashes in test code that manifest as thrown exceptions.