@polderlabs/bizar 10.7.2 → 10.11.0

package/.claude/skills/cpp-testing/SKILL.md

@@ -1,304 +0,0 @@
----
-name: cpp-testing
-description: Use this skill when writing or improving C++ tests, choosing a test framework, designing host-side tests for embedded firmware, or running a test-gate / TDD workflow. Triggers on tasks involving GoogleTest, Catch2, doctest, mocking, coverage, or host-test binaries for firmware modules.
----
-
-# C++ Testing Skill
-
-## Overview
-
-This skill provides guidance for writing effective C++ tests across the full testing pyramid: unit, integration, host-side, and on-device. It covers framework selection, test layering, host-test patterns for embedded firmware, TDD workflow, coverage targets, mocking strategies, and common anti-patterns.
-
-Key use cases:
-- Writing new tests for a C++ module
-- Choosing between GoogleTest, Catch2, and doctest
-- Setting up a host-side test binary that links firmware C++ code without ESP-IDF or FreeRTOS
-- Running a test-gate to verify 80% coverage before merging
-- Applying TDD to firmware policy/payload modules
-
-## Test Framework Selection
-
-| Framework | Best For | Strengths | Weaknesses |
-|-----------|----------|-----------|------------|
-| **GoogleTest** | Large projects, parametric tests, fixtures | Rich feature set, wide adoption, `TEST_P`, `TEST_F`, death tests | Verbose, heavy |
-| **Catch2** | Quick to write, expressive | Single-header, BDD-style, very low boilerplate | Slower compile, less `gtest` ecosystem |
-| **doctest** | Header-only, compile-time speed | Fast compile, lightweight, C++17 | Less ecosystem, newer |
-
-**Recommendation:** Default to GoogleTest for embedded/firmware projects — its `TEST_P`/`TEST_F` and death tests are well-suited to policy modules. Use Catch2 when you want minimal friction for small utilities. Use doctest when compile speed is critical.
-
-See `references/framework-compare.md` for code samples.
-
-## Test Layering
-
-```
-┌─────────────────────────────────────┐
-│     Host-Side Integration Tests     │  ← Binary links firmware .cpp, tests policy/payload
-├─────────────────────────────────────┤
-│       On-Device Integration Tests   │  ← Runs on target; tests HW / interrupts
-├─────────────────────────────────────┤
-│         Unit Tests (isolated)       │  ← Pure C++, mocked deps, fast
-└─────────────────────────────────────┘
-```
-
-- **Unit tests:** Test a single class/function in isolation. Link a `.cpp` directly into the test binary with mocked dependencies.
-- **Host-side integration tests:** Compile a `test_*.cpp` binary that links one or more firmware modules from `main/` or `components/`. No ESP-IDF, no FreeRTOS. Use for policy, payload, and datacollector modules.
-- **On-device tests:** Run on the actual hardware. Require `idf.py test` and device flashing.
-
-See `references/host-test-for-embedded.md` for the CMake setup pattern.
-
-## Host-Side Test Pattern for Embedded Firmware
-
-The goal: build a standalone Linux binary that links firmware C++ code and runs assertions — no ESP-IDF, no FreeRTOS.
-
-**CMake pattern (minimal):**
-
-```cmake
-# test/host/CMakeLists.txt
-cmake_minimum_required(VERSION 3.16)
-project(host_feature_flags_test)
-
-add_executable(test_feature_flags
-    ${CMAKE_CURRENT_SOURCE_DIR}/test_feature_flags.cpp
-    ${FIRMWARE_ROOT}/main/policy/feature_flags.cpp
-)
-target_compile_features(test_feature_flags PRIVATE cxx_std_17)
-target_link_libraries(test_feature_flags PRIVATE gtest gmock pthread)
-```
-
-**Test source pattern:**
-
-```cpp
-// test/host/test_feature_flags.cpp
-#include <gtest/gtest.h>
-#include "feature_flags.h"   // firmware header — no ESP-IDF, no FreeRTOS
-
-// Mock any firmware-freeRTOS deps via abstract interface or std::function injection
-namespace mock {
-  std::function<bool(const char*)> is_active_override;
-}
-
-bool is_feature_active(const char* name) {
-  if (mock::is_active_override) return mock::is_active_override(name);
-  return feature_flags_impl(name);  // call real impl
-}
-
-TEST(FeatureFlags, returns_true_for_known_feature) {
-  mock::is_active_override = [](const char* n) { return strcmp(n, "debug") == 0; };
-  EXPECT_TRUE(is_feature_active("debug"));
-}
-```
-
-See `references/host-test-for-embedded.md` for full examples testing `feature_flags.cpp`, `resp_fallback.cpp`, and `datacollector.cpp`.
-
-## TDD Workflow for C++
-
-1. **Red** — Write a failing test first. Compile and run; confirm it fails for the right reason.
-2. **Green** — Write the minimum production code to make the test pass. No optimization yet.
-3. **Refactor** — Clean up production and test code. Re-run tests to confirm they still pass.
-4. **Repeat** — Add the next test case.
-
-**Tips for C++ TDD:**
-- Keep tests compilable at all times (even if currently failing).
-- Use `ASSERT_*` when continued execution after failure is meaningless.
-- Write one logical assertion per test (multiple `EXPECT_*` is fine).
-- Name tests `Subject_Under_Test_Behavior_Expected`. Example: `RespFallback_returns_original_when_fallback_unavailable`.
-
-See `references/tdd-workflow.md` for a step-by-step walkthrough.
-
-## Coverage
-
-**80% line coverage** is the default gate. For a test-gate to pass:
-- At least 80% of all `.cpp` files in `main/` and `components/` must be covered.
-- **Exclude:** mock files (`*_mock.cpp`, `*_mock.h`), generated code, third-party sources.
-- Coverage is measured with `gcov` / `lcov`. Run: `cmake --build build -- -j && lcov --capture --directory . --output coverage.info --exclude '*/mocks/*' --exclude '*/build/*'`
-
-**What to cover:**
-- All public class methods (including error paths)
-- All `if/else` and `switch` branches
-- Edge cases: empty input, null pointers, boundary values, error returns
-- Negative tests: verify the code fails gracefully for bad inputs
-
-See `references/coverage.md` for `gcov`/`lcov` setup and exclusion patterns.
-
-## Mocking Strategies
-
-### 1. Abstract Interface (Dependency Inversion)
-
-Define a pure virtual interface and inject a test double:
-
-```cpp
-// interfaces.h
-struct IFeatureStorage {
-  virtual bool read(const char* key, std::string& out) = 0;
-  virtual ~IFeatureStorage() = default;
-};
-
-// production code uses IFeatureStorage*
-class FeatureFlags {
-public:
-  explicit FeatureFlags(IFeatureStorage* storage) : storage_(storage) {}
-  bool is_active(const char* name);
-private:
-  IFeatureStorage* storage_;
-};
-
-// test double
-struct FakeStorage : IFeatureStorage {
-  bool read(const char* key, std::string& out) override {
-    if (strcmp(key, "debug") == 0) { out = "true"; return true; }
-    return false;
-  }
-};
-
-TEST(FeatureFlags, uses_injected_storage) {
-  FakeStorage fake;
-  FeatureFlags ff(&fake);
-  EXPECT_TRUE(ff.is_active("debug"));
-}
-```
-
-### 2. Link-Time Seam
-
-Compile the module under test with a fake implementation at link time. Replace the real `*.cpp` with a test stub. Useful when you cannot modify the source or inject dependencies:
-
-```cmake
-# Link test stub instead of production implementation
-target_sources(test_feature_flags PRIVATE fake_feature_flags.cpp)
-```
-
-### 3. `std::function` Injection
-
-Pass behavior as `std::function` for runtime flexibility:
-
-```cpp
-class RespFallback {
-public:
-  using response_check_t = std::function<bool(const Response&)>;
-  explicit RespFallback(response_check_t checker) : checker_(std::move(checker)) {}
-  // ...
-};
-```
-
-This is the lightest option — no interface hierarchy needed.
-
-See `references/mocking.md` for detailed patterns and tradeoffs.
-
-## Fixtures and TEST_F / TEST_P
-
-### TEST_F (Fixture-based)
-
-Use `TEST_F` when multiple tests share setup/teardown logic:
-
-```cpp
-class DatacollectorTest : public ::testing::Test {
-protected:
-  void SetUp() override { collector_ = std::make_unique<Datacollector>(); }
-  void TearDown() override { collector_.reset(); }
-  std::unique_ptr<Datacollector> collector_;
-};
-
-TEST_F(DatacollectorTest, appends_reading) {
-  collector_->append(42.0);
-  EXPECT_DOUBLE_EQ(collector_->latest(), 42.0);
-}
-```
-
-### TEST_P (Parametric)
-
-Use `TEST_P` when the same test logic applies to multiple parameter sets:
-
-```cpp
-class RespFallbackParamTest : public ::testing::TestWithParam<const char*> {};
-
-TEST_P(RespFallbackParamTest, handles_named_response) {
-  const char* name = GetParam();
-  RespFallback rf;
-  EXPECT_NO_THROW(rf.process(name));
-}
-
-INSTANTIATE_TEST_SUITE_P(NamedResponses, RespFallbackParamTest,
-  ::testing::Values("keepalive", "chunked", "gzip"));
-```
-
-## Assertion Choice: EXPECT_* vs ASSERT_*
-
-| Macro | Behavior on failure | Use when... |
-|-------|---------------------|-------------|
-| `EXPECT_*` | Continues test execution | Primary assertions; multiple related checks |
-| `ASSERT_*` | Aborts immediately | Precondition failure; continuing is meaningless |
-
-**Rule:** Default to `EXPECT_*`. Use `ASSERT_*` when failure would make subsequent assertions invalid (e.g., null pointer dereference, file open failure).
-
-## Test Naming Convention
-
-Follow the pattern: `Subject_Under_Test_Behavior_Expected`
-
-```
-RespFallback_returns_original_when_fallback_unavailable
-FeatureFlags_is_active_returns_true_for_enabled_feature
-Datacollector_latest_throws_when_collection_empty
-```
-
-Avoid: `test1`, `TestFeatureFlags`, `test_is_active` — they don't communicate intent.
-
-## Common Anti-Patterns
-
-1. **Testing private methods** — Test the public interface only. Private method changes break tests unnecessarily.
-2. **Overspecifying** — Don't assert on exact ordering unless that's the contract. Prefer behavioral assertions.
-3. **Missing negative tests** — Always test the error/edge path, not just the happy path.
-4. **Global state leakage** — Each test must be independent. Reset shared state in `SetUp()`.
-5. **Mocking too much** — If you're mocking everything, you're not testing the real code. Prefer integration tests for module interactions.
-6. **Flaky tests** — Avoid timing, threading races, and filesystem dependencies in unit tests.
-
-## Do / Don't
-
-### Do
-
-```cpp
-// DO: Use descriptive test names
-TEST(FeatureFlags, is_active_returns_false_for_unknown_feature) {
-  EXPECT_FALSE(flags.is_active("nonexistent"));
-}
-
-// DO: Use ASSERT_* for preconditions
-TEST(Datacollector, latest_throws_when_empty) {
-  ASSERT_FALSE(collector->has_readings());  // guard before calling latest()
-  EXPECT_THROW(collector->latest(), std::runtime_error);
-}
-
-// DO: Test through the public interface
-TEST(RespFallback, returns_original_when_fallback_missing) {
-  RespFallback rf;
-  Response out = rf.process(Response{"original"});
-  EXPECT_EQ(out.payload, "original");
-}
-```
-
-### Don't
-
-```cpp
-// DON'T: Test private methods — test the public API instead
-TEST(FeatureFlags, DISABLED_test_internal_state) { /* ... */ }
-
-// DON'T: Overspecify — don't assert on internal state
-TEST(FeatureFlags, is_active_caches_result) {  // fragile, tests implementation
-  flags.is_active("debug");
-  EXPECT_EQ(flags.cache_size(), 1);  // too specific
-}
-
-// DON'T: Forget negative tests
-TEST(FeatureFlags, is_active_handles_nullptr) {
-  // Always test error paths
-  EXPECT_FALSE(flags.is_active(nullptr));
-}
-```
-
-## References
-
-Detailed guides on specific topics:
-
-- **`references/framework-compare.md`** — GoogleTest vs Catch2 vs doctest with code samples
-- **`references/host-test-for-embedded.md`** — CMake host-test setup, testing policy modules without ESP-IDF
-- **`references/mocking.md`** — Abstract interfaces, link-time seams, `std::function` injection
-- **`references/tdd-workflow.md`** — Red-green-refactor walkthrough in C++
-- **`references/coverage.md`** — gcov/lcov setup, 80% gate, what to exclude

package/.claude/skills/cpp-testing/references/coverage.md

@@ -1,370 +0,0 @@
-# Coverage for C++ Tests
-
-## Overview
-
-Coverage measures which lines of production code are executed by your tests. The 80% line coverage gate means at least 80% of non-excluded lines must be covered before merging. This reference covers measurement tools, interpretation, exclusion patterns, and enforcement.
-
----
-
-## Tools
-
-| Tool | Description | Notes |
-|------|-------------|-------|
-| **gcov** | GCC's coverage tool — comes with `gcc` | Works with any CMake project compiled with `-fprofile-arcs -ftest-coverage` |
-| **lcov** | Front-end for gcov — generates HTML/JSON reports | `apt install lcov` |
-| **gcovr** | Alternative — generates Cobertura XML for CI | `pip install gcovr` |
-
----
-
-## Setup
-
-### CMake Integration
-
-```cmake
-# test/host/CMakeLists.txt
-option(COVERAGE "Enable coverage reporting" OFF)
-
-if(COVERAGE)
-  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fprofile-arcs -ftest-coverage")
-  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fprofile-arcs -ftest-coverage")
-endif()
-
-# link gtest normally
-target_link_libraries(test_policy PRIVATE gtest gmock pthread)
-
-# on Linux, link gcov explicitly
-if(COVERAGE)
-  target_link_libraries(test_policy PRIVATE gcov)
-endif()
-```
-
-### Build and Capture
-
-```bash
-cd test/host && mkdir -p build && cd build
-cmake .. -DCOVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
-cmake --build . -j$(nproc)
-./test_policy          # run tests — gcov writes .gcda/.gcno files
-lcov --capture --directory . --output coverage.info \
-  --exclude '*/test_*' \
-  --exclude '*/stubs/*' \
-  --exclude '*/build/*' \
-  --exclude '*/googletest/*' \
-  --exclude '*/.cache/*'
-```
-
-### View HTML Report
-
-```bash
-genhtml coverage.info --output-directory coverage_html
-# Open coverage_html/index.html in browser
-```
-
-### Check Only Source Files (not test code)
-
-```bash
-# Filter to only main/ and components/ sources
-lcov --extract coverage.info '*/main/*' --output filtered.info
-lcov --list filtered.info
-```
-
----
-
-## What 80% Coverage Means
-
-| Metric | Description | Target |
-|--------|-------------|--------|
-| **Line coverage** | Percentage of source lines executed | ≥ 80% |
-| **Branch coverage** | Percentage of branches (if/else, switch) taken | Not explicitly gated, but inspect for untested branches |
-| **Function coverage** | Percentage of functions called | Should be 100% for public APIs |
-
-**80% line coverage does NOT mean:**
-- Every function is tested
-- Every branch is exercised
-- The code is bug-free
-
-It means 80% of **executable lines** were executed at least once. You still need:
-- Branch coverage for `if/else` and `switch`
-- Negative tests for error paths
-- Boundary value tests
-
----
-
-## Files to Exclude
-
-Exclude these from coverage reports:
-
-```
-*/test_*           — test source files (test_*.cpp)
-*/stubs/*          — test stubs (freertos_stubs.cpp, etc.)
-*/build/*          — CMake build directory
-*/mocks/*          — mock implementations
-*/googletest/*     — GoogleTest source
-*/.cache/*         — any cache directories
-*/generated/*      — auto-generated code
-*/third_party/*    — third-party dependencies
-```
-
-### lcov Exclude Pattern
-
-```bash
-lcov --capture --directory . \
-  --output coverage.info \
-  --exclude '*/test_*' \
-  --exclude '*/stubs/*' \
-  --exclude '*/build/*' \
-  --exclude '*/googletest/*' \
-  --exclude '*/third_party/*'
-```
-
----
-
-## CI Integration: Enforcing the 80% Gate
-
-### GitHub Actions
-
-```yaml
-- name: Run host tests with coverage
-  run: |
-    cd test/host
-    mkdir -p build && cd build
-    cmake .. -DCOVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
-    cmake --build . -j$(nproc)
-    ./test_policy || { cat test_output.log; exit 1; }
-
-- name: Capture coverage
-  run: |
-    lcov --capture --directory test/host/build \
-      --output coverage.info \
-      --exclude '*/test_*' --exclude '*/stubs/*' --exclude '*/build/*' \
-      --exclude '*/googletest/*'
-    lcov --extract coverage.info '*/main/*' --output src_coverage.info
-    lcov --list src_coverage.info
-
-- name: Check 80% gate
-  run: |
-    total=$(lcov --list src_coverage.info | grep -E "lines\.\.\." | awk '{print $2}' | tr -d '%')
-    echo "Coverage: $total%"
-    if (( $(echo "$total < 80" | bc -l) )); then
-      echo "ERROR: Coverage $total% < 80% gate"
-      lcov --list src_coverage.info
-      exit 1
-    fi
-```
-
-### GitLab CI
-
-```yaml
-coverage-test:
-  script:
-    - mkdir -p build && cd build
-    - cmake .. -DCOVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
-    - cmake --build . -j$(nproc)
-    - ./test_policy
-    - lcov --capture --directory . --output coverage.info \
-        --exclude '*/test_*' --exclude '*/stubs/*' --exclude '*/build/*'
-    - lcov --extract coverage.info '*/main/*' --output src_coverage.info
-    - lcov --list src_coverage.info
-  coverage: /lines\.\.\.: (\d+\.\d+)%/
-```
-
----
-
-## Interpreting Coverage Reports
-
-### What "covered" means
-
-A line is covered if **any test** executes it at least once.
-
-```cpp
-bool is_valid(int x) {
-  if (x > 0)     // line 2 — covered if x=1 tested
-    return true; // line 3 — covered if x=1 tested
-  return false;  // line 5 — covered if x=-1 tested
-}
-```
-
-### What "not covered" means
-
-```bash
-$ lcov --list filtered.info
-Overall coverage rate:
-  lines......: 73.5%  (217 / 295)
-  branches...: 58.3%  (42 / 72)
-```
-
-- **lines 73.5%** — below 80%, gate fails
-- **branches 58.3%** — some `if` branches untested; add negative tests
-
-### Finding Uncovered Lines
-
-```bash
-genhtml coverage.info --output-directory html --show-details
-# Open html/*/*.cpp.gcov.html — uncovered lines are highlighted red
-```
-
-Or use `gcovr`:
-
-```bash
-gcovr --filter main/ --xml-pretty > coverage.xml
-# coverage.xml can be imported into GitHub PR checks
-```
-
----
-
-## Coverage Gaps: How to Find and Fix
-
-### 1. Uncovered Functions
-
-```bash
-lcov --list filtered.info | grep -E "function.*0\.0"
-```
-
-**Fix:** Write a test that calls the function.
-
-### 2. Uncovered Branches
-
-```bash
-lcov --list filtered.info | grep -E "branch.*not executed"
-```
-
-**Fix:** Add a test for the untaken branch. Example: if `if (ptr == nullptr)` is untested, add:
-
-```cpp
-TEST(Datacollector, append_handles_nullptr) {
-  EXPECT_EQ(datacollector_append(nullptr, 42.0), -1);
-}
-```
-
-### 3. Uncovered Error Paths
-
-```cpp
-// production code
-int datacollector_append(Datacollector* dc, double value) {
-  if (dc == nullptr) return -1;   // ← often untested
-  if (dc->count >= MAX) return -1;  // ← sometimes untested
-  dc->readings[dc->count++] = value;
-  return 0;
-}
-```
-
-**Fix:** Add tests for both error conditions:
-
-```cpp
-TEST(Datacollector, append_returns_error_for_nullptr) {
-  EXPECT_EQ(datacollector_append(nullptr, 42.0), -1);
-}
-
-TEST(Datacollector, append_returns_error_when_full) {
-  Datacollector dc;
-  for (int i = 0; i < MAX; ++i) datacollector_append(&dc, 0.0);
-  EXPECT_EQ(datacollector_append(&dc, 99.0), -1);
-}
-```
-
----
-
-## Coverage Exclusions: When and How
-
-### Exclude Generated Code
-
-```cmake
-# In CMakeLists.txt — mark generated sources
-set_source_files_properties(
-    ${CMAKE_CURRENT_SOURCE_DIR}/generated/serde_autogen.cpp
-    PROPERTIES HEADER_FILE_ONLY ON
-)
-```
-
-Or via `lcov --remove`:
-
-```bash
-lcov --remove coverage.info '*/generated/*' --output cleaned.info
-```
-
-### Exclude Test Stubs
-
-```bash
-lcov --remove coverage.info '*/stubs/*' --output cleaned.info
-```
-
-### Exclude Platform-Specific Code
-
-```cpp
-// coverage: ignore start
-#ifdef ESP_PLATFORM
-    // ESP-IDF only
-#endif
-// coverage: ignore end
-```
-
-Note: GCC supports `#pragma GCC coverage_options` but it's fragile. Prefer exclusion at the `lcov` level.
-
----
-
-## Common Pitfalls
-
-### 1. 100% Coverage ≠ Correct Code
-
-```cpp
-// Tests achieve 100% coverage but don't test correctness
-TEST(Math, add_returns_something) {
-  EXPECT_NE(add(2, 2), 0);  // passes for add(2,2)=99 — wrong!
-}
-```
-
-**Fix:** Test for **exact expected values**, not just non-zero.
-
-### 2. Over-Excluding Files
-
-Excluding `*_test.cpp` is fine. Excluding entire modules because they're "hard to test" is a smell — those modules need redesign.
-
-### 3. Coverage as a Goal
-
-Writing tests to increase coverage % (rather than to verify behavior) leads to:
-- Meaningless tests (e.g., `EXPECT_TRUE(true)`)
-- Skipped edge cases
-- False confidence
-
-Coverage is a **minimum bar**, not a target. Aim for **behavioral correctness** first.
-
----
-
-## Quick Reference: Coverage Commands
-
-```bash
-# Full pipeline
-cd test/host && mkdir -p build && cd build
-cmake .. -DCOVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
-cmake --build . -j$(nproc)
-./test_policy || exit 1
-
-# Capture (all files)
-lcov --capture --directory . --output coverage.info \
-  --exclude '*/test_*' --exclude '*/stubs/*' --exclude '*/build/*'
-
-# Filter to only main/
-lcov --extract coverage.info '*/main/*' --output src_coverage.info
-
-# List summary
-lcov --list src_coverage.info
-
-# HTML output
-genhtml src_coverage.info --output-directory coverage_html
-
-# Enforce 80% gate
-total=$(lcov --list src_coverage.info | grep "lines" | awk '{print $2}' | tr -d '%')
-python3 -c "exit(0 if float('$total') >= 80.0 else 1)" || \
-  { echo "FAIL: coverage $total% < 80%"; lcov --list src_coverage.info; exit 1; }
-```
-
----
-
-## Summary
-
-- **Measure:** Use `gcov` + `lcov` (or `gcovr`) to capture and report coverage
-- **Exclude:** Test files, stubs, mocks, generated code, third-party deps
-- **Gate:** 80% line coverage on `main/` and `components/` (non-ESP-IDF)
-- **Inspect:** Check branch coverage for untested `if/else` paths
-- **Fix:** Add tests for uncovered lines and branches, not just to raise %
-- **CI:** Enforce the gate in CI before merging