Skip to main content
Agent skill

Cpp Testing

Use only when writing/updating/fixing C++ tests, configuring GoogleTest/CTest, diagnosing failing or flaky tests, or adding coverage/sanitizers.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Cpp Testing when an AI agent needs a reusable SKILL.md workflow for this job: Use only when writing/updating/fixing C++ tests, configuring GoogleTest/CTest, diagnosing failing or flaky tests, or adding coverage/sanitizers.

When not to use it

Skip Cpp Testing when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/cpp-testing
# Save SKILL.md to ~/.claude/skills/cpp-testing/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/cpp-testing/SKILL.md. For a shared project, commit the folder at .claude/skills/cpp-testing/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Cpp Testing skill for this task: Writing new C++ tests or fixing existing tests. Confirm any required inputs or files before making changes.

What supports this recommendation?

82/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
90/100
Practical detail
92/100
Source evidence
63/100
Source signals
70/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# C++ Testing (Agent Skill)

Agent-focused testing workflow for modern C++ (C++17/20) using GoogleTest/GoogleMock with CMake/CTest.

## When to Use

- Writing new C++ tests or fixing existing tests - Designing unit/integration test coverage for C++ components - Adding test coverage, CI gating, or regression protection - Configuring CMake/CTest workflows for consistent execution - Investigating test failures or flaky behavior - Enabling sanitizers for memory/race diagnostics

### When NOT to Use

- Implementing new product features without test changes - Large-scale refactors unrelated to test coverage or failures - Performance tuning without test regressions to validate - Non-C++ projects or non-test tasks

## Core Concepts

- **TDD loop**: red → green → refactor (tests first, minimal fix, then cleanups). - **Isolation**: prefer dependency injection and fakes over global state. - **Test layout**: `tests/unit`, `tests/integration`, `tests/testdata`. - **Mocks vs fakes**: mock for interactions, fake for stateful behavior. - **CTest discovery**: use `gtest_discover_tests()` for stable test discovery. - **CI signal**: run subset first, then full suite with `--output-on-failure`.

## TDD Workflow

Follow the RED → GREEN → REFACTOR loop:

1. **RED**: write a failing test that captures the new behavior 2. **GREEN**: implement the smallest change to pass 3. **REFACTOR**: clean up while tests stay green

```cpp // tests/add_test.cpp #include <gtest/gtest.h>

int Add(int a, int b); // Provided by production code.

TEST(AddTest, AddsTwoNumbers) { // RED EXPECT_EQ(Add(2, 3), 5); }

// src/add.cpp int Add(int a, int b) { // GREEN return a + b; }

// REFACTOR: simplify/rename once tests pass ```

## Code Examples

### Basic Unit Test (gtest)

```cpp // tests/calculator_test.cpp #include <gtest/gtest.h>

int Add(int a, int b); // Provided by production code.

TEST(CalculatorTest, AddsTwoNumbers) { EXPECT_EQ(Add(2, 3), 5); } ```

### Fixture (gtest)

```cpp // tests/user_store_test.cpp // Pseudocode stub: replace UserStore/User with project types. #include <gtest/gtest.h> #include <memory> #include <optional> #include <string>

struct User { std::string name; }; class UserStore { public: explicit UserStore(std::string /*path*/) {} void Seed(std::initializer_list<User> /*users*/) {} std::optional<User> Find(const std::string &/*name*/) { return User{"alice"}; } };

class UserStoreTest : public ::testing::Test { protected: void SetUp() override { store = std::make_unique<UserStore>(":memory:"); store->Seed({{"alice"}, {"bob"}}); }

std::unique_ptr<UserStore> store; };

TEST_F(UserStoreTest, FindsExistingUser) { auto user = store->Find("alice"); ASSERT_TRUE(user.has_value()); EXPECT_EQ(user->name, "alice"); } ```

### Mock (gmock)

```cpp // tests/notifier_test.cpp #include <gmock/gmock.h> #include <gtest/gtest.h> #include <string>

class Notifier { public: virtual ~Notifier() = default; virtual void Send(const std::string &message) = 0; };

class MockNotifier : public Notifier { public: MOCK_METHOD(void, Send, (const std::string &message), (override)); };

class Service { public: explicit Service(Notifier &notifier) : notifier_(notifier) {} void Publish(const std::string &message) { notifier_.Send(message); }

private: Notifier &notifier_; };

TEST(ServiceTest, SendsNotifications) { MockNotifier notifier; Service service(notifier);

EXPECT_CALL(notifier, Send("hello")).Times(1); service.Publish("hello"); } ```

### CMake/CTest Quickstart

```cmake # CMakeLists.txt (excerpt) cmake_minimum_required(VERSION 3.20) project(example LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20) set(CMAKE_CXX_STANDARD_REQUIRED ON)

include(FetchContent) # Prefer project-locked versions. If using a tag, use a pinned version per project policy. set(GTEST_VERSION v1.17.0) # Adjust to project policy. FetchContent_Declare( googletest # Google Test framework (official repository) URL https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip ) FetchContent_MakeAvailable(googletest)

add_executable(example_tests tests/calculator_test.cpp src/calculator.cpp ) target_link_libraries(example_tests GTest::gtest GTest::gmock GTest::gtest_main)

enable_testing() include(GoogleTest) gtest_discover_tests(example_tests) ```

```bash cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug cmake --build build -j ctest --test-dir build --output-on-failure ```

## Running Tests

```bash ctest --test-dir build --output-on-failure ctest --test-dir build -R ClampTest ctest --test-dir build -R "UserStoreTest.*" --output-on-failure ```

```bash ./build/example_tests --gtest_filter=ClampTest.* ./build/example_tests --gtest_filter=UserStoreTest.FindsExistingUser ```

## Debugging Failures

1. Re-run the single failing test with gtest filter. 2. Add scoped logging around the failing assertion. 3. Re-run with sanitizers enabled. 4. Expand to full suite once the root cause is fixed.

## Coverage

Prefer target-level settings instead of global flags.

```cmake option(ENABLE_COVERAGE "Enable coverage flags" OFF)

if(ENABLE_COVERAGE) if(CMAKE_CXX_COMPILER_ID MATCHES "GNU") target_compile_options(example_tests PRIVATE --coverage) target_link_options(example_tests PRIVATE --coverage) elseif(CMAKE_CXX_COMPILER_ID MATCHES "Clang") target_compile_options(example_tests PRIVATE -fprofile-instr-generate -fcoverage-mapping) target_link_options(example_tests PRIVATE -fprofile-instr-generate) endif() endif() ```

GCC + gcov + lcov:

```bash cmake -S . -B build-cov -DENABLE_COVERAGE=ON cmake --build build-cov -j ctest --test-dir build-cov lcov --capture --directory build-cov --output-file coverage.info lcov --remove coverage.info '/usr/*' --output-file coverage.info genhtml coverage.info --output-directory coverage ```

Clang + llvm-cov:

```bash cmake -S . -B build-llvm -DENABLE_COVERAGE=ON -DCMAKE_CXX_COMPILER=clang++ cmake --build build-llvm -j LLVM_PROFILE_FILE="build-llvm/default.profraw" ctest --test-dir build-llvm llvm-profdata merge -sparse build-llvm/default.profraw -o build-llvm/default.profdata llvm-cov report build-llvm/example_tests -instr-profile=build-llvm/default.profdata ```

## Sanitizers

```cmake option(ENABLE_ASAN "Enable AddressSanitizer" OFF) option(ENABLE_UBSAN "Enable UndefinedBehaviorSanitizer" OFF) option(ENABLE_TSAN "Enable ThreadSanitizer" OFF)

if(ENABLE_ASAN) add_compile_options(-fsanitize=address -fno-omit-frame-pointer) add_link_options(-fsanitize=address) endif() if(ENABLE_UBSAN) add_compile_options(-fsanitize=undefined -fno-omit-frame-pointer) add_link_options(-fsanitize=undefined) endif() if(ENABLE_TSAN) add_compile_options(-fsanitize=thread) add_link_options(-fsanitize=thread) endif() ```

## Flaky Tests Guardrails

- Never use `sleep` for synchronization; use condition variables or latches. - Make temp directories unique per test and always clean them. - Avoid real time, network, or filesystem dependencies in unit tests. - Use deterministic seeds for randomized inputs.

## Best Practices

### DO

- Keep tests deterministic and isolated - Prefer dependency injection over globals - Use `ASSERT_*` for preconditions, `EXPECT_*` for multiple checks - Separate unit vs integration tests in CTest labels or directories - Run sanitizers in CI for memory and race detection

### DON'T

- Don't depend on real time or network in unit tests - Don't use sleeps as synchronization when a condition variable can be used - Don't over-mock simple value objects - Don't use brittle string matching for non-critical logs

### Common Pitfalls

- **Using fixed temp paths** → Generate unique temp directories per test and clean them. - **Relying on wall clock time** → Inject a clock or use fake time sources. - **Flaky concurrency tests** → Use condition variables/latches and bounded waits. - **Hidden global state** → Reset global state in fixtures or remove globals. - **Over-mocking** → Prefer fakes for stateful behavior and only mock interactions. - **Missing sanitizer runs** → Add ASan/UBSan/TSan builds in CI. - **Coverage on debug-only builds** → Ensure coverage targets use consistent flags.

## Optional Appendix: Fuzzing / Property Testing

Only use if the project already supports LLVM/libFuzzer or a property-testing library.

- **libFuzzer**: best for pure functions with minimal I/O. - **RapidCheck**: property-based tests to validate invariants.

Minimal libFuzzer harness (pseudocode: replace ParseConfig):

```cpp #include <cstddef> #include <cstdint> #include <string>

extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) { std::string input(reinterpret_cast<const char *>(data), size); // ParseConfig(input); // project function return 0; } ```

## Alternatives to GoogleTest

- **Catch2**: header-only, expressive matchers - **doctest**: lightweight, minimal compile overhead

Intended uses

  • Writing new C++ tests or fixing existing tests
  • Designing unit/integration test coverage for C++ components
  • Adding test coverage, CI gating, or regression protection
  • Configuring CMake/CTest workflows for consistent execution
  • Investigating test failures or flaky behavior
  • Enabling sanitizers for memory/race diagnostics

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.