# How to Use Parameter Generators like Range and ValuesIn in GoogleTest: A Complete Guide

> Master GoogleTest parameter generators like Range and ValuesIn for efficient data-driven testing. Enhance your TEST_P cases with lazy sequences of values using this comprehensive guide.

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

---

**GoogleTest parameter generators—including `Range`, `Values`, `ValuesIn`, `Bool`, and `Combine`—enable data-driven testing by supplying lazy sequences of values to `TEST_P` test cases via the `testing::TestWithParam<T>` fixture pattern.**

The `google/googletest` repository provides a comprehensive value-parameterized testing framework defined primarily in [`googletest/include/gtest/gtest-param-test.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-param-test.h). These generators produce sequences that are evaluated lazily during `InitGoogleTest()`, allowing you to programmatically modify test data before execution while running a single test body across multiple inputs.

## Understanding Value-Parameterized Tests

Value-parameterized tests in GoogleTest allow you to execute the same test logic with varying input data. The architecture relies on three core components defined in the `testing` namespace:

- **`testing::TestWithParam<T>`**: A fixture template where `T` represents the type of a single parameter value (or `std::tuple` when using `Combine`).
- **`TEST_P`**: A macro that defines test cases within a parameterized fixture.
- **`INSTANTIATE_TEST_SUITE_P`**: A macro that binds a specific generator to your test suite, creating individually named test instances.

According to the source code in [`googletest/include/gtest/internal/gtest-param-util.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-param-util.h), these generators implement a lazy evaluation strategy—they do not materialize values until the test framework initializes, which occurs after `main()` begins execution.

## The Three-Step Implementation Pattern

To implement parameterized tests using generators like `Range` or `ValuesIn`, follow this standardized workflow:

1. **Define a fixture** inheriting from `testing::TestWithParam<T>`.
2. **Write test logic** using the `TEST_P` macro, accessing the current value via `GetParam()`.
3. **Instantiate the suite** with `INSTANTIATE_TEST_SUITE_P(prefix, FixtureName, generator)`, where `generator` is any valid parameter generator function.

## Core Parameter Generators Reference

GoogleTest provides five primary generator functions in [`gtest-param-test.h`](https://github.com/google/googletest/blob/main/gtest-param-test.h), each designed for specific data scenarios.

### Range(start, end, [step])

The **`Range`** generator yields consecutive integer values from `start` (inclusive) to `end` (exclusive).

- **Signature**: `Range(T start, T end)` or `Range(T start, T end, IncrementT step)`
- **Behavior**: Produces `{start, start+step, ..., end-1}`. The default step is `1`.
- **Use case**: Numeric iterations, boundary testing, and strided sequences.

```cpp
class IntRangeTest : public ::testing::TestWithParam<int> {};

TEST_P(IntRangeTest, IsPositive) {
  EXPECT_GT(GetParam(), 0);
}
INSTANTIATE_TEST_SUITE_P(
    PositiveIntegers,
    IntRangeTest,
    ::testing::Range(1, 10));  // Generates 1, 2, ..., 9

```

### Values(v1, v2, ...)

The **`Values`** generator accepts an explicit variadic list of values of any copyable type.

- **Signature**: `Values(T ...v)`
- **Behavior**: Produces the exact sequence provided in the argument list.
- **Use case**: Discrete test cases with specific, named inputs.

```cpp
class StringTest : public ::testing::TestWithParam<const char*> {};

TEST_P(StringTest, IsNotEmpty) {
  EXPECT_STRNE(GetParam(), "");
}
INSTANTIATE_TEST_SUITE_P(
    ValidStrings,
    StringTest,
    ::testing::Values("alpha", "beta", "gamma"));

```

### ValuesIn(container)

The **`ValuesIn`** generator extracts elements from existing STL containers, C-arrays, or iterator ranges.

- **Signature**: `ValuesIn(const Container& container)` or `ValuesIn(Iterator begin, Iterator end)`
- **Behavior**: Iterates over the provided data structure, exposing each element as a test parameter.
- **Use case**: When test data originates from external configuration files or pre-computed datasets.

```cpp
class VectorTest : public ::testing::TestWithParam<std::vector<int>> {};

TEST_P(VectorTest, SumIsPositive) {
  int sum = std::accumulate(GetParam().begin(), GetParam().end(), 0);
  EXPECT_GT(sum, 0);
}

std::vector<std::vector<int>> test_data = {{1, 2}, {3, 4, 5}};
INSTANTIATE_TEST_SUITE_P(
    VectorCases,
    VectorTest,
    ::testing::ValuesIn(test_data));

```

### Bool()

The **`Bool`** generator is a convenience wrapper producing the boolean sequence `{false, true}`.

- **Signature**: `Bool()`
- **Behavior**: Equivalent to `Values(false, true)`.
- **Use case**: Exhaustive testing of feature flags or binary configuration states.

```cpp
class FeatureToggleTest : public ::testing::TestWithParam<bool> {};

TEST_P(FeatureToggleTest, ConsistentBehavior) {
  bool feature_enabled = GetParam();
  // Test logic that varies by flag state
}
INSTANTIATE_TEST_SUITE_P(
    FlagStates,
    FeatureToggleTest,
    ::testing::Bool());

```

### Combine(g1, g2, ...)

The **`Combine`** generator computes the Cartesian product of multiple generators, producing `std::tuple` instances containing one value from each source.

- **Signature**: `Combine(Gen1 g1, Gen2 g2, ...)`
- **Behavior**: Yields every possible combination of the input generators. The test fixture must use `TestWithParam<std::tuple<T1, T2, ...>>`.
- **Use case**: Multi-dimensional testing matrices, such as testing all combinations of buffer sizes and enum values.

```cpp
enum Color { RED, GREEN, BLUE };

class MultiParamTest : public ::testing::TestWithParam<std::tuple<int, Color>> {};

TEST_P(MultiParamTest, AllCombinationsWork) {
  int size = std::get<0>(GetParam());
  Color color = std::get<1>(GetParam());
  // Test implementation using both parameters
}

INSTANTIATE_TEST_SUITE_P(
    SizeAndColorMatrix,
    MultiParamTest,
    ::testing::Combine(
        ::testing::Range(1, 4),           // 1, 2, 3
        ::testing::Values(RED, GREEN, BLUE)));

```

## Internal Architecture and Source Files

The parameter generator system is implemented across several key files in the `google/googletest` repository:

- **[`googletest/include/gtest/gtest-param-test.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-param-test.h)**: Defines the public API including `Range`, `Values`, `ValuesIn`, `Bool`, `Combine`, and the `INSTANTIATE_TEST_SUITE_P` macro. Also includes `ConvertGenerator` for custom type casting and `PrintToStringParamName` for test naming.
- **[`googletest/include/gtest/internal/gtest-param-util.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-param-util.h)**: Contains internal implementation classes such as `RangeGenerator`, `ValuesInIteratorRangeGenerator`, and `CartesianProductGenerator` that power the lazy evaluation engine.
- **`googletest/samples/sample7_unittest.cc`**: Demonstrates a real-world factory-function pattern using `Values` to instantiate tests for different `PrimeTable` implementations.

As implemented in `google/googletest`, these generators are evaluated during the `InitGoogleTest()` phase, allowing runtime modification of test parameters before the fixture constructor executes.

## Summary

- **Value-parameterized tests** use `testing::TestWithParam<T>` fixtures and the `TEST_P` macro to execute identical logic across multiple inputs.
- **Parameter generators** (`Range`, `Values`, `ValuesIn`, `Bool`, `Combine`) provide lazy sequences defined in [`gtest-param-test.h`](https://github.com/google/googletest/blob/main/gtest-param-test.h).
- **`INSTANTIATE_TEST_SUITE_P`** binds generators to test suites, creating individually named test cases visible in output.
- **Generator evaluation** occurs during framework initialization, enabling dynamic test data configuration.
- **`Combine`** produces `std::tuple` parameters for multi-dimensional testing matrices.

## Frequently Asked Questions

### How do I pass multiple independent parameters to a single TEST_P test?

Use the **`Combine`** generator to create a Cartesian product of multiple generators. Your fixture must inherit from `testing::TestWithParam<std::tuple<T1, T2, ...>>`, and you access individual values via `std::get<0>(GetParam())`, `std::get<1>(GetParam())`, etc. This is implemented in [`googletest/include/gtest/gtest-param-test.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-param-test.h).

### What is the difference between Values and ValuesIn generators?

**`Values`** accepts a compile-time variadic list of literal values (e.g., `Values(1, 2, 3)`), while **`ValuesIn`** accepts a runtime container or iterator range (e.g., `ValuesIn(my_vector)`). Use `Values` for static, explicit test cases and `ValuesIn` when data is constructed dynamically or loaded from external sources.

### When exactly are parameter generators evaluated during the test lifecycle?

Parameter generators are evaluated **lazily** during the `InitGoogleTest()` call, which occurs after `main()` begins but before any test fixtures are constructed. As defined in the internal utilities in [`gtest-param-util.h`](https://github.com/google/googletest/blob/main/gtest-param-util.h), this delayed evaluation allows you to programmatically modify generator arguments (such as container contents) before the test suite runs.

### Can I use custom data types with GoogleTest parameter generators?

Yes. For explicit value lists, ensure your type is copyable and streamed to output for readable test names. For type conversions, use **`ConvertGenerator`** as defined in [`gtest-param-test.h`](https://github.com/google/googletest/blob/main/gtest-param-test.h). The framework automatically uses `PrintToStringParamName` to generate test case names unless you provide a custom naming function to `INSTANTIATE_TEST_SUITE_P`.