# What Is `internal::TestFactoryImpl` in GoogleTest? Purpose and Architecture

> Understand internal::TestFactoryImpl in GoogleTest. Discover how this factory class enables dynamic test object creation at runtime by implementing TestFactoryBase.

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

---

**`internal::TestFactoryImpl` is the concrete factory class that bridges static test registration macros with dynamic test object instantiation at runtime by implementing the `TestFactoryBase` interface.**

The GoogleTest framework relies on sophisticated factory patterns to manage test object lifetimes without hard-coding constructor logic into the registration system. At the heart of this mechanism lies `internal::TestFactoryImpl`, a template class defined in the internal namespace that enables the `TEST` and `TEST_F` macros to create test instances on demand. Understanding this component reveals how GoogleTest maintains a flexible architecture that supports standard tests, death tests, and parameterized tests through a unified factory interface.

## Core Responsibilities of `internal::TestFactoryImpl`

### Runtime Test Object Instantiation

When you define a test using the `TEST()` or `TEST_F()` macros, the preprocessor expands this into a unique test class definition. The framework must instantiate this class at runtime without knowing its specific constructor signature in advance. `TestFactoryImpl<TestClass>` fulfills this requirement by overriding the pure virtual `CreateTest()` method inherited from `TestFactoryBase` to return `new TestClass`.

According to the GoogleTest source code in [`include/gtest/internal/gtest-internal.h`](https://github.com/google/googletest/blob/main/include/gtest/internal/gtest-internal.h) (lines 453-556), the `TestFactoryImpl` template implements the instantiation logic that the framework calls immediately before executing a test's body.

### Decoupling Registration from Object Creation

The `TestInfo` class stores a pointer to `TestFactoryBase` rather than to concrete test classes. This abstraction allows `MakeAndRegisterTestInfo()` in `src/gtest.cc` (lines 2850-2860) to accept any factory type while keeping the registration logic agnostic of instantiation details. Later, when `TestInfo::Run()` executes, it invokes `factory_->CreateTest()` to build the test object just before the test runs. This separation ensures the framework can manage object lifetimes and support test fixtures without embedding creation logic in the registration pipeline.

## The Registration Pipeline in Action

Behind every simple `TEST` macro lies an expanded registration sequence that wires the static definition to a dynamic factory. When you write:

```cpp
TEST(Math, SimpleAdd) {
  EXPECT_EQ(2 + 2, 4);
}

```

The preprocessor expands this to code that:
1. Defines a class `Math_SimpleAdd_Test` inheriting from `testing::Test`
2. Instantiates a `TestFactoryImpl<Math_SimpleAdd_Test>` object
3. Passes this factory to `MakeAndRegisterTestInfo()` for storage in the test registry

The expanded code resembles:

```cpp
// Simplified macro expansion
internal::TestFactoryBase* factory = 
    new internal::TestFactoryImpl<Math_SimpleAdd_Test>();

internal::MakeAndRegisterTestInfo(
    "Math", "SimpleAdd", nullptr, nullptr,
    internal::CodeLocation(__FILE__, __LINE__),
    internal::GetTypeId<Math_SimpleAdd_Test>(),
    nullptr, nullptr, factory);

```

When `RUN_ALL_TESTS()` executes, the framework retrieves this factory from the `TestInfo` object and calls `CreateTest()` to instantiate the test class immediately before invoking its test body.

## Extensibility Through the Factory Interface

While `TestFactoryImpl` handles standard tests, the `TestFactoryBase` interface enables specialized test types without modifying the core registration machinery in `src/gtest.cc`.

### Parameterized Test Factories

Parameterized tests use `ParameterizedTestFactory` defined in [`include/gtest/internal/gtest-param-util.h`](https://github.com/google/googletest/blob/main/include/gtest/internal/gtest-param-util.h) (lines 400-426). This factory inherits from `TestFactoryBase` but stores parameter values and passes them to the test class constructor. Because it implements the same interface as `TestFactoryImpl`, the `TestInfo` class handles it identically, demonstrating how the abstract factory pattern supports complex initialization scenarios while maintaining compatibility with the standard registration pipeline.

### Death Test Factories

For death tests, GoogleTest employs alternative factory implementations such as `DefaultDeathTestFactory` located in [`include/gtest/internal/gtest-death-test-internal.h`](https://github.com/google/googletest/blob/main/include/gtest/internal/gtest-death-test-internal.h) (lines 180-190). These factories plug into the same `TestFactoryBase` pointer stored in `TestInfo`, allowing the framework to replace the creation strategy for special test types without touching the core registration logic that stores and invokes the factory.

## Source Code Architecture

The factory system spans several key files in the GoogleTest repository:

- **[`include/gtest/internal/gtest-internal.h`](https://github.com/google/googletest/blob/main/include/gtest/internal/gtest-internal.h)**: Defines the abstract `TestFactoryBase` interface and the `TestFactoryImpl<TestClass>` template providing default instantiation logic.
- **`src/gtest.cc`**: Implements `MakeAndRegisterTestInfo()` which stores the factory pointer and `TestInfo::Run()` which invokes `factory_->CreateTest()` at execution time.
- **[`include/gtest/internal/gtest-param-util.h`](https://github.com/google/googletest/blob/main/include/gtest/internal/gtest-param-util.h)**: Houses `ParameterizedTestFactory` for value-parameterized and type-parameterized tests.
- **[`include/gtest/internal/gtest-death-test-internal.h`](https://github.com/google/googletest/blob/main/include/gtest/internal/gtest-death-test-internal.h)**: Contains `DefaultDeathTestFactory`, illustrating how alternative implementations handle specialized test object creation.

## Summary

- **`internal::TestFactoryImpl`** implements the **`TestFactoryBase`** interface to provide default test object instantiation for the `TEST` and `TEST_F` macros.
- The factory pattern **decouples** test registration (stored in `TestInfo`) from object creation, allowing `src/gtest.cc` to manage object lifetimes generically without knowing test class constructors.
- **Alternative factories** like `ParameterizedTestFactory` and `DefaultDeathTestFactory` plug into the same interface, enabling death tests and parameterized tests without changing core registration logic.
- Test objects are instantiated via **`new TestClass`** inside `TestFactoryImpl::CreateTest()` immediately before execution, ensuring fresh object state for each test run.

## Frequently Asked Questions

### What is the difference between `TestFactoryBase` and `TestFactoryImpl`?

`TestFactoryBase` is the abstract interface declaring the virtual `CreateTest()` method, while `TestFactoryImpl<TestClass>` is the concrete template class that implements this method by returning `new TestClass`. The base class allows `TestInfo` objects to store factory pointers polymorphically, while the implementation class provides the specific instantiation logic for individual test classes defined by the `TEST` macro.

### How does `TestFactoryImpl` relate to the `TEST` macro?

The `TEST` macro expands to code that instantiates a `TestFactoryImpl<YourTestClass>` and passes it to `MakeAndRegisterTestInfo()` during global initialization. When `RUN_ALL_TESTS()` later iterates through registered tests, it calls the factory's `CreateTest()` method to instantiate the test object just before executing the test body.

### Can I create custom factory implementations for specialized test types?

Yes, you can create custom factories inheriting from `TestFactoryBase` and register them using advanced GoogleTest APIs. The framework's own use of `ParameterizedTestFactory` for parameterized tests and `DefaultDeathTestFactory` for death tests demonstrates how custom factories can plug into the standard registration pipeline while providing specialized instantiation logic.

### Where exactly does `TestFactoryImpl` create the test object in the source code?

The actual instantiation occurs in `TestInfo::Run()` implemented in `src/gtest.cc`, which calls `factory_->CreateTest()`. For `TestFactoryImpl`, this executes the `new TestClass` expression defined in [`include/gtest/internal/gtest-internal.h`](https://github.com/google/googletest/blob/main/include/gtest/internal/gtest-internal.h). This happens immediately before the test body runs, ensuring each iteration—including retries for death tests or different parameter values—receives a fresh object instance.