# How to Filter Tests in GoogleTest Using Command-Line Flags

> Learn to filter tests in GoogleTest with --gtest_filter command-line flags. Use wildcard patterns to include or exclude specific tests efficiently.

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

---

**GoogleTest selects which tests to run through the `--gtest_filter` flag, which accepts wildcard patterns to include or exclude specific tests based on their fully-qualified names.**

The GoogleTest framework (maintained by Google at `google/googletest`) provides powerful command-line filtering capabilities that allow you to execute specific subsets of your test suite without recompiling. By leveraging pattern matching against test suite and test case names, you can precisely control which tests run during debugging, CI pipelines, or local development cycles.

## Understanding the `--gtest_filter` Syntax

The `--gtest_filter` flag uses a specific pattern syntax parsed in `googletest/src/gtest.cc` at line 929. The filter string splits on the hyphen character (`-`) to separate **positive patterns** (tests to include) from **negative patterns** (tests to exclude).

The formal syntax follows this structure:

```

<positive_pattern>[:<positive_pattern>...] [-<negative_pattern>[:<negative_pattern>...]]

```

- **Positive patterns** specify tests to run. A test executes if its fully-qualified name (`<test_suite>.<test_name>`) matches any positive pattern.
- **Negative patterns** (prefixed with `-`) override positive matches. Tests matching any negative pattern are skipped, even if they match a positive pattern.

When you omit the filter flag or provide an empty string, GoogleTest executes all registered tests by default.

## Wildcard Pattern Matching Algorithm

GoogleTest implements wildcard matching through the `FilterMatchPattern` function defined in [`googletest/include/gtest/internal/gtest-internal-inl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-internal-inl.h). This algorithm supports two wildcard characters:

- **`*`** matches any sequence of characters (including an empty sequence)
- **`?`** matches exactly one character

The matching engine compares these patterns against fully-qualified test names in the format `TestSuiteName.TestName`. This allows precise targeting of individual tests, entire suites, or arbitrary name patterns without modifying your source code.

## Practical Filter Examples

Run these commands from your terminal to filter test execution:

```bash

# Run all tests (equivalent to no filter)

./my_test_binary --gtest_filter=*

# Run all tests in a specific suite

./my_test_binary --gtest_filter=MathTest.*

# Run a single specific test

./my_test_binary --gtest_filter=MathTest.Addition

# Exclude all death tests

./my_test_binary --gtest_filter=-*DeathTest.*

# Run multiple suites with OR logic

./my_test_binary --gtest_filter=FooTest.*:BarTest.*

# Combine inclusion and exclusion

./my_test_binary --gtest_filter=MathTest.*:-MathTest.DivisionByZero

# Run tests containing specific substrings

./my_test_binary --gtest_filter=*Null*:*Constructor*

# Skip disabled tests (prefixed with DISABLED_)

./my_test_binary --gtest_filter=*:-*DISABLED_*

```

Each colon (`:`) acts as an OR operator for positive patterns, while the leading hyphen (`-`) switches to exclusion mode for all subsequent patterns.

## Combining Filters with Other Execution Flags

You can chain `--gtest_filter` with additional GoogleTest flags to further refine execution behavior. According to the Advanced GoogleTest Topics documentation in [`docs/advanced.md`](https://github.com/google/googletest/blob/main/docs/advanced.md), common combinations include:

- **`--gtest_repeat=N`** – Run the filtered test set N times consecutively
- **`--gtest_shuffle`** – Randomize the order of filtered tests
- **`--gtest_break_on_failure`** – Stop execution immediately when a filtered test fails

For example, to run all MathTest cases three times in random order:

```bash
./my_test_binary --gtest_filter=MathTest.* --gtest_repeat=3 --gtest_shuffle

```

## Summary

- **`--gtest_filter`** parses in `googletest/src/gtest.cc` and supports positive and negative wildcard patterns separated by a hyphen.
- **Positive patterns** (left of `-`) include tests; **negative patterns** (right of `-`) exclude them.
- **Wildcards** use `*` for any sequence and `?` for single characters, implemented in `FilterMatchPattern` within [`gtest-internal-inl.h`](https://github.com/google/googletest/blob/main/gtest-internal-inl.h).
- **Colons** separate multiple positive or negative patterns, functioning as logical OR operators.
- **Empty filters** execute the entire test suite, while specific patterns enable surgical test selection without recompilation.

## Frequently Asked Questions

### How do I run only one specific test in GoogleTest?

Use the fully-qualified test name with the `--gtest_filter` flag: `./my_test_binary --gtest_filter=SuiteName.TestName`. This targets exactly one test case while skipping all others.

### What is the difference between `*` and `?` in GoogleTest filters?

The `*` wildcard matches any sequence of characters (including none), allowing patterns like `Foo*` to match `Foo`, `FooBar`, and `FooTest.Baz`. The `?` wildcard matches exactly one character, so `Foo?` matches `FooA` or `Foo1` but not `Foo` or `FooBar`.

### Can I exclude disabled tests while running everything else?

Yes. Disabled tests in GoogleTest are prefixed with `DISABLED_`. To run all non-disabled tests, use: `./my_test_binary --gtest_filter=*:-*DISABLED_*`. The positive `*` includes all tests, while the negative `-*DISABLED_*` removes disabled ones.

### Where is the filter pattern matching implemented in the GoogleTest source code?

The core parsing logic resides in `googletest/src/gtest.cc` around line 929, which splits the filter string into positive and negative patterns. The actual wildcard matching algorithm (`FilterMatchPattern`) lives in [`googletest/include/gtest/internal/gtest-internal-inl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-internal-inl.h), handling the `*` and `?` character comparisons against test names.