How does GoogleTest's --gtest_filter flag select tests, including negative patterns and the names of parameterized tests?
answer
- full name: Suite.Test
- colon separates, dash excludes
- star and question mark
- list the names first
basics
~20 s--gtest_filter takes colon-separated wildcard patterns matched against full names like Suite.Test; an optional dash introduces patterns to exclude. * and ? are the only wildcards. Parameterized tests carry their prefix and index, as in Small/Sizes.Fits/0.
solid answer
~40 sA filter is matched against each test's **full name**, `TestSuiteName.TestName`. Its format is `positive[:positive...][-negative[:negative...]]`: a test runs if it matches **any** positive pattern and **no** negative one, and a leading `-` alone means `*-...`. Patterns use `*` (any string) and `?` (one character). Value-parameterized tests are named `Prefix/Suite.Test/N`, typed tests `Suite/N.Test`, so `--gtest_filter='Small/Sizes.Fits/*'` picks one instantiation. `--gtest_list_tests` prints the names without running anything, which is how you build a filter. The `GTEST_FILTER` environment variable sets the same thing, but the flag wins when both are given. `DISABLED_` tests stay skipped unless `--gtest_also_run_disabled_tests` is added. A filter that matches nothing prints a warning and still exits 0 unless `--gtest_fail_if_no_test_selected` is set. Quote the pattern so the shell does not expand `*`.
go deeper
Know that --gtest_filter=Suite.* runs one suite and that --gtest_list_tests shows the names.
Explain positive and negative patterns, the full-name format of parameterized and typed tests, and flag-over-environment precedence.
Guard CI filters against silently selecting nothing, and handle disabled tests and CTest's pretty names deliberately.
Standardise how pipelines select subsets so a renamed suite cannot drop coverage without anyone noticing.
## What the filter is matched against Every GoogleTest test has a **full name** of the form `TestSuiteName.TestName`. `TEST(Flaky, FailsFirstTime)` is `Flaky.FailsFirstTime`; `TEST_F(ThermostatTest, Heats)` is `ThermostatTest.Heats`, because the fixture class names the suite. Generated tests carry more: | Declared as | Full names produced | |---|---| | `TEST(Flaky, FailsFirstTime)` | `Flaky.FailsFirstTime` | | `TEST_P(Sizes, Fits)` instantiated by `INSTANTIATE_TEST_SUITE_P(Small, Sizes, Values(1, 2))` | `Small/Sizes.Fits/0`, `Small/Sizes.Fits/1` | | `TYPED_TEST(Cache, Evicts)` over two types | `Cache/0.Evicts`, `Cache/1.Evicts` | The safest way to see the exact names is `--gtest_list_tests`. It prints suites and tests in an indented list, honours `--gtest_filter`, and runs nothing. ## The pattern language The documented grammar is short: 1. a `:`-separated list of **positive patterns**; 2. optionally a `-` followed by a `:`-separated list of **negative patterns**; 3. a test runs if and only if it matches at least one positive pattern and none of the negative ones. Inside a pattern, `*` matches any string and `?` matches any single character; there are no character classes or regular expressions. `-NegativePatterns` on its own is shorthand for `*-NegativePatterns`. Examples a CI job might use: - `--gtest_filter=Flaky.*` runs every test in suite `Flaky`; - `--gtest_filter=*Null*:*Constructor*` runs tests whose full name contains either word; - `--gtest_filter=-*DeathTest.*` runs everything except death-test suites; - `--gtest_filter=Flaky.*:Other.*-Flaky.AlwaysPasses` runs two suites minus one test; - `--gtest_filter='Small/Sizes.Fits/*'` runs one instantiation of a parameterized test. Quote the filter in a shell: an unquoted `Flaky.*` can be expanded against file names in the current directory before GoogleTest sees it. ## Environment variable versus flag The same setting can come from `GTEST_FILTER`. GoogleTest's documentation states the general rule for all its options: when both an environment variable and a flag are given, the **flag takes precedence**. Running with `GTEST_FILTER='Other.*'` and `--gtest_filter='Flaky.AlwaysPasses'` runs only `Flaky.AlwaysPasses`. Flags are read only when `main` called `InitGoogleTest`, which `gtest_main` does. The console confirms the active filter on its first line, `Note: Google Test filter = Flaky.*`, which is the first thing to check when a run executes the wrong tests. ## Edge cases worth knowing - **Disabled tests.** A test or suite whose name starts with `DISABLED_` is compiled but not run, and the filter does not change that. Add `--gtest_also_run_disabled_tests` (or `GTEST_ALSO_RUN_DISABLED_TESTS`) and a filter to run selected disabled tests. - **A filter that matches nothing.** The run prints `WARNING: filter "Nope.*" did not match any test; no tests were run`, reports `[ PASSED ] 0 tests.` and exits 0. A typo in a CI filter therefore passes silently. `--gtest_fail_if_no_test_selected` turns that into exit status 1. - **Pretty names in CTest are not filter names.** CMake's `gtest_discover_tests` may show a parameterized test as `Small/Sizes.Fits/1` where the trailing `1` is the parameter value, not GoogleTest's index; its documentation warns that its `TEST_FILTER` option matches GoogleTest's original names. - **Stopping early.** `--gtest_fail_fast` skips the remaining tests after the first failure, useful with a broad filter during local debugging. ## Putting it together For a flaky subset, the routine is: 1. run `./flaky_test --gtest_list_tests` and copy the exact suite and test names, including any `Prefix/` and `/N` parts; 2. write a positive pattern that covers the suspects, for example `Flaky.*:Small/Sizes.*`; 3. add negative patterns for the ones already cleared, for example `-Flaky.AlwaysPasses`; 4. run once and check the `Note: Google Test filter` line and the `Running N tests` count; 5. add `--gtest_fail_if_no_test_selected` so a later rename cannot turn the job into a silent no-op. The same filter string then feeds `--gtest_repeat` and `--gtest_shuffle` runs without change. Keeping it in one variable of the CI script, rather than copying it into several commands, means the replay of a failing order always selects the same set of tests as the run that failed, which a shuffled replay depends on.
- Why did a CI job that ran --gtest_filter=Flakey.* stay green although it tested nothing?The misspelt filter matched no test. GoogleTest prints a warning that no tests were run, reports zero passed tests and exits with status 0, so the job saw success. Add `--gtest_fail_if_no_test_selected` (or set `GTEST_FAIL_IF_NO_TEST_SELECTED`) so a filter that selects nothing exits with status 1.
- How do you run one test that has been marked DISABLED_ without editing the source?Combine `--gtest_also_run_disabled_tests` with a filter naming it, for example `--gtest_also_run_disabled_tests --gtest_filter=Flaky.DISABLED_TimesOut`. The first flag lifts the exclusion of disabled tests and the filter keeps every other disabled test out of the run.
- Expecting --gtest_filter to accept regular expressions
- Filtering a parameterized test by Suite.Test without its prefix and index
- Believing GTEST_FILTER overrides the command-line flag
- Assuming a filter that matches nothing makes the run fail
- Leaving the filter unquoted so the shell expands the star