cpp-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

C++ Testing (Agent Skill)

C++测试（Agent技能）

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

面向Agent的现代C++（C++17/20）测试工作流，基于GoogleTest/GoogleMock与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

编写新的C++测试或修复现有测试
为C++组件设计单元/集成测试覆盖率
添加测试覆盖率、CI门禁或回归保护
配置CMake/CTest工作流以实现一致执行
排查测试失败或不稳定问题
启用Sanitizer进行内存/竞争诊断

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

实现新的产品功能但不涉及测试变更
与测试覆盖率或失败无关的大规模重构
无需验证测试回归的性能调优
非C++项目或非测试相关任务

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循环：红→绿→重构（先编写测试，最小化修复代码，再进行清理）。
隔离性：优先使用依赖注入和假对象（fake）而非全局状态。

测试布局：

tests/unit

、

tests/integration

、

tests/testdata

。

Mock与Fake的区别：Mock用于模拟交互，Fake用于模拟有状态行为。
CTest发现：使用
```
gtest_discover_tests()
```
实现稳定的测试发现。
CI信号：先运行测试子集，再使用
```
--output-on-failure
```
运行完整测试套件。

TDD Workflow

TDD工作流

Follow the RED → GREEN → REFACTOR loop:

RED: write a failing test that captures the new behavior
GREEN: implement the smallest change to pass
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

遵循红→绿→重构循环：

红：编写一个捕获新行为的失败测试
绿：实现最小化的代码变更使测试通过
重构：在保持测试通过的前提下清理代码

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)

基础单元测试（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);
}

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)

测试夹具（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");
}

cpp

// 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("alice");
    ASSERT_TRUE(user.has_value());
    EXPECT_EQ(user->name, "alice");
}

Mock (gmock)

模拟对象（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");
}

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/CTest快速入门

cmake

undefined

cmake

undefined

CMakeLists.txt (excerpt)

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)

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

set(GTEST_VERSION v1.17.0) # 根据项目策略调整。 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

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

调试测试失败

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

使用GTest过滤器重新运行单个失败的测试。
在失败断言周围添加作用域日志。
启用Sanitizer后重新运行测试。
找到根本原因后，重新运行完整测试套件。

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

优先使用目标级设置而非全局标志。

cmake

option(ENABLE_COVERAGE "启用覆盖率标志" 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

Sanitizer配置

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()

cmake

option(ENABLE_ASAN "启用AddressSanitizer" OFF)
option(ENABLE_UBSAN "启用UndefinedBehaviorSanitizer" OFF)
option(ENABLE_TSAN "启用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.

永远不要使用
```
sleep
```
进行同步；使用条件变量或闩锁（latch）。
为每个测试生成唯一的临时目录，并始终清理它们。
单元测试中避免依赖真实时间、网络或文件系统。
为随机输入使用确定性种子。

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

保持测试的确定性和隔离性
优先使用依赖注入而非全局变量
对前置条件使用
```
ASSERT_*
```
，对多检查场景使用
```
EXPECT_*
```
在CTest标签或目录中区分单元测试与集成测试
在CI中运行Sanitizer以检测内存和竞争问题

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

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

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.

使用固定临时路径 → 为每个测试生成唯一的临时目录并清理。
依赖挂钟时间 → 注入时钟或使用假时间源。
不稳定的并发测试 → 使用条件变量/闩锁和有限等待。
隐藏的全局状态 → 在测试夹具中重置全局状态或移除全局变量。
过度模拟 → 对有状态行为优先使用Fake，仅对交互进行Mock。
未运行Sanitizer → 在CI中添加ASan/UBSan/TSan构建。
仅在Debug构建中做覆盖率检查 → 确保覆盖率目标使用一致的编译标志。

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;
}

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

libFuzzer：最适合纯函数且I/O操作极少的场景。
RapidCheck：基于属性的测试，用于验证不变量。

极简libFuzzer测试桩（伪代码：替换为实际的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); // 项目实际函数
    return 0;
}

Alternatives to GoogleTest

GoogleTest的替代方案

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

Catch2：仅头文件库，匹配器表达能力强
doctest：轻量级，编译开销极小