The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
refine according to CONTRIBUTING.md
moonlandera5ec19cb8d88
diff --git a/skills/cpp-testing/SKILL.md b/skills/cpp-testing/SKILL.mdindex fc58a52a1..6f60991ba 100644--- a/skills/cpp-testing/SKILL.md+++ b/skills/cpp-testing/SKILL.md@@ -1,72 +1,95 @@---name: cpp-testing-description: C++ testing strategies using GoogleTest/GoogleMock, TDD workflow, CMake/CTest, coverage, sanitizers, and practical testing patterns.+description: Use only when writing/updating/fixing C++ tests, configuring GoogleTest/CTest, diagnosing failing or flaky tests, or adding coverage/sanitizers.----# C++ Testing Patterns+# C++ Testing (Agent Skill)-Actionable, example-driven testing guidance for modern C++ (C++17/20) using GoogleTest/GoogleMock, CMake, and CTest.+Agent-focused testing workflow for modern C++ (C++17/20) using GoogleTest/GoogleMock with CMake/CTest.-## When to Activate+## When to Use-- Writing new C++ features or refactoring existing code-- Designing unit and integration tests for libraries or services+- Writing new C++ tests or fixing existing tests+- Designing unit/integration test coverage for C++ components- Adding test coverage, CI gating, or regression protection-- Setting up CMake/CTest workflows for consistent test execution+- Configuring CMake/CTest workflows for consistent execution+- Investigating test failures or flaky behavior+- Enabling sanitizers for memory/race diagnostics-## TDD Workflow for C+++### When NOT to Use-### The Red-Green-Refactor Loop+- 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-1. **RED**: Write a failing test for the new behavior-2. **GREEN**: Implement the minimal code to pass-3. **REFACTOR**: Improve the design while keeping tests green+## 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-// calculator_test.cpp+// tests/add_test.cpp#include <gtest/gtest.h>-int Add(int a, int b); // Step 1: declare the behavior+int Add(int a, int b); // Provided by production code.-TEST(CalculatorTest, AddsTwoNumbers) { // Step 1: RED- EXPECT_EQ(Add(2, 3), 5);+TEST(AddTest, AddsTwoNumbers) { // RED+ EXPECT_EQ(Add(2, 3), 5);}-// calculator.cpp-int Add(int a, int b) { // Step 2: GREEN- return a + b;+// src/add.cpp+int Add(int a, int b) { // GREEN+ return a + b;}-// Step 3: REFACTOR when needed, keeping tests green+// REFACTOR: simplify/rename once tests pass```-## Core Patterns+## Code Examples-### Basic Test Structure+### Basic Unit Test (gtest)```cpp+// tests/calculator_test.cpp#include <gtest/gtest.h>-int Clamp(int value, int lo, int hi);--TEST(ClampTest, ReturnsLowerBound) {- EXPECT_EQ(Clamp(-1, 0, 10), 0);-}--TEST(ClampTest, ReturnsUpperBound) {- EXPECT_EQ(Clamp(42, 0, 10), 10);-}+int Add(int a, int b); // Provided by production code.-TEST(ClampTest, ReturnsValueInRange) {- EXPECT_EQ(Clamp(5, 0, 10), 5);+TEST(CalculatorTest, AddsTwoNumbers) {+ EXPECT_EQ(Add(2, 3), 5);}```-### Fixtures for Shared Setup+### Fixture (gtest)```cpp+// tests/user_store_test.cpp+// Pseudocode stub: replace UserStore/User with project types.#include <gtest/gtest.h>-#include "user_store.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:@@ -85,55 +108,13 @@ TEST_F(UserStoreTest, FindsExistingUser) {}```-### Parameterized Tests--```cpp-#include <gtest/gtest.h>--struct Case {- int input;- int expected;-};--class AbsTest : public ::testing::TestWithParam<Case> {};--TEST_P(AbsTest, HandlesValues) {- auto [input, expected] = GetParam();- EXPECT_EQ(std::abs(input), expected);-}--INSTANTIATE_TEST_SUITE_P(- BasicCases,- AbsTest,- ::testing::Values(- Case{-3, 3},- Case{0, 0},- Case{7, 7}- )-);-```--### Death Tests (Failure Conditions)--```cpp-#include <gtest/gtest.h>--void RequirePositive(int value) {- if (value <= 0) {- std::abort();- }-}--TEST(DeathTest, AbortsOnNonPositive) {- ASSERT_DEATH(RequirePositive(0), "");-}-```--### GoogleMock for Behavior Verification+### Mock (gmock)```cpp+// tests/notifier_test.cpp#include <gmock/gmock.h>#include <gtest/gtest.h>+#include <string>class Notifier {public:@@ -149,9 +130,7 @@ public:class Service {public:explicit Service(Notifier ¬ifier) : notifier_(notifier) {}- void Publish(const std::string &message) {- notifier_.Send(message);- }+ void Publish(const std::string &message) { notifier_.Send(message); }private:Notifier ¬ifier_;@@ -161,42 +140,15 @@ TEST(ServiceTest, SendsNotifications) {MockNotifier notifier;Service service(notifier);- EXPECT_CALL(notifier, Send("hello"))- .Times(1);-+ EXPECT_CALL(notifier, Send("hello")).Times(1);service.Publish("hello");}```-### Fakes vs Mocks--- **Fake**: a lightweight in-memory implementation to exercise logic (great for stateful systems)-- **Mock**: used to assert interactions or order of operations--Prefer fakes for higher signal tests, use mocks only when behavior is the real contract.--## Test Organization--Recommended structure:--```-project/-|-- CMakeLists.txt-|-- include/-|-- src/-|-- tests/-| |-- unit/-| |-- integration/-| |-- testdata/-```--Keep unit tests close to the source, keep integration tests in their own folders, and isolate large fixtures in `testdata/`.--## CMake + CTest Workflow--### FetchContent for GoogleTest/GoogleMock+### CMake/CTest Quickstart```cmake+# CMakeLists.txt (excerpt)cmake_minimum_required(VERSION 3.20)project(example LANGUAGES CXX)@@ -204,9 +156,11 @@ 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- URL https://github.com/google/googletest/archive/refs/tags/v1.14.0.zip+ URL https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip)FetchContent_MakeAvailable(googletest)@@ -214,75 +168,80 @@ add_executable(example_teststests/calculator_test.cppsrc/calculator.cpp)--target_link_libraries(example_tests- GTest::gtest- GTest::gmock- GTest::gtest_main-)+target_link_libraries(example_tests GTest::gtest GTest::gmock GTest::gtest_main)enable_testing()include(GoogleTest)gtest_discover_tests(example_tests)```-### Configure, Build, Run-```bashcmake -S . -B build -DCMAKE_BUILD_TYPE=Debugcmake --build build -jctest --test-dir build --output-on-failure```-### Run a Subset of Tests+## Running Tests```bash+ctest --test-dir build --output-on-failurectest --test-dir build -R ClampTestctest --test-dir build -R "UserStoreTest.*" --output-on-failure```-## Coverage Workflows+```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.-### GCC + gcov + lcov+## 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 -DCMAKE_BUILD_TYPE=Debug \- -DCMAKE_CXX_FLAGS="--coverage"+cmake -S . -B build-cov -DENABLE_COVERAGE=ONcmake --build build-cov -jctest --test-dir build-cov-lcov --capture --directory build-cov --output-file coverage.infolcov --remove coverage.info '/usr/*' --output-file coverage.info-genhtml coverage.info --output-directory coverage```-### LLVM/Clang + llvm-cov+Clang + llvm-cov:```bash-cmake -S . -B build-llvm -DCMAKE_BUILD_TYPE=Debug \- -DCMAKE_CXX_COMPILER=clang++ \- -DCMAKE_CXX_FLAGS="-fprofile-instr-generate -fcoverage-mapping"+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_PROFILE_FILE="build-llvm/default.profraw" ctest --test-dir build-llvmllvm-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+llvm-cov report build-llvm/example_tests -instr-profile=build-llvm/default.profdata```## Sanitizers-### Common Flags--- AddressSanitizer (ASan): `-fsanitize=address`-- UndefinedBehaviorSanitizer (UBSan): `-fsanitize=undefined`-- ThreadSanitizer (TSan): `-fsanitize=thread`--### CMake Toggle Example-```cmakeoption(ENABLE_ASAN "Enable AddressSanitizer" OFF)option(ENABLE_UBSAN "Enable UndefinedBehaviorSanitizer" OFF)@@ -292,123 +251,22 @@ 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()```-Usage:--```bash-cmake -S . -B build-asan -DENABLE_ASAN=ON-cmake --build build-asan-ctest --test-dir build-asan --output-on-failure-```--## Common Scenarios--### API-Like Boundaries (Interfaces)--```cpp-class Clock {-public:- virtual ~Clock() = default;- virtual std::chrono::system_clock::time_point Now() const = 0;-};--class SystemClock : public Clock {-public:- std::chrono::system_clock::time_point Now() const override {- return std::chrono::system_clock::now();- }-};--class Session {-public:- Session(Clock &clock, std::chrono::seconds ttl)- : clock_(clock), ttl_(ttl) {}-- bool IsExpired(std::chrono::system_clock::time_point created) const {- return (clock_.Now() - created) > ttl_;- }--private:- Clock &clock_;- std::chrono::seconds ttl_;-};-```--### Filesystem Isolation+## Flaky Tests Guardrails-```cpp-#include <filesystem>-#include <gtest/gtest.h>--TEST(FileTest, WritesOutput) {- auto temp = std::filesystem::temp_directory_path() / "cpp-testing";- std::filesystem::create_directories(temp);-- auto file = temp / "output.txt";- std::ofstream out(file);- out << "hello";- out.close();-- std::ifstream in(file);- std::string content;- in >> content;-- EXPECT_EQ(content, "hello");-- std::filesystem::remove_all(temp);-}-```--### Time-Dependent Logic--```cpp-class FakeClock : public Clock {-public:- explicit FakeClock(std::chrono::system_clock::time_point now) : now_(now) {}- std::chrono::system_clock::time_point Now() const override { return now_; }- void Advance(std::chrono::seconds delta) { now_ += delta; }--private:- std::chrono::system_clock::time_point now_;-};-```--### Concurrency (Deterministic Tests)--```cpp-#include <condition_variable>-#include <mutex>-#include <thread>--TEST(WorkerTest, SignalsCompletion) {- std::mutex mu;- std::condition_variable cv;- bool done = false;-- std::thread worker([&] {- std::lock_guard<std::mutex> lock(mu);- done = true;- cv.notify_one();- });-- std::unique_lock<std::mutex> lock(mu);- bool ok = cv.wait_for(lock, std::chrono::milliseconds(500), [&] { return done; });-- worker.join();- ASSERT_TRUE(ok);-}-```+- 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@@ -427,22 +285,38 @@ TEST(WorkerTest, SignalsCompletion) {- Don't over-mock simple value objects- Don't use brittle string matching for non-critical logs-## Alternatives to GoogleTest+### Common Pitfalls-- **Catch2**: header-only, expressive matchers, fast setup-- **doctest**: lightweight, minimal compile overhead+- **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-## Fuzzing and Property Testing+Only use if the project already supports LLVM/libFuzzer or a property-testing library.-- **libFuzzer**: integrate with LLVM; focus on pure functions with minimal I/O-- **RapidCheck**: property-based testing to validate invariants over many inputs+- **libFuzzer**: best for pure functions with minimal I/O.+- **RapidCheck**: property-based tests to validate invariants.-Minimal libFuzzer harness:+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);+ // ParseConfig(input); // project functionreturn 0;}```++## Alternatives to GoogleTest++- **Catch2**: header-only, expressive matchers+- **doctest**: lightweight, minimal compile overhead