# How GoogleTest Integrates with Bazel Using MODULE.bazel and BUILD.bazel

> Discover how GoogleTest integrates with Bazel using MODULE.bazel and BUILD.bazel. Learn how to leverage this powerful testing framework in your C++ projects for efficient builds and robust testing.

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

---

**GoogleTest integrates with Bazel through a two-stage process where `MODULE.bazel` declares the module metadata and external dependencies, while `BUILD.bazel` defines the compiled library targets and platform-specific build rules that consuming projects reference.**

GoogleTest (the `google/googletest` repository) provides first-class Bazel support through the Bzlmod module system. This integration allows C++ projects to depend on both Google Test and GoogleMock with a single declaration, while the repository handles complex platform adaptation and dependency resolution automatically.

## Module Declaration in MODULE.bazel

The `MODULE.bazel` file at the repository root serves as the module's manifest, declaring how Bazel should fetch and resolve the `googletest` module in external projects.

### Module Identity and Versioning

According to the source code in lines 33-37, the module declares its name as **`googletest`** with version **`head`**. This identifier is the canonical reference that other Bazel projects use when adding GoogleTest as a dependency:

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

```

### External Dependencies

GoogleTest declares its direct external dependencies using `bazel_dep` statements (lines 42-62). These include:

- **abseil-cpp**: String utilities and flags integration
- **platforms**: Platform constraint definitions
- **re2**: Regular expression library for pattern matching
- **rules_cc**: C++ compilation rules
- **rules_python**: Development-only dependency for test infrastructure

When a consuming project enables Bzlmod by adding `module()` to their own `MODULE.bazel`, Bazel automatically pulls the `googletest` module and transitively resolves these dependencies.

### Toolchain and SDK Configuration

The module handles specialized testing infrastructure through extension usage. Lines 66-75 register a Python toolchain using `use_extension` and `python.toolchain`, which supports the "fake Fuchsia SDK" exposed via `use_repo` (lines 77-81). This configuration allows Fuchsia-specific tests to compile even when the actual Fuchsia SDK is not present on the build machine.

## Build Target Definitions in BUILD.bazel

The `BUILD.bazel` file defines the concrete C++ library targets that consumers link against, handling source bundling and platform-specific compilation.

### Core Library Architecture

The primary **`cc_library`** target named **`gtest`** (lines 102-118) bundles both Google Test and Google Mock production sources. Crucially, this target deliberately **excludes** the monolithic "all" source files—`gtest-all.cc`, `gtest_main.cc`, `gmock-all.cc`, and `gmock_main.cc`—to prevent duplicate symbol errors when consumers link against specific target combinations.

### Specialized Target Variants

The build file exposes three additional targets for different integration scenarios:

- **`gtest_prod`**: A minimal `cc_library` (lines 90-95) containing only [`gtest_prod.h`](https://github.com/google/googletest/blob/main/gtest_prod.h) for the `FRIEND_TEST` macro. Production code uses this to declare test friendships without depending on the full testing framework.
- **`gtest_main`**: Provides a default `main()` entry point implemented in `gmock_main.cc`. Projects depending on this target receive a complete test runner without writing their own `main()` function.
- **`gtest_for_library`**: A `testonly` alias marked `True` (lines 85-90) intended for libraries that are themselves only consumed by test code.

### Platform-Specific Configuration

The build rules use `config_setting` and `select` statements (lines 41-64) to adapt compilation across platforms. This system conditionally applies:
- **`-pthread`** linker flags on Unix platforms
- **Abseil library linking** when the `has_absl` configuration is enabled
- **Fuchsia SDK libraries** for the `:fuchsia` configuration target

## Practical Integration Examples

### Adding GoogleTest as a Module Dependency

In your project's `MODULE.bazel`, declare the dependency:

```python
module(
    name = "my_project",
    version = "1.0.0",
    compatibility_level = 1,
)

bazel_dep(name = "googletest", version = "head")

```

### Defining Test Targets

Reference GoogleTest in your `BUILD.bazel` files:

```python
load("@rules_cc//cc:defs.bzl", "cc_test")

cc_test(
    name = "example_test",
    srcs = ["example_test.cc"],
    deps = [
        "@googletest//:gtest_main",  # Provides gtest + default main()

    ],
)

```

### Enabling Abseil Integration

To use GoogleTest with Abseil support, configure the `GTEST_HAS_ABSL` preprocessor definition:

```python
cc_test(
    name = "absl_test",
    srcs = ["absl_test.cc"],
    deps = [
        "@googletest//:gtest",
        "@abseil-cpp//absl/strings",
    ],
    copts = ["-DGTEST_HAS_ABSL=1"],
)

```

## Summary

- **`MODULE.bazel`** declares the `googletest` module (version `head`) and registers dependencies including abseil-cpp, re2, and rules_python.
- **`BUILD.bazel`** exposes `cc_library` targets including `gtest`, `gtest_main`, and `gtest_prod`, with the `gtest` target excluding monolithic source files to prevent linking conflicts.
- Platform-specific adaptation uses `config_setting` and `select` to apply conditional compiler flags, pthread linking, and optional Abseil integration.
- The fake Fuchsia SDK repository enables platform-specific testing without requiring the actual SDK installation.
- Consumers add `bazel_dep(name = "googletest", version = "head")` to their module file and depend on `@googletest//:gtest_main` for immediate test execution capability.

## Frequently Asked Questions

### How do I add GoogleTest to an existing Bazel project?

Add `bazel_dep(name = "googletest", version = "head")` to your project's `MODULE.bazel` file. Then reference `@googletest//:gtest_main` in the `deps` attribute of your `cc_test` targets. Bazel automatically downloads the module and compiles the necessary libraries when you run your tests.

### What is the difference between the gtest and gtest_main targets?

The **`gtest`** target provides the testing framework libraries without a `main()` function, requiring you to implement your own entry point. The **`gtest_main`** target includes a default `main()` implementation (from `gmock_main.cc`) that initializes the framework and runs all registered tests. Most projects should depend on `gtest_main` unless they need custom initialization logic.

### How does GoogleTest handle platform-specific compiler flags?

The `BUILD.bazel` file defines `config_setting` rules that detect the target platform (such as `:linux`, `:windows`, or `:fuchsia`). It then uses `select` statements to conditionally apply compiler options, linker flags like `-pthread`, and Abseil dependencies based on the active configuration. This ensures correct compilation across operating systems without manual intervention from consumers.

### Why does the gtest library exclude certain source files?

The `gtest` target deliberately excludes `gtest-all.cc`, `gtest_main.cc`, `gmock-all.cc`, and `gmock_main.cc` (as seen in lines 102-118 of `BUILD.bazel`). These monolithic files contain amalgamations of other source files; including them would cause duplicate symbol definitions when linking against the granular library targets. This design allows flexible composition of test frameworks without linkage errors.