diff --git a/README.md b/README.md index 912a276..fe7711a 100644 --- a/README.md +++ b/README.md @@ -218,6 +218,7 @@ everything-claude-code/ | |-- verification-loop/ # Continuous verification (Longform Guide) | |-- golang-patterns/ # Go idioms and best practices | |-- golang-testing/ # Go testing patterns, TDD, benchmarks +| |-- cpp-testing/ # C++ testing with GoogleTest, CMake/CTest (NEW) | |-- django-patterns/ # Django patterns, models, views (NEW) | |-- django-security/ # Django security best practices (NEW) | |-- django-tdd/ # Django TDD workflow (NEW) diff --git a/README.zh-CN.md b/README.zh-CN.md index 1499d54..271240a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -171,6 +171,7 @@ everything-claude-code/ | |-- verification-loop/ # 持续验证（详细指南） | |-- golang-patterns/ # Go 惯用语和最佳实践（新增） | |-- golang-testing/ # Go 测试模式、TDD、基准测试（新增） +| |-- cpp-testing/ # C++ 测试模式、GoogleTest、CMake/CTest（新增） | |-- commands/ # 用于快速执行的斜杠命令 | |-- tdd.md # /tdd - 测试驱动开发 diff --git a/skills/cpp-testing/SKILL.md b/skills/cpp-testing/SKILL.md new file mode 100644 index 0000000..6f60991 --- /dev/null +++ b/skills/cpp-testing/SKILL.md @@ -0,0 +1,322 @@ +--- +name: cpp-testing +description: Use only when writing/updating/fixing C++ tests, configuring GoogleTest/CTest, diagnosing failing or flaky tests, or adding coverage/sanitizers. +--- + +# 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 + +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 + +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 +#include +#include +#include + +struct User { std::string name; }; +class UserStore { +public: + explicit UserStore(std::string /*path*/) {} + void Seed(std::initializer_list /*users*/) {} + std::optional Find(const std::string &/*name*/) { return User{"alice"}; } +}; + +class UserStoreTest : public ::testing::Test { +protected: + void SetUp() override { + store = std::make_unique(":memory:"); + store->Seed({{"alice"}, {"bob"}}); + } + + std::unique_ptr 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 +#include +#include + +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 ¬ifier) : notifier_(notifier) {} + void Publish(const std::string &message) { notifier_.Send(message); } + +private: + Notifier ¬ifier_; +}; + +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 + 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 +#include +#include + +extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) { + std::string input(reinterpret_cast(data), size); + // ParseConfig(input); // project function + return 0; +} +``` + +## Alternatives to GoogleTest + +- **Catch2**: header-only, expressive matchers +- **doctest**: lightweight, minimal compile overhead