@polderlabs/bizar 8.1.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/config/skills/cpp-testing/SKILL.md

@@ -0,0 +1,304 @@
+---
+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/worktrees/kanban-overhaul/config/skills/cpp-testing/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "C++ Testing"
+  short_description: "C++ unit, integration, and host test patterns"
+  default_prompt: "Use $cpp-testing to design or improve C++ test coverage, host tests, and TDD workflows."

package/.claude/worktrees/kanban-overhaul/config/skills/cpp-testing/references/coverage.md

@@ -0,0 +1,370 @@
+# 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