Code Testing Extensions

C++ Extension

Language-specific guidance for C++ test generation.

Rule #1: Investigate the Repo First

Before writing any test or running any command, read:

1. Existing tests — find *_test.cpp, *_tests.cpp, test_*.cc, tests/, test/, unittests/, and any CTest/Bazel/Make test targets. Copy the framework, naming, fixtures, assertions, and helper style already in use.

2. Build configuration — inspect CMakeLists.txt, CMakePresets.json, Makefile, WORKSPACE, MODULE.bazel, BUILD, BUILD.bazel, meson.build, or CI scripts before inventing commands.

3. Dependencies — detect GoogleTest, GoogleMock, Catch2, doctest, Boost.Test, or a custom harness from package manifests and target links.

4. Compiler and standard — identify CMAKE_CXX_STANDARD, -std=c++NN, toolchain files, compiler wrappers, sanitizers, and warning-as-error flags.

5. Coverage setup — determine whether the repo already has gcov, llvm-cov, gcovr, lcov, or custom coverage targets. If not, add minimal, test-target-scoped coverage instrumentation.

Generated C++ tests must earn coverage, not merely compile. Target uncovered functions, branches, error paths, and boundary conditions; shallow smoke tests that only construct objects rarely move line coverage.

Environment and Toolchain Detection

Useful discovery commands:

cmake --version
g++ --version
clang++ --version
find . \( -name CMakeLists.txt -o -name CMakePresets.json -o -name Makefile -o -name BUILD -o -name BUILD.bazel \)
find . \( -name '*test*.cpp' -o -name '*test*.cc' -o -name '*tests*.cpp' -o -name '*tests*.cc' \)

Do not change the project's C++ standard to make a test compile. Match the production target's standard and include directories.

Test Framework Detection

Use the framework already present. Do not add Catch2 to a GoogleTest repo or GoogleTest to a Catch2 repo just because it is familiar.

Build Commands

Prefer repo scripts and presets first. Otherwise use the smallest command that compiles the changed test target.

Make equivalents when no CMake build exists:

Bazel equivalents:

Test Commands

For CTest, run from the configured build tree or pass --test-dir build; running ctest from the source root often reports zero tests.

Lint Command

Use the repo's lint script first (make lint, cmake --build build --target lint, ninja clang-tidy). Otherwise detect tools from configuration:

• .clang-format present → clang-format -i path/to/test.cpp

• .clang-tidy present → run the repo's clang-tidy target or clang-tidy path/to/test.cpp -- -Iinclude

• CMake format target present → cmake --build build --target format

Never silence warnings in generated tests with blanket pragmas. Fix the warning or match the existing project pattern.

Project Layout and Test File Placement

Common layouts:

project/
├── include/              # public headers
├── src/                  # implementation files
├── tests/                # test sources and CMakeLists.txt
│   ├── CMakeLists.txt
│   └── widget_test.cpp
├── CMakeLists.txt
└── CMakePresets.json

• Match existing suffixes: _test.cpp, _tests.cpp, test_*.cpp, or .cc.

• Keep tests near existing test CMake targets instead of creating an isolated harness.

• Prefer testing through public headers. Use white-box access only when existing tests already do so or coverage-critical internals cannot be reached otherwise.

• Shared fixtures/helpers belong in tests/support/, tests/helpers/, or the existing helper location, not production src/ unless the repo already has test-only utilities.

GoogleTest Setup

Minimal test source:

#include <gtest/gtest.h>

#include "calculator.hpp"

TEST(CalculatorTest, Add_WithPositiveInputs_ReturnsSum) {
    Calculator calculator;

    EXPECT_EQ(calculator.Add(2, 3), 5);
}

CMake registration with discovery:

enable_testing()
find_package(GTest REQUIRED)
include(GoogleTest)

add_executable(calculator_tests
    tests/calculator_test.cpp
)
target_link_libraries(calculator_tests
    PRIVATE
        calculator_lib
        GTest::gtest_main
)
gtest_discover_tests(calculator_tests)

If the repo already has a test helper function such as add_project_test(...), use it instead of writing raw add_executable blocks.

Catch2 v3 Setup

Minimal test source:

#include <catch2/catch_test_macros.hpp>

#include "calculator.hpp"

TEST_CASE("Calculator adds positive inputs", "[calculator]") {
    Calculator calculator;

    CHECK(calculator.Add(2, 3) == 5);
}

CMake registration with discovery:

enable_testing()
find_package(Catch2 3 REQUIRED)
include(Catch)

add_executable(calculator_tests
    tests/calculator_test.cpp
)
target_link_libraries(calculator_tests
    PRIVATE
        calculator_lib
        Catch2::Catch2WithMain
)
catch_discover_tests(calculator_tests)

Use Catch2::Catch2WithMain unless the repo already provides a custom main. Linking a framework main and defining your own main causes duplicate-symbol linker failures.

Coverage Instrumentation

Coverage instrumentation is the highest-risk setup step. Add coverage flags to both compilation and linking for the test target. Adding flags only to CXXFLAGS often compiles but produces no .gcda files or fails with missing gcov runtime symbols at link time.

CMake target-scoped coverage option

Prefer target-scoped flags over global CMAKE_CXX_FLAGS so production targets stay clean:

option(CODE_COVERAGE "Build tests with gcov-compatible coverage instrumentation" OFF)

add_executable(calculator_tests
    tests/calculator_test.cpp
)
target_link_libraries(calculator_tests
    PRIVATE
        calculator_lib
        GTest::gtest_main
)

if(CODE_COVERAGE AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang|AppleClang")
    target_compile_options(calculator_tests PRIVATE --coverage -O0 -g)
    target_link_options(calculator_tests PRIVATE --coverage)
endif()

For libraries built into the test binary, instrument the library target too, otherwise coverage only reports test files:

if(CODE_COVERAGE AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang|AppleClang")
    target_compile_options(calculator_lib PRIVATE --coverage -O0 -g)
    target_link_options(calculator_lib PRIVATE --coverage)
    target_compile_options(calculator_tests PRIVATE --coverage -O0 -g)
    target_link_options(calculator_tests PRIVATE --coverage)
endif()

Equivalent long-form flags:

target_compile_options(calculator_tests PRIVATE -fprofile-arcs -ftest-coverage -O0 -g)
target_link_options(calculator_tests PRIVATE -fprofile-arcs -ftest-coverage)

Coverage command sequence

GCC/gcov path:

cmake -S . -B build-coverage -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON -DCODE_COVERAGE=ON
cmake --build build-coverage --target calculator_tests
ctest --test-dir build-coverage --output-on-failure
gcovr --root . --filter 'src/' --filter 'include/' --exclude 'tests/' --print-summary

Clang path using gcov-compatible data:

cmake -S . -B build-coverage -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON -DCODE_COVERAGE=ON
cmake --build build-coverage --target calculator_tests
ctest --test-dir build-coverage --output-on-failure
gcovr --root . --gcov-executable 'llvm-cov gcov' --filter 'src/' --filter 'include/' --exclude 'tests/' --print-summary

lcov / genhtml path:

cmake -S . -B build-coverage -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON -DCODE_COVERAGE=ON
cmake --build build-coverage
ctest --test-dir build-coverage --output-on-failure
lcov --capture --directory build-coverage --output-file coverage.info
lcov --remove coverage.info '*/tests/*' '*/_deps/*' --output-file coverage.filtered.info
genhtml coverage.filtered.info --output-directory coverage-html

Make-only coverage path:

make clean
CXXFLAGS="--coverage -O0 -g" LDFLAGS="--coverage" make tests
./tests/calculator_tests
gcovr --root . --print-summary

Important coverage rules:

• Compile and link with the same compiler family. Clang-generated coverage data should be read with llvm-cov gcov, not system gcov.

• Run the instrumented test binary before collecting; .gcda files are written when the process exits normally.

• Use -O0 -g for coverage builds to keep line mapping stable.

• Exclude test files and vendored dependencies from coverage reports; include production src/ and include/.

• If the code under test is a static library, object library, or source list linked into tests, instrument that target as well as the test executable.

Coverage-Targeting Guidance

To avoid low coverage deltas:

1. Read the coverage report and identify uncovered production files, functions, and branch lines.

2. Write tests that drive real behavior through public APIs or stable seams.

3. Prioritize branches: error handling, empty input, boundary values, invalid parse cases, feature flags, and state transitions.

4. Prefer one parameterized test that covers many meaningful paths over many tests that repeat the same happy path.

5. Assert observable outcomes, side effects, return codes, exceptions, and mock interactions. A test that only constructs an object usually adds little or no useful coverage.

6. Re-run the targeted coverage command and confirm the intended files moved.

Do not chase coverage by testing implementation details that make the suite brittle when a public API can cover the same lines.

Test Patterns

GoogleTest assertions

Use ASSERT_* only when the rest of the test cannot safely continue.

GoogleTest fixtures and parameterized tests

class ParserTest : public ::testing::Test {
protected:
    Parser parser_;
};

TEST_F(ParserTest, Parse_WithEmptyInput_ReturnsEmptyResult) {
    EXPECT_TRUE(parser_.Parse("").empty());
}

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

TEST_P(ClampTest, Clamp_WithBoundaryInputs_ReturnsExpectedValue) {
    const auto [value, min, max, expected] = GetParam();

    EXPECT_EQ(Clamp(value, min, max), expected);
}

INSTANTIATE_TEST_SUITE_P(
    BoundaryCases,
    ClampTest,
    ::testing::Values(
        std::make_tuple(-1, 0, 10, 0),
        std::make_tuple(5, 0, 10, 5),
        std::make_tuple(11, 0, 10, 10)));

Catch2 assertions and generators

#include <catch2/catch_approx.hpp>
#include <catch2/catch_test_macros.hpp>
#include <catch2/generators/catch_generators.hpp>

TEST_CASE("Clamp handles boundary inputs", "[math]") {
    const auto [value, min, max, expected] = GENERATE(
        std::tuple{-1, 0, 10, 0},
        std::tuple{5, 0, 10, 5},
        std::tuple{11, 0, 10, 10});

    CHECK(Clamp(value, min, max) == expected);
}

TEST_CASE("Divide rejects zero denominator", "[math]") {
    REQUIRE_THROWS_AS(Divide(1.0, 0.0), std::invalid_argument);
    CHECK(Divide(1.0, 3.0) == Catch::Approx(0.333333).epsilon(0.001));
}

Use REQUIRE when execution must stop after failure; use CHECK for independent assertions.

Mocking Rules

Use GoogleMock when the repo already uses gMock or GoogleTest with mocks:

#include <gmock/gmock.h>

class MockClock : public Clock {
public:
    MOCK_METHOD(std::chrono::seconds, Now, (), (const, override));
};

TEST(SchedulerTest, ShouldRun_WhenIntervalElapsed_ReturnsTrue) {
    MockClock clock;
    EXPECT_CALL(clock, Now()).WillOnce(::testing::Return(std::chrono::seconds{42}));

    Scheduler scheduler(clock);

    EXPECT_TRUE(scheduler.ShouldRun());
}

Guidelines:

• Mock interfaces with virtual methods and virtual destructors.

• Prefer small interfaces or constructor injection over global state.

• For code without virtuals, create seams with templates, function objects, adapters, or thin interfaces around external dependencies.

• Do not mock standard library containers or value objects; build real values.

• If a test needs more than three mocks, treat it as a design smell and look for a higher-level behavioral test.

Testing Internals

If types are not well suited for testing only through their public surface, consider exposing internals to tests using a preprocessor-guarded friend declaration:

class MyClass {
#ifdef UNIT_TESTING
    friend class MyClassTest;
#endif
    // ...
};

Define UNIT_TESTING only in the test build configuration so production builds remain unaffected:

target_compile_definitions(my_component_tests PRIVATE UNIT_TESTING)

Use this sparingly. Prefer public behavior tests and dependency seams before adding test-only friendship.

Common Errors

Dependency Installation (Last Resort)

Only add dependencies after investigation confirms the repo has no test framework or the expected framework is missing. Prefer existing package managers and lockfiles.

CMake with installed packages:

find_package(GTest REQUIRED)
find_package(Catch2 3 REQUIRED)

CMake FetchContent fallback for GoogleTest:

include(FetchContent)
FetchContent_Declare(
    googletest
    URL https://github.com/google/googletest/archive/refs/tags/v1.14.0.zip)
FetchContent_MakeAvailable(googletest)

CMake FetchContent fallback for Catch2 v3:

include(FetchContent)
FetchContent_Declare(
    Catch2
    URL https://github.com/catchorg/Catch2/archive/refs/tags/v3.5.4.zip)
FetchContent_MakeAvailable(Catch2)
list(APPEND CMAKE_MODULE_PATH ${catch2_SOURCE_DIR}/extras)

Package manager examples:

On Debian/Ubuntu, libgtest-dev historically installs only GoogleTest sources (no prebuilt libraries or CMake package config), so find_package(GTest REQUIRED) can still fail. On those systems either build/install GoogleTest from the packaged sources, add it via FetchContent, or use vcpkg/Conan instead of relying on apt alone.

Do not vendor dependencies by copying source into the repo unless that is already the project's dependency policy.

Skip

Skip or avoid these actions unless the repo explicitly requires them:

• Do not replace the build system or create a parallel test harness outside CMake/Make/Bazel just for generated tests.

• Do not add coverage flags globally to release builds; keep coverage in a Debug/test-only configuration.

• Do not use system gcov with Clang-generated coverage data.

• Do not define a second test main when linking framework-provided main targets.

• Do not write tests that only instantiate objects without assertions or behavior coverage.

• Do not add a new test framework when an existing one is already configured.