Quickstart: Building with Bazel

This tutorial aims to get you up and running with GoogleTest using the Bazel build system. If you're using GoogleTest for the first time or need a refresher, we recommend this tutorial as a starting point.

Prerequisites

To complete this tutorial, you'll need:

  • A compatible operating system (e.g. Linux, macOS, Windows).
  • A compatible C++ compiler that supports at least C++14.
  • Bazel 7.0 or higher, the preferred build system used by the GoogleTest team.

See Supported Platforms for more information about platforms compatible with GoogleTest.

If you don't already have Bazel installed, see the Bazel installation guide.

{: .callout .note} Note: The terminal commands in this tutorial show a Unix shell prompt, but the commands work on the Windows command line as well.

Set up a Bazel workspace

A Bazel workspace is a directory on your filesystem that you use to manage source files for the software you want to build. Each workspace directory has a text file named MODULE.bazel which may be empty, or may contain references to external dependencies required to build the outputs.

First, create a directory for your workspace:

$ mkdir my_workspace && cd my_workspace

Next, you’ll create the MODULE.bazel file to specify dependencies. As of Bazel 7.0, the recommended way to consume GoogleTest is through the Bazel Central Registry. To do this, create a MODULE.bazel file in the root directory of your Bazel workspace with the following content:

# MODULE.bazel

# Choose the most recent version available at
# https://registry.bazel.build/modules/googletest
bazel_dep(name = "googletest", version = "1.15.2")

Now you're ready to build C++ code that uses GoogleTest.

Create and run a binary

With your Bazel workspace set up, you can now use GoogleTest code within your own project.

As an example, create a file named hello_test.cc in your my_workspace directory with the following contents:

#include <gtest/gtest.h>

// Demonstrate some basic assertions.
TEST(HelloTest, BasicAssertions) {
  // Expect two strings not to be equal.
  EXPECT_STRNE("hello", "world");
  // Expect equality.
  EXPECT_EQ(7 * 6, 42);
}

GoogleTest provides assertions that you use to test the behavior of your code. The above sample includes the main GoogleTest header file and demonstrates some basic assertions.

To build the code, create a file named BUILD in the same directory with the following contents:

cc_test(
    name = "hello_test",
    size = "small",
    srcs = ["hello_test.cc"],
    deps = [
        "@googletest//:gtest",
        "@googletest//:gtest_main",
    ],
)

This cc_test rule declares the C++ test binary you want to build, and links to the GoogleTest library (@googletest//:gtest") and the GoogleTest main() function (@googletest//:gtest_main). For more information about Bazel BUILD files, see the Bazel C++ Tutorial.

{: .callout .note} NOTE: In the example below, we assume Clang or GCC and set --cxxopt=-std=c++14 to ensure that GoogleTest is compiled as C++14 instead of the compiler's default setting (which could be C++11). For MSVC, the equivalent would be --cxxopt=/std:c++14. See Supported Platforms for more details on supported language versions.

Now you can build and run your test:

Congratulations! You've successfully built and run a test binary using GoogleTest.

Next steps