# How to Set Up GoogleTest in a C++ Project: A Complete CMake Guide

> Easily set up GoogleTest in your C++ project using CMake FetchContent. Download, build, and link GoogleTest to run your unit tests efficiently with this complete guide.

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

---

**Use CMake's `FetchContent` module to automatically download and build GoogleTest alongside your project, then link your test executable against `gtest_main` to get a default `main()` function and the full testing API.**

Setting up GoogleTest in a C++ project requires only a few lines of CMake configuration, as the `google/googletest` repository provides a ready-made build system that works across Linux, macOS, and Windows. The framework is implemented as a static or shared library with all public headers located in `include/gtest/` and implementation details under `src/`, making it straightforward to integrate into existing codebases without runtime dependencies beyond the C++ standard library.

## Prerequisites

Before integrating GoogleTest, ensure your build environment meets the following requirements defined in [`googletest/README.md`](https://github.com/google/googletest/blob/main/googletest/README.md):

- **C++17 or later** – The current branch requires a minimum C++17 standard for compilation.
- **CMake 3.14 or newer** – Required for modern `FetchContent` support and reliable cross-platform builds.

## Method 1: Embedding with FetchContent (Recommended)

The most robust way to set up GoogleTest is using CMake's `FetchContent` module, which downloads the source automatically during the configuration phase. This approach guarantees that the same compiler flags and C runtime library (CRT) settings are used for both the library and your test binaries, avoiding mismatched runtime-library errors on Windows.

Add the following to your root [`CMakeLists.txt`](https://github.com/google/googletest/blob/main/CMakeLists.txt):

```cmake
cmake_minimum_required(VERSION 3.14)
project(MyProject LANGUAGES CXX)

include(FetchContent)
FetchContent_Declare(
  googletest
  URL https://github.com/google/googletest/archive/refs/tags/v1.18.0.zip
)

# For Windows: Prevent overriding the parent project's compiler/linker settings

set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)

FetchContent_MakeAvailable(googletest)

enable_testing()

add_executable(my_tests test.cpp)
target_link_libraries(my_tests gtest_main)
add_test(NAME my_tests COMMAND my_tests)

```

This configuration creates the `gtest` and `gtest_main` targets directly in your build tree without requiring a separate installation step.

## Method 2: Standalone Build as a Subdirectory

If you prefer to manage the GoogleTest source yourself—either by cloning the repository or adding it as a Git submodule—you can include it via `add_subdirectory()`. This method is useful when you need to modify the framework or work in environments with restricted internet access.

First, clone the repository:

```bash
git clone https://github.com/google/googletest.git

```

Then reference it in your [`CMakeLists.txt`](https://github.com/google/googletest/blob/main/CMakeLists.txt):

```cmake
cmake_minimum_required(VERSION 3.14)
project(MyTests LANGUAGES CXX)

add_subdirectory(/path/to/googletest)   # Adjust path to your clone

add_executable(example_test example_test.cpp)
target_link_libraries(example_test gtest_main)
add_test(NAME example_test COMMAND example_test)

```

Building this generates static libraries `libgtest.a` and `libgtest_main.a` (or their shared counterparts) in your build directory.

## Linking the Test Libraries

GoogleTest provides two primary library targets. Choose the one that fits your needs:

- **`gtest`** – Links only the core testing framework. You must provide your own `main()` function that initializes the framework and runs the tests.
- **`gtest_main`** – Includes everything in `gtest` plus a default `main()` implementation. This is the recommended choice for most projects unless you need custom initialization logic.

Both targets automatically handle header include paths, so you only need to link against the library:

```cmake
target_link_libraries(my_tests gtest_main)  # Or gtest if you define main() yourself

```

## Writing and Running Your First Test

Create a test source file that includes `<gtest/gtest.h>` and uses the `TEST` macro to define test cases:

```cpp
#include <gtest/gtest.h>

// Simple function to test
int Add(int a, int b) { return a + b; }

TEST(Addition, HandlesPositiveNumbers) {
  EXPECT_EQ(Add(2, 3), 5);
  EXPECT_GT(Add(10, 5), 0);
}

```

To execute tests, use either **CTest** (CMake's test driver) or run the binary directly:

```bash

# Via CTest (runs all tests added with add_test())

ctest

# Direct execution (provides rich output with filters and repetition options)

./my_tests

```

When running the binary directly, GoogleTest parses command-line arguments to support filtering (`--gtest_filter`), repeating tests (`--gtest_repeat`), and generating XML reports (`--gtest_output`).

## Summary

- **GoogleTest** is a header-only C++ testing framework packaged with CMake build scripts in the `google/googletest` repository.
- **FetchContent** is the recommended integration method for new projects, ensuring consistent compiler settings and automatic downloads.
- **C++17** and **CMake 3.14+** are hard requirements for recent versions.
- Link against **`gtest_main`** to use the default test runner, or **`gtest`** if you define a custom `main()` function.
- All public symbols are located in `include/gtest/` (particularly [`include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/include/gtest/gtest.h)), while implementation resides in `src/gtest-all.cc`.

## Frequently Asked Questions

### What is the minimum C++ standard required to use GoogleTest?

GoogleTest requires **C++17** or later as of the current main branch. This is enforced in the [`CMakeLists.txt`](https://github.com/google/googletest/blob/main/CMakeLists.txt) and documented in [`googletest/README.md`](https://github.com/google/googletest/blob/main/googletest/README.md). Attempting to compile with an older standard will result in compilation errors, particularly when using modern standard library features.

### How do I prevent "mismatched C runtime library" errors on Windows when using GoogleTest?

Set the `gtest_force_shared_crt` CMake variable to `ON` before calling `FetchContent_MakeAvailable()` or `add_subdirectory()`. According to the source code in [`include/gtest/internal/gtest-port.h`](https://github.com/google/googletest/blob/main/include/gtest/internal/gtest-port.h), this flag ensures that GoogleTest uses the same C runtime library (static or dynamic) as your parent project, which is essential for avoiding linker errors on Windows.

### Should I link my tests against `gtest` or `gtest_main`?

Link against **`gtest_main`** unless you need to implement custom initialization code, environment setup, or command-line argument parsing in your test entry point. The `gtest_main` target includes a default `main()` function that initializes the framework with `::testing::InitGoogleTest()` and returns `RUN_ALL_TESTS()`, saving you from writing boilerplate code.

### Can I use GoogleTest without CMake?

Yes, though CMake is the officially supported and recommended build system. You can manually compile `src/gtest-all.cc` (which includes all implementation files) along with your test sources, or create platform-specific project files. However, using the provided [`CMakeLists.txt`](https://github.com/google/googletest/blob/main/CMakeLists.txt) handles platform-specific configuration flags and dependencies automatically, making it the most reliable approach for cross-platform development.