Master C++ Testing: GoogleTest vs Catch2 vs doctest Guide

In modern C++ development, unit testing is not optional—it's a safety net that catches regressions, documents behavior, and enables fearless refactoring. Three frameworks dominate the landscape: GoogleTest, Catch2, and doctest. Each offers unique trade-offs in compile time, feature set, and syntax. This tutorial provides a hands-on comparison, guiding you through setup, writing tests, mocking, and debugging real-world issues. By the end, you'll know which framework fits your project's needs and how to avoid common pitfalls.

Setting Up GoogleTest

GoogleTest (gtest) is a comprehensive framework developed by Google. It supports test discovery, assertions, death tests, and mocking via GoogleMock. To set up, clone the repository and build with CMake:

git clone https://github.com/google/googletest.git
cd googletest
mkdir build && cd build
cmake .. -DCMAKE_CXX_STANDARD=17
make
sudo make install

Alternatively, use FetchContent in CMake to integrate directly:

include(FetchContent)
FetchContent_Declare(
  googletest
  GIT_REPOSITORY https://github.com/google/googletest.git
  GIT_TAG release-1.12.1
)
FetchContent_MakeAvailable(googletest)

Link your test executable with gtest and gtest_main.

#include <gtest/gtest.h>

int add(int a, int b) { return a + b; }

TEST(AddTest, PositiveNumbers) {
    EXPECT_EQ(add(2, 3), 5);
    EXPECT_EQ(add(0, 0), 0);
}

TEST(AddTest, NegativeNumbers) {
    EXPECT_EQ(add(-1, -1), -2);
}

int main(int argc, char **argv) {
    ::testing::InitGoogleTest(&argc, argv);
    return RUN_ALL_TESTS();
}

Writing Tests with Catch2

Catch2 is a header-only testing framework with a natural BDD-style syntax. It supports sections, generators, and matchers. To use, download the single header or use vcpkg:

vcpkg install catch2

Include the header and define CATCH_CONFIG_MAIN in exactly one source file:

#define CATCH_CONFIG_MAIN
#include <catch2/catch.hpp>

Write tests using TEST_CASE and SECTION macros:

TEST_CASE("Addition works", "[math]") {
    REQUIRE(add(2, 3) == 5);
    SECTION("with zero") {
        REQUIRE(add(0, 5) == 5);
    }
    SECTION("with negatives") {
        REQUIRE(add(-1, -1) == -2);
    }
}

Catch2's SECTION allows hierarchical test organization without separate test cases.

#define CATCH_CONFIG_MAIN
#include <catch2/catch.hpp>

int multiply(int a, int b) { return a * b; }

TEST_CASE("Multiplication works", "[math]") {
    REQUIRE(multiply(2, 3) == 6);
    SECTION("by zero") {
        REQUIRE(multiply(5, 0) == 0);
    }
    SECTION("by negative") {
        REQUIRE(multiply(-2, 3) == -6);
    }
}

Lightweight Testing with doctest

doctest is the fastest C++ testing framework, designed for compile-time efficiency. It is header-only and can be used in both source and header files. Setup is minimal:

#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
#include <doctest/doctest.h>

Write tests with TEST_CASE and CHECK/REQUIRE macros:

TEST_CASE("string concatenation") {
    std::string a = "Hello ";
    std::string b = "World";
    CHECK((a + b) == "Hello World");
}

doctest supports subcases (similar to Catch2 sections) and has a minimal footprint, making it ideal for embedded systems or libraries where compile time matters.

#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
#include <doctest/doctest.h>

int factorial(int n) {
    return n <= 1 ? 1 : n * factorial(n - 1);
}

TEST_CASE("factorial") {
    CHECK(factorial(0) == 1);
    CHECK(factorial(1) == 1);
    CHECK(factorial(5) == 120);
}

Mocking with GoogleMock

GoogleMock (gmock) integrates with GoogleTest to create mock objects. Define a mock class by inheriting from a base interface and using MOCK_METHOD macros:

class Database {
public:
    virtual ~Database() = default;
    virtual bool save(const std::string& data) = 0;
};
class MockDatabase : public Database {
public:
    MOCK_METHOD(bool, save, (const std::string&), (override));
};

In tests, set expectations:

TEST(DatabaseTest, SaveCalled) {
    MockDatabase mock;
    EXPECT_CALL(mock, save("test")).Times(1).WillOnce(::testing::Return(true));
    // code that uses mock
}

Use NiceMock to suppress warnings about unexpected calls, or StrictMock to fail on any unexpected call.

#include <gmock/gmock.h>
#include <gtest/gtest.h>

class Logger {
public:
    virtual ~Logger() = default;
    virtual void log(const std::string& msg) = 0;
};

class MockLogger : public Logger {
public:
    MOCK_METHOD(void, log, (const std::string&), (override));
};

class Service {
    Logger& logger_;
public:
    Service(Logger& l) : logger_(l) {}
    void process() { logger_.log("processed"); }
};

TEST(ServiceTest, LogsOnProcess) {
    MockLogger mock;
    EXPECT_CALL(mock, log("processed")).Times(1);
    Service svc(mock);
    svc.process();
}

Parameterized Tests and Data-Driven Testing

All three frameworks support parameterized tests to run the same test logic with different inputs.

GoogleTest: Use TEST_P with INSTANTIATE_TEST_SUITE_P.

class ParamTest : public ::testing::TestWithParam<std::tuple<int, int, int>> {};
TEST_P(ParamTest, Sum) {
    auto [a, b, expected] = GetParam();
    EXPECT_EQ(add(a, b), expected);
}
INSTANTIATE_TEST_SUITE_P(Default, ParamTest,
    ::testing::Values(
        std::make_tuple(1, 1, 2),
        std::make_tuple(2, 3, 5)
    ));

Catch2: Use GENERATE inside a TEST_CASE.

TEST_CASE("parameterized sum") {
    auto [a, b, expected] = GENERATE(table<int, int, int>({
        {1, 1, 2},
        {2, 3, 5}
    }));
    REQUIRE(add(a, b) == expected);
}

doctest: Use TEST_CASE with SUBCASE or manual loops.

TEST_CASE("parameterized sum") {
    int a, b, expected;
    SUBCASE("1+1=2") { a=1; b=1; expected=2; }
    SUBCASE("2+3=5") { a=2; b=3; expected=5; }
    CHECK(add(a, b) == expected);
}

#include <gtest/gtest.h>

int add(int a, int b) { return a + b; }

class AddParamTest : public ::testing::TestWithParam<std::tuple<int, int, int>> {};

TEST_P(AddParamTest, Sum) {
    auto [a, b, expected] = GetParam();
    EXPECT_EQ(add(a, b), expected);
}

INSTANTIATE_TEST_SUITE_P(
    AddTests,
    AddParamTest,
    ::testing::Values(
        std::make_tuple(1, 1, 2),
        std::make_tuple(2, 3, 5),
        std::make_tuple(-1, 1, 0)
    )
);

Best Practices and Common Pitfalls

Best Practices: - Write tests before code (TDD) to ensure testability. - Use descriptive test names that explain the scenario. - Keep tests independent; avoid shared mutable state. - Use fixtures for common setup. - Run tests in CI with sanitizers (AddressSanitizer, UndefinedBehaviorSanitizer).

Common Pitfalls: - Testing implementation details: Test behavior, not internal state. - Flaky tests: Avoid randomness, timeouts, and external dependencies. - Ignoring test failures: Treat failures as critical bugs. - Over-mocking: Mock only external dependencies; use real objects for value types.

Example of a well-structured test:

``cpp TEST_F(MyFixture, ReturnsCorrectValueWhenInputIsValid) { // Arrange auto input = createValidInput(); // Act auto result = objectUnderTest.process(input); // Assert EXPECT_EQ(result, expectedValue); } ``

#include <gtest/gtest.h>

class Calculator {
public:
    int divide(int a, int b) {
        if (b == 0) throw std::invalid_argument("division by zero");
        return a / b;
    }
};

TEST(CalculatorTest, DivideByZeroThrows) {
    Calculator calc;
    EXPECT_THROW(calc.divide(5, 0), std::invalid_argument);
}

TEST(CalculatorTest, DividePositive) {
    Calculator calc;
    EXPECT_EQ(calc.divide(10, 2), 5);
}

TEST(CalculatorTest, DivideNegative) {
    Calculator calc;
    EXPECT_EQ(calc.divide(-10, 2), -5);
}