googletest

Framework

google/googletest

Google's C++ testing and mocking framework for unit tests.

Overview

GoogleTest is a mature xUnit test framework for C++ that provides automatic test discovery, rich assertions, death tests, parameterized tests, and mocking support. Widely adopted across major open-source projects, it enables developers to write and run tests with flexibility and ease.

README Preview

# GoogleTest\n\n### Announcements\n\n#### Documentation Updates\n\nOur documentation is now live on GitHub Pages at\nhttps://google.github.io/googletest/. We recommend browsing the documentation on\nGitHub Pages rather than directly in the repository.\n\n#### Release 1.18.0\n\n[Release 1.18.0](https://github.com/google/googletest/releases/tag/v1.18.0) is\nnow available.\n\nThe 1.18.x branch\n[requires at least C++17](https://opensource.google/documentation/policies/cplusplus-support#c_language_standard).\n\n#### Continuous Integration\n\nWe use Google's internal systems for continuous integration.\n\n#### Coming Soon\n\n*   We are planning to take a dependency on\n    [Abseil](https://github.com/abseil/abseil-cpp).\n\n## Welcome to **GoogleTest**, Google's C++ test framework!\n\nThis repository is a merger of the formerly separate GoogleTest and GoogleMock\nprojects. These were so closely related that it makes sense to maintain and\nrelease them together.\n\n### Getting Started\n\nSee the [GoogleTest User's Guide](https://google.github.io/googletest/) for\ndocumentation. We recommend starting with the\n[GoogleTest Primer](https://google.github.io/googletest/primer.html).\n\nMore information about building GoogleTest can be found at\n[googletest/README.md](googletest/README.md).\n\n## Features\n\n*   xUnit test framework: \\n    Googletest is based on the [xUnit](https://en.wikipedia.org/wiki/XUnit)\n    testing framework, a popular architecture for unit testing.\n*   Test discovery: \\n    Googletest automatically discovers and runs your tests, eliminating the need\n    to manually register your tests.\n*   Rich set of assertions: \\n    Googletest provides a variety of assertions, such as equality, inequality,\n    exceptions, and more, making it easy to test your code.\n*   User-defined assertions: \\n    You can define your own assertions with Googletest, making it simple to\n    write tests that are specific to your code.\n*   Death tests: \\n    Googletest supp

FAQ (5)

Troubleshooting
Why does UnitTest::GetTestSuite(i) return the wrong test suite when --gtest_shuffle is enabled in GoogleTest?

UnitTestImpl::GetTestSuite(int i) computes the shuffled position from test_suite_indices_, but incorrectly indexes test_suites_ with the original i. In googletest/src/gtest-internal-inl.h, change:

return test_suites_[i];

to:

return test_suites_[index];

The mutable accessor already uses index correctly. Rebuild GoogleTest and relink your test binary after applying the patch. This bug existed since commit bd851333 and was observed on main at commit 08da6214.

GitHub Issue #5040
Troubleshooting
Why does GoogleTest JSON output corrupt UTF-8 property values by escaping each byte as \u00XX?

This happens on platforms where plain char is signed. In JsonUnitTestResultPrinter::EscapeJson, UTF-8 bytes from 0x80 through 0xFF become negative, so the check ch < ' ' treats them as JSON control characters and escapes each byte separately.

Fix it by interpreting the byte as unsigned before the control-character check:

const unsigned char ch = static_cast<unsigned char>(str[i]);

if (ch < ' ') {
  // Emit the needed \u00XX escape only for real ASCII control characters.
}

Bytes with the high bit set should be left untouched so valid UTF-8 sequences are written as UTF-8. Continue escaping JSON-required characters such as " and \. Then rebuild libgtest and libgtest_main, or upgrade to a GoogleTest release containing the fix for issue #5081.

As a temporary workaround, avoid non-ASCII characters in RecordProperty, test names, file paths, and failure messages, or post-process the JSON to reconstruct the incorrectly split UTF-8 sequences.

GitHub Issue #5081
Troubleshooting
How to fix GoogleTest LNK2038 'MTd_StaticDebug' does not match 'MDd_DynamicDebug' with CMake FetchContent?

The error means GoogleTest is being built with the static debug C runtime (/MTd), while your executable uses the dynamic debug C runtime (/MDd).

Upgrade GoogleTest to a main commit containing the fix for issue #5042. The fix only overrides CRT settings when GoogleTest is the top-level project, so FetchContent and add_subdirectory() consumers inherit the parent project's CRT setting.

If you cannot update immediately, force GoogleTest to use the shared CRT before declaring it:

set(gtest_force_shared_crt ON CACHE BOOL "Use shared CRT for GoogleTest" FORCE)

include(FetchContent)
FetchContent_Declare(
  googletest
  GIT_REPOSITORY https://github.com/google/googletest
  GIT_TAG        main
)
FetchContent_MakeAvailable(googletest)

Then delete the build directory and reconfigure:

Remove-Item -Recurse -Force build
cmake -S . -B build
cmake --build build

Alternatively, to consistently use the static CRT everywhere, set this before creating your targets and adding GoogleTest:

set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")

GitHub Issue #5042
Troubleshooting
How to fix the undefined reference to `regcompA` error when building GoogleTest on Linux or Fedora?

The error occurs when a MinGW or Cygwin regex.h header leaks into the Linux include path. It macro-remaps POSIX functions such as regcomp, regexec, and regfree to Windows-style names like regcompA, which do not exist in glibc. CMake and GCC versions are not the cause.

1. Check for leaked include paths:

echo "$CPATH $C_INCLUDE_PATH $CPLUS_INCLUDE_PATH $CMAKE_INCLUDE_PATH"
echo | g++ -x c++ -E -Wp,-v -

Look for MinGW, Cygwin, w64-mingw32, or cross-compiler include directories.

2. Remove them from the environment and rebuild from scratch:

unset CPATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH CMAKE_INCLUDE_PATH
rm -rf build
cmake -S . -B build
cmake --build build

If the bad include path cannot be removed immediately, force GoogleTest to use its simple regex implementation instead of POSIX regex:

rm -rf build
cmake -S . -B build -DCMAKE_CXX_FLAGS='-DGTEST_HAS_POSIX_RE=0'
cmake --build build

For a permanent fix, update GoogleTest to a newer release or commit containing the issue #5001 fix, which detects macro-redefined POSIX regex symbols and automatically falls back to SIMPLE_RE.

GitHub Issue #5001
Troubleshooting
How do I fix the -Wc++17-attribute-extensions warning for [[maybe_unused]] when building GoogleTest in C++14?

GoogleTest 1.15.x requires C++17, so build it with C++17 instead of C++14:

CXXFLAGS="-Werror -Wall -Wextra -Wpedantic" cmake -S . -B /tmp/gtestbuildfolder -DCMAKE_CXX_STANDARD=17 -DCMAKE_CXX_STANDARD_REQUIRED=ON
cmake --build /tmp/gtestbuildfolder

The warning occurs because Apple Clang exposes [[maybe_unused]] in C++14 as a compiler extension, even though the attribute was introduced in C++17.

If you must compile an older GoogleTest version in C++14, patch the GTEST_INTERNAL_HAVE_CPP_ATTRIBUTE macro so it also checks __cplusplus:

#if defined(__has_cpp_attribute)
#define GTEST_INTERNAL_HAVE_CPP_ATTRIBUTE(x) (__cplusplus >= __has_cpp_attribute(x))
#else
#define GTEST_INTERNAL_HAVE_CPP_ATTRIBUTE(x) 0
#endif

The preferred fix is to use C++17 or upgrade GoogleTest.

GitHub Issue #4605