323 lines
9.7 KiB
Markdown
323 lines
9.7 KiB
Markdown
---
|
||
name: cpp-testing
|
||
description: 僅在編寫/更新/修復 C++ 測試、配置 GoogleTest/CTest、診斷失敗或不穩定 (Flaky) 的測試，或增加覆蓋率/消毒器 (Sanitizers) 時使用。
|
||
---
|
||
|
||
# C++ 測試 (Agent 技能)
|
||
|
||
針對現代 C++ (C++17/20) 的 Agent 導向測試工作流，使用 GoogleTest/GoogleMock 並搭配 CMake/CTest。
|
||
|
||
## 何時使用
|
||
|
||
- 撰寫新 C++ 測試或修復現有測試。
|
||
- 為 C++ 組件設計單元/整合測試覆蓋。
|
||
- 增加測試覆蓋率、設置 CI 門檻或回歸保護。
|
||
- 為了一致的執行結果而配置 CMake/CTest 工作流。
|
||
- 調查測試失敗或不穩定 (Flaky) 的行為。
|
||
- 啟用消毒器 (Sanitizers) 進行記憶體或競爭診斷。
|
||
|
||
### 何時「不」使用
|
||
|
||
- 在無測試變更的情況下實作新產品功能。
|
||
- 與測試覆蓋或測試失敗無關的大規模重構。
|
||
- 在沒有測試回歸驗證的情況下進行效能調優。
|
||
- 非 C++ 專案或非測試性質的任務。
|
||
|
||
## 核心概念
|
||
|
||
- **TDD 迴圈**：紅燈 (Red) → 綠燈 (Green) → 重構 (Refactor) (先寫測試，執行最小化修復，最後進行清理)。
|
||
- **隔離性 (Isolation)**：優先選用相依注入 (Dependency Injection) 與 Fake 物件，而非使用全域狀態。
|
||
- **測試佈局**：`tests/unit`, `tests/integration`, `tests/testdata`。
|
||
- **Mock vs Fake**：Mock 用於互動驗證，Fake 用於模擬具備狀態的行為。
|
||
- **CTest 探索**：使用 `gtest_discover_tests()` 進行穩定的測試探索。
|
||
- **CI 信號**：先執行子集測試，再執行完整套件並附帶 `--output-on-failure` 選項。
|
||
|
||
## TDD 工作流
|
||
|
||
請遵循 紅燈 → 綠燈 → 重構 迴圈：
|
||
|
||
1. **紅燈 (RED)**：撰寫一個會失敗的測試，用以捕捉新的行為。
|
||
2. **綠燈 (GREEN)**：執行最小程度的變更以通過測試。
|
||
3. **重構 (REFACTOR)**：在保持綠燈的狀態下清理程式碼。
|
||
|
||
```cpp
|
||
// 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)
|
||
|
||
```cpp
|
||
// 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)
|
||
|
||
```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 /*路徑*/) {}
|
||
void Seed(std::initializer_list<User> /*使用者清單*/) {}
|
||
std::optional<User> Find(const std::string &/*名稱*/) { 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 ¬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 快速上手
|
||
|
||
```cmake
|
||
# 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)
|
||
# 優先使用專案鎖定的版本。若使用標籤，請根據專案政策使用固定的版本。
|
||
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
|
||
```
|
||
|
||
## 執行測試
|
||
|
||
```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
|
||
```
|
||
|
||
## 偵錯失敗
|
||
|
||
1. 使用 gtest 篩選器重新執行單一失敗的測試。
|
||
2. 在失敗的斷言周圍加入作用域日誌 (Scoped logging)。
|
||
3. 在啟用消毒器 (Sanitizers) 的情況下重新執行。
|
||
4. 當根因修復後，擴展至執行完整套件。
|
||
|
||
## 覆蓋率 (Coverage)
|
||
|
||
優先選用目標層級 (Target-level) 的設定，而非使用全域旗標。
|
||
|
||
```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)
|
||
|
||
```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) 防範機制
|
||
|
||
- 絕不使用 `sleep` 進行同步；應使用條件變數 (Condition variables) 或 Latches。
|
||
- 確保每個測試的暫存目錄是唯一的，並始終清理乾淨。
|
||
- 單元測試應避免依賴真實時間、網路或檔案系統。
|
||
- 對隨機化輸入使用確定性的種子。
|
||
|
||
## 最佳實踐
|
||
|
||
### 推薦做法 (DO)
|
||
|
||
- 保持測試的確定性與隔離性。
|
||
- 優先選用相依注入 (Dependency injection) 而非全域變數。
|
||
- 使用 `ASSERT_*` 檢查前提條件，使用 `EXPECT_*` 進行多重檢查。
|
||
- 在 CTest 標籤或目錄中區分單元測試與整合測試。
|
||
- 在 CI 中執行消毒器，以偵測記憶體問題與競爭情況。
|
||
|
||
### 應避免的做法 (DON'T)
|
||
|
||
- 單元測試不應依賴真實時間或網路。
|
||
- 在可使用條件變數的情況下，不要使用 sleep 進行同步。
|
||
- 不要對簡單的數值物件 (Value objects) 進行過度 Mock 模擬。
|
||
- 對於非關鍵字日誌，不要使用脆弱的字串匹配。
|
||
|
||
### 常見陷阱
|
||
|
||
- **使用固定的暫存路徑** → 每個測試生成唯一的暫存目錄並進行清理。
|
||
- **依賴掛鐘時間 (Wall clock time)** → 注入時鐘或使用 Fake 時間源。
|
||
- **不穩定的併發測試** → 使用條件變數/Latches 以及帶超時的等待。
|
||
- **隱藏的全域狀態** → 在 Fixtures 中重置全域狀態或移除全域變數。
|
||
- **過度 Mock 模擬 (Over-mocking)** → 針對具備狀態的行為優先使用 Fake 物件，僅針對互動進行 Mock 模擬。
|
||
- **遺漏消毒器執行** → 在 CI 中加入 ASan/UBSan/TSan 建置。
|
||
- **僅在 Debug 建置中檢查覆蓋率** → 確保覆蓋率目標使用一致的旗標。
|
||
|
||
## 補充附錄：模糊測試 (Fuzzing) / 屬性測試 (Property Testing)
|
||
|
||
僅在專案已支援 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;
|
||
}
|
||
```
|
||
|
||
## GoogleTest 的替代方案
|
||
|
||
- **Catch2**：Header-only，表達力豐富的匹配器 (Matchers)。
|
||
- **doctest**：輕量級，編譯開銷極小。
|