C++ Reference ยท Preprocessor, Tools and Concepts
Testing C++ with Catch2 and GoogleTest
Compare the main C++ unit-testing frameworks, Catch2, GoogleTest and doctest, see test code for each, and learn how tests plug into CMake and CTest.
A unit test is a small program that calls your code with known inputs and checks the results. Tests tell you immediately when a change breaks something, and they let you refactor with confidence. C++ has no testing framework in the standard library, so projects choose one of several popular libraries.
Every framework gives you the same four things: a way to declare tests, assertions (CHECK, EXPECT_EQ) that report the failing expression and values, fixtures for shared setup, and a main that finds and runs all tests, with an exit code your build system can read.
The framework code on this page is read-only, because our runner has no Catch2 or GoogleTest. The live examples build a tiny test harness from scratch, which shows how these libraries work inside.
// Catch2 (v3) #include <catch2/catch_test_macros.hpp> TEST_CASE("addition works", "[math]") { REQUIRE(1 + 1 == 2); }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
The first example fails one check on purpose, to show the shape of a failure report.
The main frameworks
| Framework | Style | Notes |
|---|---|---|
| Catch2 (v3) | TEST_CASE, SECTION, REQUIRE |
Readable expressions: REQUIRE(a == b) prints both values. Sections give fixture-like behavior. Built-in benchmarks and matchers. |
| GoogleTest (+ GoogleMock) | TEST, TEST_F, EXPECT_EQ |
Very widely used, strong mocking, parameterized and death tests. |
| doctest | Like Catch2 | Very small and fast to compile. |
| Boost.Test | BOOST_AUTO_TEST_CASE |
Part of Boost. |
// GoogleTest #include <gtest/gtest.h> int add(int a, int b) { return a + b; } TEST(MathTest, AddsNumbers) { EXPECT_EQ(add(2, 3), 5); // non-fatal: the test continues ASSERT_GT(add(1, 1), 1); // fatal: the test stops here if false } class StackTest : public ::testing::Test { protected: void SetUp() override { /* build the fixture */ } }; TEST_F(StackTest, StartsEmpty) { /* ... */ }
// Catch2 with sections TEST_CASE("vector") { std::vector<int> v{1, 2, 3}; SECTION("push_back grows it") { v.push_back(4); REQUIRE(v.size() == 4); } SECTION("clear empties it") { v.clear(); REQUIRE(v.empty()); } } // each SECTION runs with a fresh copy of v
Running tests with CMake
include(FetchContent) FetchContent_Declare(Catch2 GIT_REPOSITORY https://github.com/catchorg/Catch2.git GIT_TAG v3.8.0) FetchContent_MakeAvailable(Catch2) add_executable(tests test_math.cpp) target_link_libraries(tests PRIVATE Catch2::Catch2WithMain mylib) include(CTest) include(Catch) catch_discover_tests(tests)
cmake --build build && ctest --test-dir build --output-on-failure
Usage notes
- Test behavior, not implementation. A test should break when the result changes, not when you rename a private function.
- Fast and independent. Tests must not depend on order, the clock, the network or files that you did not create yourself. Fake those dependencies behind an interface.
- One reason to fail. Name tests after the behavior (
rejects_empty_name), and keep the checks inside focused. - Use
REQUIREandASSERT_*when later lines depend on the result, such as before dereferencing a pointer; useCHECKandEXPECT_*otherwise to see all failures at once. - Compare floating point with a tolerance (
Catch::Approx,EXPECT_NEAR), never with==. - Run tests under sanitizers. A passing test that corrupts memory is still a bug (see Sanitizers).
- Test the failure cases, including exceptions:
REQUIRE_THROWS_AS(f(), std::out_of_range)orEXPECT_THROW(f(), std::out_of_range). - Mock only what you own. Mock interfaces that you define, with GoogleMock or hand-written fakes, not the standard library.