# Basic Structure of a GoogleTest Test Case: Macro Expansion and Class Architecture

> Understand the basic structure of a GoogleTest test case. Learn how TEST macros create C++ classes inheriting from ::testing::Test for automated test running.

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

---

**A GoogleTest test case is a C++ class generated by the `TEST` or `TEST_F` macros that inherits from `::testing::Test`, with the test body placed inside the generated class's implementation and automatically registered with the framework's test runner.**

The basic structure of a GoogleTest test case relies on preprocessor macro expansion to transform simple declarative syntax into a complete class hierarchy. In the `google/googletest` repository, these mechanisms are implemented in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h), using internal utilities like `GTEST_TEST_` and `GetTestTypeId()` to hide complex template logic from the test writer.

## The Two Fundamental Test Case Types

GoogleTest provides two primary macros for declaring test cases, each serving different testing needs.

### Simple Test Cases with the TEST Macro

The `TEST` macro declares a basic test case without shared state. According to the source code in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h) at lines 2206-2207, this macro expands to `GTEST_TEST`, which in turn invokes `GTEST_TEST_`. This internal macro generates a class that inherits from `::testing::Test` and automatically registers the test with the framework's registry.

```cpp
// googletest/include/gtest/gtest.h (lines 2206-2207)
TEST(MathTest, AddsTwoIntegers) {
  int sum = 2 + 3;
  EXPECT_EQ(sum, 5);        // Non-fatal assertion
  ASSERT_GT(sum, 0);        // Fatal assertion - stops test if failed
}

```

When compiled, this macro creates a unique class containing your test logic inside its `TestBody()` method. The `TEST` macro is ideal for isolated unit tests that do not require shared resources or setup logic.

### Fixture-Based Tests with the TEST_F Macro

The `TEST_F` macro declares a test that utilizes a **test fixture** — a user-defined class providing shared state and lifecycle methods. Defined at lines 2238-2239 in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h), this macro expands to `GTEST_TEST_F`, which generates a class inheriting from your custom fixture rather than directly from `::testing::Test`.

```cpp
// googletest/include/gtest/gtest.h (lines 2238-2239) references this pattern
class VectorTest : public ::testing::Test {
 protected:
  void SetUp() override {    // Runs before each test in this suite
    v = {1, 2, 3};
  }

  void TearDown() override { // Runs after each test
    v.clear();
  }

  std::vector<int> v;
};

TEST_F(VectorTest, HasCorrectSize) {
  EXPECT_EQ(v.size(), 3);
}

TEST_F(VectorTest, ContainsValue) {
  EXPECT_TRUE(std::find(v.begin(), v.end(), 2) != v.end());
}

```

Your fixture class **must** inherit from `::testing::Test` and declare data members and helper methods in the `protected` section to allow access by the generated test classes.

## Internal Macro Expansion and Class Generation

Both `TEST` and `TEST_F` leverage the internal `GTEST_TEST_` macro defined in [`googletest/include/gtest/internal/gtest-internal.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-internal.h). This utility creates a concrete class that:

1. Inherits from either `::testing::Test` (for `TEST`) or your fixture class (for `TEST_F`)
2. Implements the `TestBody()` virtual method containing your test code
3. Registers the test using `GetTestTypeId()` to enable automatic discovery

The registration happens through a static initialization pattern that constructs a `TestInfo` object, linking your test to the appropriate test suite before `main()` executes.

## Working with Test Fixtures and Lifecycle Methods

Test fixtures in GoogleTest provide `SetUp()` and `TearDown()` virtual methods for resource management. When using `TEST_F`, the framework executes these methods automatically:

- **`SetUp()`** runs immediately before the `TestBody()` execution for each test
- **`TearDown()`** runs immediately after the test completes, even if assertions failed

These methods differ from a C++ constructor/destructor pair because they allow exception-safe cleanup and access to GoogleTest's assertion macros during initialization and destruction phases.

## Summary

- **`TEST`** macro creates simple test cases inheriting directly from `::testing::Test`, defined at lines 2206-2207 in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h)
- **`TEST_F`** macro generates fixture-based tests inheriting from user-defined classes, defined at lines 2238-2239 in the same header
- Both macros expand through `GTEST_TEST_` to create concrete C++ classes with `TestBody()` implementations
- Fixtures provide `SetUp()` and `TearDown()` hooks for per-test resource management
- The internal [`gtest-internal.h`](https://github.com/google/googletest/blob/main/gtest-internal.h) file provides registration utilities like `GetTestTypeId()` that enable automatic test discovery without manual registration code

## Frequently Asked Questions

### What is the difference between TEST and TEST_F in GoogleTest?

`TEST` creates a standalone test case that inherits directly from `::testing::Test` and requires no shared setup. `TEST_F` requires a user-defined fixture class inheriting from `::testing::Test` and provides that fixture's protected members and lifecycle methods to each test in the suite. Use `TEST` for isolated functions and `TEST_F` when multiple tests share common initialization code or resources.

### How does GoogleTest automatically discover and run test cases?

GoogleTest uses static initialization within the macro expansion to register tests. When the `TEST` or `TEST_F` macro expands, it creates a global `TestInfo` object referencing your test class. The constructor of this object adds the test to an internal registry before `main()` executes, allowing the `RUN_ALL_TESTS()` function to discover and execute all registered tests without explicit enumeration.

### When should I use a test fixture instead of a simple TEST macro?

Use a test fixture when multiple test cases share common setup code, expensive resource initialization, or have inter-test dependencies requiring cleanup. The `SetUp()` and `TearDown()` methods ensure fresh state for each test while avoiding code duplication. For truly independent unit tests with no shared state, prefer the simpler `TEST` macro to minimize test complexity and improve execution parallelization.

### Where are the TEST and TEST_F macros defined in the GoogleTest source code?

The `TEST` macro is defined at lines 2206-2207 and `TEST_F` at lines 2238-2239 in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h). Both macros delegate to internal implementations (`GTEST_TEST` and `GTEST_TEST_F`) that reside in the same file. Additional registration utilities referenced by these macros, including `GetTestTypeId()`, are located in [`googletest/include/gtest/internal/gtest-internal.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-internal.h).