# GoogleTest Admin & Architecture Guide

This guide is for build engineers, toolchain owners, library integrators, and
contributors who need to understand GoogleTest's architecture, integrate it into
larger build systems, control it in CI, harden it, and reason about its
internals. It complements the [User Guide](google__googletest__UserGuide.md),
which covers day-to-day test authoring.

GoogleTest is a **header-rich, statically-linked C++ library** with no runtime
services, no network surface, and no daemon. Its "operations" are therefore
build-time integration, CI configuration, and version management rather than
deployment in the conventional sense.

---

## 1. Executive Summary

| Aspect | Detail |
| :----- | :----- |
| What it is | Google's C++ unit-testing + mocking framework (gtest + gmock), merged into one repo |
| Language standard | C++17 minimum (the `1.17.x` line) |
| Distribution | Source; consumed via CMake FetchContent, Bazel (BCR), or pkg-config; compiled into the consumer |
| Runtime dependencies | **None required.** Optional: Abseil + RE2 (richer regex, flags, stack traces) |
| Build systems | Bazel (first-class, maintainer-used) and CMake (community-maintained) |
| Supported platforms | Linux, macOS, Windows, plus POSIX, Cygwin, QNX, FreeBSD, OpenBSD; Fuchsia unofficial |
| Threading | Thread-safe where `pthreads` is available; assertions from multiple threads are unsupported on some systems (e.g. Windows) |
| License | BSD 3-Clause (`notice`) |
| Output formats | Console (colored), JUnit XML, JSON |

**Operational posture:** the only "production" concern is *correctness of
integration* — pinning a version, wiring it into the build, and configuring CI
flags. There is nothing to deploy, monitor, or secure at runtime in the usual
sense, because GoogleTest code only ever runs inside *your* test binaries, never
in shipped production binaries (assuming you keep test targets `testonly`).

---

## 2. Architecture

### 2.1 Two libraries, one repository

The repository is a merger of two formerly separate projects:

```
googletest/  (repo root)
├── googletest/      <- gtest: the testing framework
│   ├── include/gtest/        public headers (the macro + class API)
│   │   └── internal/         implementation-detail headers (not a public API)
│   ├── src/                  the .cc implementation
│   ├── samples/              worked examples (sample1..sample10)
│   ├── cmake/                CMake helper files + .pc.in templates
│   └── test/                 the framework's own self-tests
├── googlemock/      <- gmock: the mocking library (depends on gtest)
│   ├── include/gmock/        public headers
│   │   └── internal/         implementation-detail headers
│   ├── src/                  the .cc implementation
│   └── test/                 self-tests
├── docs/            <- the canonical user/reference documentation (Jekyll site)
├── ci/              <- presubmit scripts (linux/macos/windows)
├── CMakeLists.txt   <- top-level CMake (community-maintained)
├── BUILD.bazel, MODULE.bazel, WORKSPACE*  <- Bazel build
└── .clang-format, CONTRIBUTING.md, LICENSE
```

> [!NOTE]
> The `googletest/docs/README.md` and `googlemock/docs/README.md` are stubs that
> redirect to the top-level `docs/` directory — that is the single source of the
> documentation, also published at <https://google.github.io/googletest/>.

### 2.2 Component model

GoogleTest has no servers or processes; its "architecture" is a set of
cooperating classes and a registration mechanism.

```
                 InitGoogleTest(argc, argv)   parses --gtest_* flags
                            │
                            ▼
   TEST/TEST_F/TEST_P  ──►  auto-registration  ──►  UnitTest (singleton)
   macros generate            (static init)             │
   Test subclasses                                      ▼
                                              RUN_ALL_TESTS()
                                                        │
        ┌───────────────────────────────────────────────┤
        ▼                          ▼                      ▼
   TestSuite objects   ◄── owns ── TestInfo objects   TestEventListeners
        │                          │                      │ (fan-out)
        ▼                          ▼                      ▼
   SetUpTestSuite()        Test fixture lifecycle   default printer +
   TearDownTestSuite()     (ctor→SetUp→body→TearDown→dtor)  XML/JSON generator
        │
        ▼
   TestResult / TestPartResult  (per-assertion outcomes)
```

Key runtime types (all in `namespace testing`, declared in
`googletest/include/gtest/gtest.h`):

| Type | Role |
| :--- | :--- |
| `UnitTest` | Singleton holding the whole test program's state; `UnitTest::GetInstance()` |
| `TestSuite` | A group of tests; tracks pass/fail/skip counts and timing |
| `TestInfo` | Metadata for one test (suite name, name, file, line, type/value params) |
| `Test` | Abstract base all fixtures inherit from; defines `SetUp`/`TearDown` hooks |
| `TestResult` / `TestPartResult` | Outcome of a test / a single assertion |
| `TestEventListener` / `TestEventListeners` | The observer API for progress + output |
| `Environment` | Global program-level setup/teardown |
| `AssertionResult` | Carries success/failure + message; the basis of custom predicates |

### 2.3 Registration and execution flow

1. `TEST*` macros expand to a class deriving from `Test` (or a fixture) and a
   static registrar that adds a `TestInfo` to the global `UnitTest`. **No manual
   test listing is ever required.**
2. `InitGoogleTest(&argc, argv)` parses and strips recognized `--gtest_*` flags.
3. `RUN_ALL_TESTS()` saves flag state, then for each test: constructs the
   fixture, calls `SetUp()`, runs the body, calls `TearDown()`, destroys the
   fixture, and restores flag state. A fatal failure skips remaining steps of
   that test only.
4. Listeners receive `On*Start`/`On*End` events; the default console printer and
   XML/JSON generators are themselves listeners and can be removed or replaced.

### 2.4 The event-listener extension point

`TestEventListener` is the primary extension API. Subclass
`EmptyTestEventListener` and override only the events you care about
(`OnTestStart`, `OnTestPartResult`, `OnTestEnd`, `OnTestIterationStart`, etc.),
then `listeners().Append(...)`. This is how teams build custom reporters, TAP
output, GUIs, leak checkers, or database sinks. The default text printer can be
detached via `listeners().Release(listeners().default_result_printer())`.

> [!IMPORTANT]
> A listener that handles `OnTestPartResult()` must not itself generate
> failures, and must be ordered *before* listeners that can. Failures raised in
> `OnTestPartResult()` would recurse.

### 2.5 Death-test architecture

Death tests spawn a child process to verify a crash/exit:

- **POSIX:** `fork()` (or `clone()` on Linux) the child. In `"fast"` style the
  statement runs immediately in the child; in `"threadsafe"` style the child
  re-executes the test binary with flags that run only the single death test.
- **Windows:** the child is spawned with `CreateProcess()` and re-executes the
  binary — equivalent to POSIX `"threadsafe"`.

`clone()` (not `fork()`) is used on Linux because forking with multiple parent
threads risks the child hanging. Suites containing death tests should be named
`*DeathTest` so GoogleTest runs them before other suites.

---

## 3. Build & Integration Mastery

### 3.1 CMake options

The top-level `CMakeLists.txt` exposes these cache options:

| Option | Default | Effect |
| :----- | :------ | :----- |
| `BUILD_GMOCK` | `ON` | Build the googlemock subproject (which also builds googletest). Set `OFF` to build gtest only. |
| `INSTALL_GTEST` | `ON` | Enable `install` rules. Turn **OFF** when embedding GoogleTest inside a larger project so you don't pollute the install tree. |
| `GTEST_HAS_ABSL` | `OFF` | Use Abseil + RE2 (must be added to the build separately via `find_package(absl)` / `find_package(re2)`). |
| `gtest_force_shared_crt` | (per-project) | On Windows/MSVC, force use of the shared C runtime so settings don't clash with the parent project. |

```cmake
cmake -S . -B build -DBUILD_GMOCK=OFF -DINSTALL_GTEST=OFF
```

> [!NOTE]
> `CMAKE_CXX_EXTENSIONS` is forced **OFF** by the build except on Cygwin, MSYS,
> and QNX. Minimum CMake is **3.16** for building GoogleTest itself; consumers
> using `FetchContent` need **3.14+**.

The imported/installed targets are `GTest::gtest`, `GTest::gtest_main`,
`GTest::gmock`, `GTest::gmock_main`. The CMake `GoogleTest` module provides
`gtest_discover_tests(<target>)` to register each test with CTest.

> [!CAUTION]
> CMake support is **community-based — the maintainers do not use CMake
> internally** (per the comment at the top of `CMakeLists.txt`). For the most
> robust experience, Bazel is the reference build. Track CMake-specific issues
> (e.g. #4616, #4718, #4925, #3771) accordingly.

### 3.2 Bazel

The canonical build. `MODULE.bazel` declares the module and its direct deps:

```python
module(name = "googletest", version = "head", compatibility_level = 1)

bazel_dep(name = "abseil-cpp", version = "20260107.0")
bazel_dep(name = "platforms",  version = "0.0.11")
bazel_dep(name = "re2",        version = "2025-11-05.bcr.1")
bazel_dep(name = "rules_cc",   version = "0.2.8")
bazel_dep(name = "rules_python", version = "1.3.0", dev_dependency = True)
```

Consumers add `bazel_dep(name = "googletest", version = "1.17.0")` and depend on
`@googletest//:gtest` and `@googletest//:gtest_main`.

**Targets defined in `BUILD.bazel`:**

| Target | Purpose |
| :----- | :------ |
| `:gtest` | The combined gtest + gmock library (use for any test) |
| `:gtest_main` | `main()` for tests (`srcs = googlemock/src/gmock_main.cc`) — note the unified main lives in gmock |
| `:gtest_for_library` | `testonly` alias of `:gtest` for libraries that are themselves test-only |
| `:gtest_prod` | Header-only target exposing the `FRIEND_TEST` macro for production code |
| `:gtest_sample_lib`, `:gtest_samples`, `:sample9_unittest`, `:sample10_unittest` | The bundled samples |

**Platform-aware build logic (`select()` in `BUILD.bazel`):**

- `copts`/`linkopts` add `-pthread` everywhere except QNX and Windows; QNX adds
  `-lregex`; FreeBSD/OpenBSD add `-lm -pthread`.
- `config_setting`s exist for `qnx`, `windows`, `freebsd`, `openbsd`, `fuchsia`,
  `msvc_compiler`, and `has_absl`.
- With `--define absl=1`, `GTEST_HAS_ABSL=1` is defined and the Abseil/RE2 deps
  are linked (flat_hash_set, failure_signal_handler, stacktrace, symbolize,
  flags, strings, re2).
- Fuchsia (unofficial) links `@fuchsia_sdk//pkg/fdio` + `pkg/zx` so
  `gtest-death-test.cc`'s `EXPECT_DEATH` compiles.

> [!TIP]
> Pass the C++ standard explicitly to Bazel: `--cxxopt=-std=c++17` (Clang/GCC) or
> `--cxxopt=/std:c++17` (MSVC). The default compiler setting may be older than
> C++17.

### 3.3 pkg-config

GoogleTest installs `.pc` templates (`gtest.pc.in`, `gtest_main.pc.in`,
`gmock.pc.in`, `gmock_main.pc.in`). The generated `gtest.pc` looks like:

```text
Name: gtest
Description: GoogleTest (without main() function)
Version: <PROJECT_VERSION>
Libs: -L${libdir} -lgtest -lpthread
Cflags: -I${includedir} -DGTEST_HAS_PTHREAD=1
```

> [!IMPORTANT]
> Always consume `Cflags`/`Libs` *whole* (`${GTEST_CFLAGS}` / `${GTEST_LDFLAGS}`
> in CMake). Splitting them into include-dirs and libraries drops `-pthread` and
> `-DGTEST_HAS_PTHREAD=1`, which causes link errors or subtle threading bugs.
> For cross-compilation, set `PKG_CONFIG_SYSROOT_DIR` and `PKG_CONFIG_LIBDIR` so
> `-I`/`-L` paths are rewritten into the sysroot.

### 3.4 Choosing libraries

| You build | Link |
| :-------- | :--- |
| A test with GoogleTest's `main()` | `gtest_main` |
| A test with your own `main()` | `gtest` |
| A test using mocks + ready `main()` | `gmock_main` |
| A test using mocks + own `main()` | `gmock` (which pulls in `gtest`) |
| Production code needing `FRIEND_TEST` | `gtest_prod` (header only) |

---

## 4. Configuration Reference

GoogleTest is configured at three layers: **compile-time macros**,
**command-line flags**, and **environment variables**. Flags override the
matching environment variable.

### 4.1 Runtime flags and environment variables

| Flag | Env var | Default | Purpose |
| :--- | :------ | :------ | :------ |
| `--gtest_list_tests` | — | off | List tests and exit (overrides other flags) |
| `--gtest_filter=PAT` | `GTEST_FILTER` | `*` | Run only matching tests |
| `--gtest_also_run_disabled_tests` | `GTEST_ALSO_RUN_DISABLED_TESTS` | off | Include `DISABLED_` tests |
| `--gtest_fail_fast` | `GTEST_FAIL_FAST` | off | Stop at first failure |
| `--gtest_fail_if_no_test_linked` | `GTEST_FAIL_IF_NO_TEST_LINKED` | off | Fail if no test case is linked in |
| `--gtest_fail_if_no_test_selected` | `GTEST_FAIL_IF_NO_TEST_SELECTED` | off | Fail if no test actually ran |
| `--gtest_repeat=N` | `GTEST_REPEAT` | 1 | Repeat tests N times (`-1`=forever) |
| `--gtest_shuffle` | `GTEST_SHUFFLE` | off | Randomize test order |
| `--gtest_random_seed=N` | `GTEST_RANDOM_SEED` | 0 (time-based) | Fix shuffle seed (0–99999) |
| `--gtest_recreate_environments_when_repeating` | — | true | Re-run global env setup/teardown each iteration |
| `--gtest_color=(yes\|no\|auto)` | `GTEST_COLOR` | auto | Colored output |
| `--gtest_brief=1` | `GTEST_BRIEF` | 0 | Print only failures |
| `--gtest_print_time=0` | `GTEST_PRINT_TIME` | 1 | Suppress per-test timing |
| `--gtest_print_utf8=0` | `GTEST_PRINT_UTF8` | 1 | Suppress UTF-8 rendering of strings |
| `--gtest_output=(xml\|json)[:path]` | `GTEST_OUTPUT` | none | Emit XML/JSON report |
| `--gtest_break_on_failure` | `GTEST_BREAK_ON_FAILURE` | off | Trap into debugger on failure |
| `--gtest_catch_exceptions=0` | `GTEST_CATCH_EXCEPTIONS` | 1 | Whether GoogleTest catches test-thrown exceptions |
| `--gtest_death_test_style=(fast\|threadsafe)` | — | fast | Death-test execution style |
| `--gmock_catch_leaked_mocks=0` | — | 1 | Report leaked mocks as failures |
| `--gmock_verbose=(info\|warning\|error)` | — | warning | gMock log verbosity |

**Sharding env vars** (set by your test runner, no flag equivalent):
`GTEST_TOTAL_SHARDS`, `GTEST_SHARD_INDEX`, `GTEST_SHARD_STATUS_FILE`.

**Other env-only controls:** `TEST_PREMATURE_EXIT_FILE` (premature-exit
detection protocol), `TEST_SHARD_STATUS_FILE`.

> [!NOTE]
> For flags to take effect, your `main()` must call
> `testing::InitGoogleTest(&argc, argv)` before `RUN_ALL_TESTS()`. Run any test
> binary with `--help` for the authoritative, version-specific flag list.

### 4.2 Compile-time customization points

GoogleTest supports deep customization via macros, intended for unusual
platforms. The `internal/custom/` directories are the official injection points
(`googletest/include/gtest/internal/custom/`,
`googlemock/include/gmock/internal/custom/`):

| Header / macro | Customizes |
| :------------- | :--------- |
| `GTEST_OS_STACK_TRACE_GETTER_` | Stack-trace getter implementation |
| `GTEST_CUSTOM_TEMPDIR_FUNCTION_` | Override `testing::TempDir()` |
| `GTEST_LOG_(severity)`, `GTEST_CHECK_(condition)` | Logging primitives (plus `LogToStderr`/`FlushInfoLog`) |
| `GTEST_HAS_NOTIFICATION_`, `GTEST_HAS_MUTEX_AND_THREAD_LOCAL_` | Supply your own threading primitives |
| `GTEST_API_` | Symbol-export specifier |
| `GMOCK_DECLARE_*_` / `GMOCK_DEFINE_*_` / `GMOCK_FLAG_GET/SET` | Flag plumbing for gmock |

Feature-detection macros include `GTEST_HAS_PTHREAD`, `GTEST_HAS_ABSL`,
`GTEST_USES_SIMPLE_RE` / `GTEST_USES_POSIX_RE` (which regex engine is active),
`GTEST_OS_*` (platform), and `GTEST_HAS_CXXABI_H_`.

> [!TIP]
> Regex engine selection matters for death-test matchers and `MatchesRegex`:
> with Bazel+Abseil you get **RE2** syntax; on POSIX you get **POSIX extended**
> regex; on Windows you get GoogleTest's **simple** engine (no `|`, `()`, `[]`,
> or `{m,n}`). For portable death tests, use only the simple-engine subset or
> `#if` on `GTEST_USES_*_RE`.

### 4.3 XML / JSON report schema

`--gtest_output=xml` produces JUnit-style XML where `<testsuites>` = the program,
`<testsuite>` = a GoogleTest suite, `<testcase>` = a test function, and each
`<failure>` = one failed assertion. Attributes include `tests`, `failures`,
`errors`, `time`, `timestamp`, `file`, `line`. JSON output mirrors the same
shape and conforms to a documented JSON Schema / Proto3 message.

> [!IMPORTANT]
> The exact JSON document format is explicitly **subject to change** — don't
> build brittle parsers against undocumented fields. XML is the more stable
> integration target (it maps to the long-standing `junitreport` Ant format).

Per-test metadata can be injected via `RecordProperty("key", value)`, surfaced
as XML attributes (key must be a valid XML attribute name and not collide with
`name`, `file`, `line`, `status`, `time`, `classname`, `type_param`,
`value_param`).

---

## 5. Operations & CI

### 5.1 Continuous integration

The repo's own CI lives in `ci/` (`linux-presubmit.sh`, `macos-presubmit.sh`,
`windows-presubmit.bat`); the project notes it also uses Google's internal CI.
For *your* projects, the standard pattern is:

1. Build test binaries with your build system (Bazel `cc_test` or CMake +
   `gtest_discover_tests`).
2. Run via the native runner (`bazel test` / `ctest`) or invoke the binaries
   directly with `--gtest_output=xml:results/` for CI report ingestion.
3. Shard across machines with `GTEST_TOTAL_SHARDS` / `GTEST_SHARD_INDEX`.
4. Use `--gtest_shuffle` to surface inter-test coupling, and
   `--gtest_repeat=N --gtest_break_on_failure` to chase flakes.

### 5.2 Self-testing layout

GoogleTest tests itself extensively. Each library has a `test/` tree mixing C++
unit tests (`*_test.cc`) and Python-driven golden-output tests
(`googletest-output-test.py` + `*_golden*.txt`). The samples double as
integration tests (`gtest_samples`, `sample9_unittest`, `sample10_unittest` in
Bazel).

> [!NOTE]
> One open issue (#3943) notes `googletest-output-test.py` is not fully Python 3
> ready — relevant if you build/run the framework's own Python-based tests in a
> Python-3-only environment.

### 5.3 Version management

| Practice | Why |
| :------- | :-- |
| Pin to a specific commit/release | Reproducible builds; the AI-doc model is diff-from-pinned |
| Update the pin deliberately and often | Picks up new-compiler fixes (GCC 15, MSVC) |
| Keep WORKSPACE and MODULE.bazel versions in sync | The MODULE file comments require it |
| Mark test targets `testonly` | Keeps GoogleTest out of production binaries |

The current release line is **1.17.0** (C++17+). The repo `main` builds as
version `head` in Bazel; CMake stamps `GOOGLETEST_VERSION`.

> [!CAUTION]
> The project announces a **planned dependency on Abseil** is coming. Today
> Abseil/RE2 are optional (`GTEST_HAS_ABSL`); plan for them potentially becoming
> required in a future major version, and verify your build can supply them.

---

## 6. Security Analysis

GoogleTest's threat surface is unusually small because it is a build-time,
in-process testing library with no network, no persistence, and no daemon.

| Vector | Assessment |
| :----- | :--------- |
| Network | **None.** No sockets, no listeners, no remote calls. |
| Untrusted input | Test inputs are author-supplied code. `--gtest_filter`, `--gtest_output` paths, and env vars come from the CI operator, not external users. |
| File writes | XML/JSON reports and the premature-exit file are written to operator-specified paths. Ensure CI runs with least privilege and writes to a sandboxed workspace. |
| Process spawning | Death tests `fork`/`clone`/`CreateProcess` a child that re-executes the test binary. Only triggered by author-written death tests. |
| Supply chain | The real risk surface: a compromised pinned archive/registry entry would be compiled into your test binaries. Pin by commit hash and verify provenance via the Bazel Central Registry. |
| Production leakage | GoogleTest code must not ship in production. Keep test/mocks `testonly`; never link `gtest`/`gmock` into release artifacts. |

> [!IMPORTANT]
> The `gtest_force_shared_crt` / CRT settings and `--gtest_catch_exceptions`
> affect crash behavior, not security. The one genuine hardening control is
> **supply-chain hygiene**: pin versions by hash, restrict who can bump the pin,
> and run CI test execution under least-privilege sandboxes (death tests spawn
> processes; reports write files).

> [!CAUTION]
> On Windows, the statically-initialized GoogleTest singleton allocates on the
> heap, so the VC++ leak detector reports false positives at exit. This is
> benign — suppress with `_CrtMemCheckpoint` / `_CrtMemDumpAllObjectsSince`. Do
> not mistake it for a real leak in your code.

---

## 7. Internals & Module Reference

### 7.1 gtest source modules (`googletest/src/`)

| File | Responsibility |
| :--- | :------------- |
| `gtest.cc` | Core: `UnitTest`, `TestSuite`, `TestInfo`, flag parsing, the console printer, XML/JSON generation, `RUN_ALL_TESTS` machinery (largest module) |
| `gtest-death-test.cc` | Death-test execution (fork/clone/CreateProcess, child re-exec) |
| `gtest-filepath.cc` | Path handling for outputs and temp dirs |
| `gtest-matchers.cc` | The matcher base machinery shared with gmock |
| `gtest-port.cc` | Platform-abstraction layer (threads, regex, mutexes, time) |
| `gtest-printers.cc` | The extensible value printer |
| `gtest-assertion-result.cc` | `AssertionResult` implementation |
| `gtest-test-part.cc` | `TestPartResult` |
| `gtest-typed-test.cc` | Typed / type-parameterized test support |
| `gtest-internal-inl.h` | Internal shared declarations |
| `gtest-all.cc` | Unity build aggregating all of the above |
| `gtest_main.cc` | A default `main()` (the Bazel `gtest_main` uses gmock's main instead) |

### 7.2 gtest public headers (`googletest/include/gtest/`)

`gtest.h` is the umbrella include. Companions: `gtest-assertion-result.h`,
`gtest-death-test.h`, `gtest-matchers.h`, `gtest-message.h`,
`gtest-param-test.h`, `gtest-printers.h`, `gtest-spi.h` (the
"catching-framework-failures" API), `gtest-test-part.h`, `gtest-typed-test.h`,
`gtest_pred_impl.h`, and `gtest_prod.h` (the `FRIEND_TEST` macro for production
code). The `internal/` subtree (`gtest-internal.h`, `gtest-port.h`,
`gtest-param-util.h`, `gtest-type-util.h`, `gtest-death-test-internal.h`, etc.)
is **not** a stable public API.

### 7.3 gmock source modules (`googlemock/src/`)

| File | Responsibility |
| :--- | :------------- |
| `gmock-spec-builders.cc` | `EXPECT_CALL`/`ON_CALL` expectation engine, sequencing, verification |
| `gmock-matchers.cc` | Built-in matcher implementations |
| `gmock-cardinalities.cc` | `Times()` cardinalities (`AtLeast`, `AnyNumber`, etc.) |
| `gmock-internal-utils.cc` | Shared helpers |
| `gmock.cc` | Library init + flag handling (`--gmock_*`) |
| `gmock-all.cc` | Unity build |
| `gmock_main.cc` | The unified `main()` used by both `gtest_main` and `gmock_main` |

### 7.4 gmock public headers (`googlemock/include/gmock/`)

`gmock.h` (umbrella), plus `gmock-actions.h`, `gmock-cardinalities.h`,
`gmock-function-mocker.h` (the `MOCK_METHOD` machinery), `gmock-matchers.h`,
`gmock-more-actions.h`, `gmock-more-matchers.h`, `gmock-nice-strict.h`
(`NiceMock`/`NaggyMock`/`StrictMock`), and `gmock-spec-builders.h`. The
`internal/` subtree (`gmock-internal-utils.h`, `gmock-port.h`, `gmock-pp.h` — the
preprocessor metaprogramming behind `MOCK_METHOD`) is implementation detail.

### 7.5 Threading model

GoogleTest is designed to be thread-safe and *is* thread-safe where `pthreads`
is available. On platforms lacking it (notably Windows), using GoogleTest
**assertions from two threads concurrently is unsafe**. In practice most tests
assert from the main thread; `EXPECT_NO_FATAL_FAILURE` and the SPI failure-catch
macros only observe failures in the calling thread.

---

## 8. Code Quality & Conventions

| Aspect | Observation |
| :----- | :---------- |
| Style | Google C++ Style Guide; enforced by the repo's `.clang-format` |
| Naming | Tests/suites avoid underscores (compiler-reserved-identifier safety) |
| Portability | Heavy `select()`/macro abstraction (`gtest-port`) isolates platform differences; works with and without exceptions |
| No-exceptions design | Fatal assertions return rather than throw — hence the void-function constraint |
| Public vs internal | Clean separation: `include/.../internal/` and `internal/custom/` are explicitly not public API |
| Self-documentation | The `docs/` tree is exhaustive and authoritative; samples are runnable and CI-checked |
| Header organization | One umbrella header per library plus focused sub-headers; `*-all.cc` unity builds |

---

## 9. Known Issues & Improvement Areas

Drawn from the project's open community issues at the documented commit.

| Theme | Issues | Notes |
| :---- | :----- | :---- |
| New-compiler breakage | #4965 (deleted function), #4881 (GCC 15.2 attribute ordering), #4759 (GCC 15 `MOCK_METHOD` + `std::expected`) | Track latest release for fixes |
| CMake friction | #4616, #4718 (`BUILD_SHARED_LIBS=ON` + `GTEST_HAS_ABSL=ON` flag access), #4925 (MSVC `_isatty`), #3771 (`find_package` can't find gmock) | Reflects community-maintained CMake path |
| Parameterized-test naming | #4985 (param test name ≠ ctest name), #4956 (macOS `INSTANTIATE_TEST_SUITE_P` pointer names), #4937 (names too long) | Naming/`ctest` integration edge cases |
| Output/format | #4907 (XML output changes when failures present), #4973 (`%s` directive with null arg) | Report-format edge cases |
| Platform | #3947 (QNX `.WillOnce()` compile failure), #3982 (Windows leaked-mock crash) | Niche-platform support |
| Tooling | #3943 (`googletest-output-test.py` not fully Python 3 ready) | Affects framework self-tests |
| Docs | #4608 (document the 15-argument limit), #4974 (missing full stops), #4934 (human/AI-readable `ElementsAreArray`) | Documentation requests |

**Architectural watch items:**

- **Planned Abseil dependency.** Optional today; budget for it becoming standard.
- **JSON output format is explicitly unstable.** Prefer XML for durable CI
  integration.
- **CMake is community-maintained.** For mission-critical builds, the Bazel path
  is the reference; weigh contributing CMake fixes if you rely on it heavily.

---

## 10. Contributing

See `CONTRIBUTING.md` in the repository. High-level expectations:

- Follow the Google C++ Style Guide; run `clang-format` (config in the repo).
- Add or update tests in the relevant `test/` tree; samples are CI-checked.
- Keep changes portable across the supported compiler/platform matrix.
- Maintainers develop and test primarily with **Bazel** + Google's internal CI;
  validate non-trivial build changes there as well as in CMake.

---

## 11. Quick Reference

**Build (CMake):**
```bash
cmake -S . -B build [-DBUILD_GMOCK=OFF] [-DINSTALL_GTEST=OFF] [-DGTEST_HAS_ABSL=ON]
cmake --build build
cd build && ctest
```

**Build (Bazel):**
```bash
bazel test --cxxopt=-std=c++17 //...
```

**Link targets:** `gtest`, `gtest_main`, `gmock`, `gmock_main`, `gtest_prod`.

**Most-used flags:** `--gtest_filter`, `--gtest_output=xml:dir/`,
`--gtest_repeat=N`, `--gtest_shuffle`, `--gtest_break_on_failure`,
`--gtest_death_test_style=threadsafe`, `--gmock_verbose=info`.

**Key types:** `UnitTest`, `TestSuite`, `TestInfo`, `Test`, `Environment`,
`TestEventListener`, `AssertionResult`.

**Optional deps:** Abseil + RE2 (via `GTEST_HAS_ABSL` / `--define absl=1`).

**Self-check:** `--gtest_fail_if_no_test_linked`,
`--gtest_fail_if_no_test_selected`, `--gmock_catch_leaked_mocks`.

---

_Generated June 2026 from google/googletest at 7140cd4. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._