cpp-testing

name	cpp-testing
description	仅在编写/更新/修复 C++ 测试、配置 GoogleTest/CTest、诊断失败或不稳定的测试、或添加覆盖率/检测器（Sanitizers）时使用。
origin	ECC

C++ 测试（智能体技能）

针对现代 C++ (C++17/20) 的智能体测试工作流，使用 GoogleTest/GoogleMock 配合 CMake/CTest。

适用场景

• 编写新的 C++ 测试或修复现有测试
• 为 C++ 组件设计单元/集成测试覆盖
• 添加测试覆盖、CI 门禁或回归防护
• 配置 CMake/CTest 工作流以实现一致性执行
• 调查测试失败或不稳定（Flaky）行为
• 启用检测器（Sanitizers）进行内存/竞态诊断

不适用场景

• 实施不涉及测试更改的新产品功能
• 与测试覆盖或失败无关的大规模重构
• 在没有测试回归验证的情况下进行性能调优
• 非 C++ 项目或非测试任务

核心概念

• TDD 循环：红（Red）→ 绿（Green）→ 重构（Refactor）（测试先行，最小化修复，然后清理）。
• 隔离性：优先选择依赖注入和伪造对象（Fakes），而非全局状态。
• 测试布局：tests/unit、tests/integration、tests/testdata。
• Mocks vs Fakes：Mock 用于交互验证，Fake 用于有状态的行为模拟。
• CTest 发现：使用 gtest_discover_tests() 进行稳定的测试发现。
• CI 信号：先运行子集，然后使用 --output-on-failure 运行完整套件。

TDD 工作流

遵循 红 → 绿 → 重构 循环：

1. 红（RED）：编写一个捕获新行为的失败测试。
2. 绿（GREEN）：实施最小化的更改以使测试通过。
3. 重构（REFACTOR）：在保持测试为绿色的前提下进行清理。

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

int Add(int a, int b); // 由生产代码提供。

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

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

// 重构（REFACTOR）：一旦测试通过，简化/重命名代码

代码示例

基础单元测试 (gtest)

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

int Add(int a, int b); // 由生产代码提供。

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

测试固件 (Fixture) (gtest)

// tests/user_store_test.cpp
// 伪代码存根：请将 UserStore/User 替换为项目实际类型。
#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();
    (user.());
    (user->name, );
}

打桩测试 (Mock) (gmock)

// 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.();
}

CMake/CTest 快速入门

# CMakeLists.txt (节选)
cmake_minimum_required(VERSION 3.20)
project(example LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

include(FetchContent)
# 优先使用项目锁定的版本。如果使用 tag，请根据项目策略使用固定版本。
set(GTEST_VERSION v1.17.0) # 根据项目策略调整。
FetchContent_Declare(
  googletest
  # Google Test 框架 (官方仓库)
  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)

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

运行测试

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

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

调试失败用例

1. 使用 gtest 过滤器重新运行单个失败的测试。
2. 在失败的断言周围添加作用域日志（Scoped Logging）。
3. 启用检测器（Sanitizers）重新运行。
4. 根本原因修复后，扩展到运行完整套件。

覆盖率 (Coverage)

优先使用目标级（Target-level）设置，而非全局标志。

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:

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:

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)

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）防护准则

• 永远不要使用 sleep 进行同步；请使用条件变量（Condition Variables）或门闩（Latches）。
• 确保临时目录在每个测试中都是唯一的，并且始终进行清理。
• 在单元测试中避免依赖真实时间、网络或文件系统。
• 为随机输入使用确定性的种子。

最佳实践

建议（DO）

• 保持测试的确定性和隔离性
• 优先使用依赖注入而非全局变量
• 使用 ASSERT_* 检查前提条件，使用 EXPECT_* 进行多重检查
• 在 CTest 标签或目录中区分单元测试与集成测试
• 在 CI 中运行检测器以进行内存和竞态检测

禁止（DON'T）

• 不要在单元测试中依赖真实时间或网络
• 当可以使用条件变量时，不要使用 sleep 进行同步
• 不要过度打桩（Mock）简单的值对象（Value Objects）
• 不要对非关键日志使用脆弱的字符串匹配

常见陷阱

• 使用固定的临时路径 → 为每个测试生成唯一的临时目录并清理。
• 依赖墙上时钟时间（Wall clock time） → 注入时钟或使用伪造的时间源。
• 不稳定的并发测试 → 使用条件变量/门闩和有界等待。
• 隐藏的全局状态 → 在测试固件中重置全局状态，或移除全局变量。
• 过度 Mock → 优先对有状态行为使用 Fake，仅对交互使用 Mock。
• 缺失检测器运行 → 在 CI 中添加 ASan/UBSan/TSan 构建。
• 仅在 Debug 构建中进行覆盖率统计 → 确保覆盖率目标使用一致的标志。

可选附录：模糊测试 / 属性测试

仅在项目已支持 LLVM/libFuzzer 或属性测试库时使用。

• libFuzzer：最适合具有极少 I/O 的纯函数。
• RapidCheck：基于属性的测试，用于验证不变量。

最小化的 libFuzzer 挂钩（伪代码：请替换 ParseConfig）：

#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); // 项目函数
    return 0;
}

GoogleTest 的替代方案

• Catch2：仅头文件，具有表现力的匹配器（Matchers）
• doctest：轻量级，极小的编译开销