In GoogleTest, how do TEST_P and INSTANTIATE_TEST_SUITE_P run one test body over many values, and how are the generated tests named?
answer
- TestWithParam<T> and GetParam()
- generators: Values, Range, Combine
- prefix, suite, test, index
- a name generator for readable suffixes
basics
~20 sA fixture derived from testing::TestWithParam<T> holds the TEST_P bodies, which read GetParam(). INSTANTIATE_TEST_SUITE_P supplies values from a generator such as Values or Combine, and each value becomes a test named Prefix/Suite.Test/index unless a name generator supplies the suffix.
solid answer
~40 sDerive the fixture from `testing::TestWithParam<T>`, write the body once with `TEST_P(Fixture, Test)`, and read the current value with `GetParam()`. At namespace scope, `INSTANTIATE_TEST_SUITE_P(Prefix, Fixture, generator)` supplies the values: `Values(...)`, `ValuesIn(container)`, `Range(begin, end, step)` with `end` excluded, `Bool()`, or `Combine(g1, g2)` for the Cartesian product as `std::tuple`. Every `TEST_P` in the suite runs once per value, whether defined before or after the instantiation. Tests are named `Prefix/Fixture.Test/0`, `/1` and so on, which is what filters match; an optional fourth argument, a function taking `testing::TestParamInfo<ParamType>`, gives readable suffixes such as `File4096`. A `TEST_P` with no instantiation produces a failing test in the suite `GoogleTestVerification`.
code
cpp · 25 lines#include <gtest/gtest.h>
#include <string>
#include <tuple>
enum class Backend { kFile, kMemory };
class KvRoundTripTest
: public testing::TestWithParam<std::tuple<Backend, int>> {};
TEST_P(KvRoundTripTest, StoresValueOfSize) {
const auto [backend, size] = GetParam();
std::string value(static_cast<size_t>(size), 'x');
EXPECT_EQ(value.size(), static_cast<size_t>(size));
(void)backend; // a real test would open the store for this backend
}
INSTANTIATE_TEST_SUITE_P(
AllBackends, KvRoundTripTest,
testing::Combine(testing::Values(Backend::kFile, Backend::kMemory),
testing::Values(1, 4096)),
[](const testing::TestParamInfo<KvRoundTripTest::ParamType>& info) {
const char* name =
std::get<0>(info.param) == Backend::kFile ? "File" : "Memory";
return std::string(name) + std::to_string(std::get<1>(info.param));
});go deeper
Recall the three pieces: a TestWithParam<T> fixture, TEST_P bodies using GetParam(), and INSTANTIATE_TEST_SUITE_P with Values.
Explain the generators including Combine and Range's excluded end, the Prefix/Suite.Test/index naming, and custom name generators.
Keep parameterized suites readable and bounded: named suffixes for reports and filters, no combinatorial blow-up, and the uninstantiated-suite check understood.
Decide when a conformance suite shared across implementations is worth building as abstract parameterized tests that each team instantiates.
## The problem value parameters solve Testing a key-value store over two backends and two value sizes by hand means four nearly identical tests. **Value-parameterized tests** write the body once and let GoogleTest run it for each parameter value. Three pieces are involved. ## Piece 1: the fixture The fixture derives from `testing::TestWithParam<T>`, where `T` is the parameter type. `TestWithParam<T>` itself derives from `testing::Test` and `testing::WithParamInterface<T>`, so an existing fixture can gain parameters by also deriving from `WithParamInterface<T>`. `T` must be copyable; with a raw pointer type you manage the pointees' lifetime yourself. ```cpp enum class Backend { kFile, kMemory }; class KvRoundTripTest : public testing::TestWithParam<std::tuple<Backend, int>> {}; ``` ## Piece 2: the test patterns `TEST_P(KvRoundTripTest, StoresValueOfSize)` defines a test **pattern**. Inside it, `GetParam()` returns the current value; with a tuple, a structured binding such as `const auto [backend, size] = GetParam();` unpacks it. A suite may hold many `TEST_P` patterns, and each runs once for every value of every instantiation. ## Piece 3: the instantiation `INSTANTIATE_TEST_SUITE_P(Prefix, Fixture, generator)` must appear at namespace scope, not inside a function. It instantiates **all** `TEST_P` patterns of the suite, including ones defined after it in the file. The generators live in `::testing`: | Generator | Yields | |---|---| | `Values(v1, ..., vN)` | the listed values | | `ValuesIn(container)` or `ValuesIn(begin, end)` | elements of an array, container or iterator range | | `Range(begin, end)` or `Range(begin, end, step)` | `begin`, `begin + step`, ... excluding `end` | | `Bool()` | `false`, `true` | | `Combine(g1, ..., gN)` | every combination, as `std::tuple` | | `ConvertGenerator<T>(g)` | values of `g` converted with `static_cast` | Generator expressions are evaluated when GoogleTest initialises, so they can use results of work done earlier in `main()`, such as parsed command-line options. ## How the tests are named Each generated test gets a full name of the form `Prefix/Fixture.Test/Suffix`: - `Prefix` is the instantiation name, which separates several instantiations of one suite, for example `AllBackends` and `FileOnly`. An empty prefix is allowed and adds nothing. - `Suffix` defaults to the value's index, `0`, `1`, `2` and so on. - An optional fourth argument to `INSTANTIATE_TEST_SUITE_P` is a name generator: a function or lambda taking `const testing::TestParamInfo<ParamType>&` and returning `std::string`, built from `info.param`. It turns `/3` into `/Memory4096`. `testing::PrintToStringParamName()` is a ready-made one that does not work for string parameters. Names matter because a filter such as `--gtest_filter='AllBackends/*Memory*'` selects tests by them, and because a report that says `/3 failed` forces someone to work out which value index 3 was. With `Combine`, the first generator varies slowest, so the four tests come out as `File1`, `File4096`, `Memory1`, `Memory4096`. Names must stay unique and alphanumeric; the reference permits underscores in a suffix, but the FAQ advises against underscores in test names, so plain alphanumerics are the safe choice. ## The uninstantiated-suite check A `TEST_P` suite that is never instantiated would silently run nothing. GoogleTest therefore adds a failing test to a suite called `GoogleTestVerification` naming the uninstantiated suite. When that is intentional, such as an abstract suite in a library for others to instantiate, `GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST(Fixture);` suppresses the failure. ## Adding a case without touching the body The pay-off shows when the store gains a third backend. The change is mechanical: 1. Add the enumerator, for example `Backend::kMmap`. 2. Add it to the `Values(...)` list in the instantiation. 3. Extend the name generator so the new tests read `Mmap1` and `Mmap4096`. Every existing `TEST_P` pattern now runs against the new backend, and none of the test bodies changes. If only some patterns apply to the new backend, a second fixture or a second instantiation with its own prefix keeps the suites honest instead of adding conditionals inside the bodies. ## Abstract test suites Putting the fixture in a header and the `TEST_P` patterns in a library lets each implementation of an interface instantiate the same conformance suite with its own factory as the parameter. This is the value-parameterized counterpart of type-parameterized tests. ## Common mistakes - Placing `INSTANTIATE_TEST_SUITE_P` inside a function, which does not compile. - Reusing one prefix for two instantiations of the same suite; in one source file that is a redefinition compile error. - Relying on index suffixes, so reports name values only by position. - Forgetting an instantiation, which the `GoogleTestVerification` failure catches.
- What happens to a TEST_P suite that no INSTANTIATE_TEST_SUITE_P covers?None of its patterns run, and GoogleTest adds a failing test to the `GoogleTestVerification` suite naming the uninstantiated suite. If the omission is intentional, for instance an abstract suite shipped in a library, `GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST(Fixture);` in the defining namespace suppresses it.
- How do you run the same TEST_P patterns over two unrelated value sets?Write two `INSTANTIATE_TEST_SUITE_P` lines with different prefixes, for example `Small` with `Values(1, 2)` and `Large` with `Values(1 << 20)`. Each instantiation produces its own set of tests named `Small/...` and `Large/...`, and the prefix keeps them distinct.
- When is Combine a poor choice?When the product grows large or most combinations add nothing. `Combine` of three generators with ten values each yields a thousand tests. Listing the meaningful tuples with `Values(std::make_tuple(...), ...)` or `ValuesIn` keeps the suite focused; which inputs deserve a case is a test-design decision.
- INSTANTIATE_TEST_SUITE_P only covers TEST_P patterns defined above it.
- Range(0, 3) yields 0, 1, 2 and 3.
- A TEST_P suite with no instantiation is simply skipped without any report.
- INSTANTIATE_TEST_SUITE_P can be written inside a test function.
- GetParam() is a free function usable anywhere in the test file.