# How `INSTANTIATE_TEST_SUITE_P` Creates Named Instantiations in GoogleTest Parameterized Tests > Learn how INSTANTIATE_TEST_SUITE_P generates named instantiations for GoogleTest parameterized tests. Master custom test parameter suffixes and registration. - Repository: [Google/googletest](https://github.com/google/googletest) - Tags: internals - Published: 2026-08-30 --- **`INSTANTIATE_TEST_SUITE_P` is a macro that expands into compile-time code to generate test parameters, optionally create custom name suffixes, and register the resulting test instances with GoogleTest's parameterized test registry.** The `INSTANTIATE_TEST_SUITE_P` macro in the `google/googletest` framework transforms a single line of code into multiple concrete test cases with human-readable names. Understanding its expansion mechanism helps developers debug registration failures and optimize test suite organization. ## Macro Expansion and the Three-Phase Registration Process When you write `INSTANTIATE_TEST_SUITE_P(MyPrefix, MyTestSuite, ::testing::Values(1, 2, 3))`, the preprocessor expands this into three distinct components that execute before `main()` runs. ### Phase 1: Generator Function Creation The macro defines a static function named `gtest_##prefix##test_suite_name##_EvalGenerator_()` that returns a `ParamGenerator`. This function evaluates the third argument of the macro (such as `::testing::Values()` or `::testing::Range()`) and produces the sequence of parameters to iterate over. In [`googletest/include/gtest/gtest-param-test.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-param-test.h) (lines 55-57), the expansion captures the parameter generator expression and wraps it in a function that the framework can call during test discovery. ### Phase 2: Name Generator Setup (Optional) If you supply a fourth argument to the macro, it becomes a callable that receives `TestParamInfo` and returns a `std::string` suffix. The macro creates `gtest_##prefix##test_suite_name##_EvalGenerateName_()` to forward calls to your custom naming logic. When omitted, the system defaults to `DefaultParamName`, which uses `PrintToString` to generate numeric or stringified suffixes. Lines 60-68 of [`gtest-param-test.h`](https://github.com/google/googletest/blob/main/gtest-param-test.h) use a compile-time check (`if (::testing::internal::AlwaysFalse())`) to enforce that only zero or one extra arguments are provided. ### Phase 3: Static Registration via Dummy Variable The final expansion defines a static integer variable named `gtest_##prefix##test_suite_name##_dummy_`. Its initializer executes before `main()` and performs the actual registration by calling: ```cpp UnitTest::GetInstance() ->parameterized_test_registry() .GetTestSuitePatternHolder() ->AddTestSuiteInstantiation() ``` This call in [`googletest/src/gtest-internal-inl.h`](https://github.com/google/googletest/blob/main/googletest/src/gtest-internal-inl.h) (lines 713-722) stores the user-provided prefix string, pointers to the generator and name-generator functions, and source location metadata. The framework later combines the prefix with generated suffixes to create final test names like `MyPrefix/0` or `MyPrefix/EvenValue`. ## Source Code Implementation Details The implementation spans three critical files in the repository: - **[`googletest/include/gtest/gtest-param-test.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-param-test.h)** (lines 53-84): Defines the `INSTANTIATE_TEST_SUITE_P` macro expansion, including the generator creation and registration logic. - **[`googletest/src/gtest-internal-inl.h`](https://github.com/google/googletest/blob/main/googletest/src/gtest-internal-inl.h)** (lines 713-722): Implements `AddTestSuiteInstantiation` within the `parameterized_test_registry`, storing instantiation data for later test case generation. - **[`googletest/include/gtest/internal/gtest-internal.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-internal.h)** (lines 1240-1245): Provides `DefaultParamName` and validation utilities that ensure generated names contain only ASCII alphanumerics and underscores. The macro guarantees that each generated test name is **non-empty, unique, and contains only valid characters** (as documented in lines 45-47 of [`gtest-param-test.h`](https://github.com/google/googletest/blob/main/gtest-param-test.h)). ## Practical Examples ### Basic Named Instantiation ```cpp #include class IntegerTest : public ::testing::TestWithParam {}; TEST_P(IntegerTest, IsPositive) { EXPECT_GT(GetParam(), 0); } INSTANTIATE_TEST_SUITE_P( PositiveNumbers, // prefix appears in test names IntegerTest, ::testing::Values(1, 2, 3)); ``` This generates three test cases named: - `PositiveNumbers/0` - `PositiveNumbers/1` - `PositiveNumbers/2` The macro creates `gtest_PositiveNumbersIntegerTest_EvalGenerator_` to produce the values and registers them via the static dummy variable pattern. ### Custom Name Generators ```cpp #include struct Point { int x, y; }; class PointTest : public ::testing::TestWithParam {}; TEST_P(PointTest, InQuadrantI) { EXPECT_GT(GetParam().x, 0); EXPECT_GT(GetParam().y, 0); } INSTANTIATE_TEST_SUITE_P( Coordinates, PointTest, ::testing::Values(Point{1, 1}, Point{2, 3}), ::testing::PrintToStringParamName); ``` Using `PrintToStringParamName` as the fourth argument generates descriptive names like `Coordinates/(1,1)` and `Coordinates/(2,3)`, assuming `operator<<` is defined for `Point`. ### Lambda-Based Custom Suffixes ```cpp INSTANTIATE_TEST_SUITE_P( ConfigTests, MyParamTest, ::testing::Combine( ::testing::Values("prod", "dev"), ::testing::Values(1, 2)), [](const ::testing::TestParamInfo& info) { const std::string& env = std::get<0>(info.param); int version = std::get<1>(info.param); return env + "_v" + std::to_string(version); }); ``` This produces test names such as `ConfigTests/prod_v1`, `ConfigTests/prod_v2`, `ConfigTests/dev_v1`, and `ConfigTests/dev_v2`. The lambda becomes the target of the internal `gtest_##prefix##test_suite_name##_EvalGenerateName_` function pointer. ## Summary - **`INSTANTIATE_TEST_SUITE_P`** expands into three components: a static generator function, an optional name-generator function, and a static registration variable. - The **prefix argument** becomes the visible namespace for the generated tests, appearing before the slash in the final test name. - **Registration occurs before `main()`** through a static initializer pattern that calls `AddTestSuiteInstantiation` in the parameterized test registry. - **Custom name generators** receive `TestParamInfo` and must return valid C++ identifiers (alphanumeric and underscores only). - Implementation details reside primarily in [`gtest-param-test.h`](https://github.com/google/googletest/blob/main/gtest-param-test.h) for the macro definition and [`gtest-internal-inl.h`](https://github.com/google/googletest/blob/main/gtest-internal-inl.h) for the registry storage logic. ## Frequently Asked Questions ### What is the difference between `INSTANTIATE_TEST_SUITE_P` and `INSTANTIATE_TEST_CASE_P`? `INSTANTIATE_TEST_CASE_P` is the deprecated name for the same functionality, retained for backward compatibility. Modern GoogleTest code should use `INSTANTIATE_TEST_SUITE_P`, which was introduced to clarify that parameterized test suites are distinct from test cases. Both macros expand identically in the source code. ### How do I ensure unique test names when using `INSTANTIATE_TEST_SUITE_P`? GoogleTest enforces uniqueness at runtime. If your custom name generator returns duplicate strings for different parameters, the framework throws an error during test initialization. Ensure your name generator produces unique suffixes for every parameter value in the set. The default `DefaultParamName` uses the parameter index to guarantee uniqueness. ### Can I use multiple `INSTANTIATE_TEST_SUITE_P` calls for the same test suite? Yes. You can instantiate the same test fixture with different prefixes and parameter sets. Each call generates a distinct set of tests with unique names. For example, you can have `INSTANTIATE_TEST_SUITE_P(Foo, MyTest, Values(1,2))` and `INSTANTIATE_TEST_SUITE_P(Bar, MyTest, Values(3,4))` in the same translation unit, producing `Foo/0`, `Foo/1`, `Bar/0`, and `Bar/1`. ### Why does `INSTANTIATE_TEST_SUITE_P` use a static dummy variable for registration? The static variable pattern ensures that test registration executes during program startup before `main()` runs, without requiring explicit initialization calls in user code. The variable's initializer calls `UnitTest::GetInstance()->parameterized_test_registry()`, which is the singleton access point for all parameterized tests. This design follows the global constructor pattern used throughout GoogleTest to enable automatic test discovery.