# How to Filter Parameterized Tests in GoogleTest Using Wildcard Patterns

> Learn to filter parameterized GoogleTest tests using wildcard patterns with --gtest_filter or GTEST_FILTER. Efficiently run specific test suites like MathTest/*.

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

---

**Use the `--gtest_filter` command-line flag or the `GTEST_FILTER` environment variable with wildcard patterns (e.g., `MathTest/*`) to match parameterized test names, which append a slash and numeric index after the suite name.**

Parameterized tests in the `google/googletest` framework generate multiple instances that share logic but execute with different inputs. Because each instance receives a unique name containing the parameter index, filtering them requires patterns that account for the special naming convention. This guide explains how to target specific parameterized test suites using wildcards based on the actual implementation in the GoogleTest source code.

## Understanding Parameterized Test Naming Conventions

When you instantiate a parameterized test suite using `INSTANTIATE_TEST_SUITE_P`, GoogleTest constructs the full test name by combining the test suite name, the instantiation prefix, the test name, and a numeric index separated by slashes. For example, a test defined as `TEST_P(MathTest, IsPositive)` instantiated with `Values(1, 2)` generates names like `MathTest/Values.IsPositive/0` and `MathTest/Values.IsPositive/1`.

In [`include/gtest/internal/gtest-param-test.h`](https://github.com/google/googletest/blob/main/include/gtest/internal/gtest-param-test.h), the framework appends the `/N` suffix during test registration. The slash character (`/`) is a literal part of the test name, not a directory separator, which means your filter patterns must explicitly include or wildcard this delimiter to match parameterized instances.

## Basic Filtering with Wildcards

The `--gtest_filter` flag accepts a pattern string that supports two wildcards:
- **`*`** matches any sequence of characters, including the slash and index.
- **`?`** matches exactly one character.

To run all instances of the `MathTest` suite regardless of the instantiation prefix or index, use a pattern that accounts for the slash:

```bash
./my_test --gtest_filter=MathTest/*

```

This matches `MathTest/Values.IsPositive/0`, `MathTest/Values.IsPositive/1`, and any other instantiation because the asterisk consumes everything after the suite name.

## Advanced Pattern Composition

GoogleTest filters support logical composition through positive and negative patterns separated by colons and minus signs.

**Including multiple suites:**

```bash
./my_test --gtest_filter=MathTest/*:StringTest/*

```

**Excluding specific instances:**
Prefix a pattern with a hyphen (`-`) to skip matching tests. This example runs all `MathTest` instances except the first index:

```bash
./my_test --gtest_filter=MathTest/*-MathTest/Values.IsPositive/0

```

The parser in `src/gtest.cc` processes these patterns sequentially, first adding matches for positive patterns, then removing matches for negative patterns.

## Environment Variables and Programmatic Control

You can set filters without modifying command-line arguments by using the `GTEST_FILTER` environment variable:

```bash
export GTEST_FILTER=MathTest/*
./my_test

```

Alternatively, set the flag programmatically in your test driver before calling `RUN_ALL_TESTS()`:

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

int main(int argc, char **argv) {
  ::testing::InitGoogleTest(&argc, argv);
  ::testing::GTEST_FLAG(filter) = "MathTest/*";
  return RUN_ALL_TESTS();
}

```

The flag is declared in [`include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/include/gtest/gtest.h) and parsed in `src/gtest.cc`, where the `UnitTestImpl` class matches the pattern against each test's full name.

## Practical Code Example

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

class MathTest : public ::testing::TestWithParam<int> {
 protected:
  int value_ = GetParam();
};

INSTANTIATE_TEST_SUITE_P(
    IntValues,  // Instantiation prefix
    MathTest,
    ::testing::Values(1, 2, 3)
);

TEST_P(MathTest, IsPositive) {
  EXPECT_GT(value_, 0);
}

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

int main(int argc, char **argv) {
  ::testing::InitGoogleTest(&argc, argv);
  // Uncomment to filter programmatically:
  // ::testing::GTEST_FLAG(filter) = "MathTest/*";
  return RUN_ALL_TESTS();
}

```

Run only the second instance:

```bash
./math_test --gtest_filter=MathTest/IntValues.IsPositive/1

```

Run all except index 2:

```bash
./math_test --gtest_filter=MathTest/*-MathTest/IntValues.IsPositive/2

```

## Summary

- **Parameterized test names** include a slash (`/`) and numeric index generated in [`include/gtest/internal/gtest-param-test.h`](https://github.com/google/googletest/blob/main/include/gtest/internal/gtest-param-test.h), requiring filters to account for this structure.
- Use **`--gtest_filter=PATTERN`** (or `GTEST_FILTER`) with **`*`** to match all instances of a suite (e.g., `MathTest/*`).
- Combine patterns with **:** to include multiple suites and prefix with **-** to exclude specific tests or indices.
- The filtering logic resides in `src/gtest.cc`, where the framework evaluates wildcards against the full test name constructed during instantiation.

## Frequently Asked Questions

### How do I run only the parameterized tests from a specific test suite?

Use a wildcard pattern that matches the suite name followed by a slash: `--gtest_filter=MathTest/*`. This captures all instantiation prefixes and indices because the asterisk matches the entire suffix after the suite name.

### Can I filter parameterized tests by their specific parameter value rather than the index?

No, GoogleTest filters operate on the string representation of the test name, which uses numeric indices (e.g., `/0`, `/1`). The parameter values themselves are not encoded in the name unless you implement a custom naming function via `GetParamName()` in your test fixture, after which you can filter on those custom strings.

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

The asterisk (`*`) matches any sequence of characters of any length, including zero characters and slashes, making it ideal for filtering entire suites or instantiation groups. The question mark (`?`) matches exactly one character, useful for pinpointing specific single-digit indices such as `MathTest/?.IsPositive/0`.

### Why does my filter pattern MathTest.* not work for parameterized tests?

Standard test names use a period (`.`) between the suite and test name, but parameterized tests insert a slash (`/`) between the suite name and the instantiation prefix. Therefore, `MathTest.*` fails to match `MathTest/Values.IsPositive/0`. Use `MathTest/*` instead to account for the slash separator.