@polderlabs/bizar 8.0.0 → 9.0.0

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

@@ -0,0 +1,364 @@
+# Mocking Strategies in C++
+
+## Overview
+
+Mocking lets you test a unit in isolation by replacing its dependencies with controlled test doubles. In C++, the three primary strategies are:
+
+1. **Abstract Interface** — dependency inversion with a pure virtual interface
+2. **Link-Time Seam** — replace a compiled object at link time
+3. **`std::function` Injection** — pass behavior as a callable at runtime
+
+Each has a different trade-off between isolation, compile-time cost, and how much you need to modify existing code.
+
+---
+
+## 1. Abstract Interface (Dependency Inversion)
+
+### Concept
+
+Define a pure virtual interface. The class under test accepts a pointer/reference to the interface. In tests, pass a fake implementation.
+
+### When to Use
+
+- You control the design and can introduce interfaces
+- You need fine-grained control over mock behavior (ON_CALL, EXPECT_CALL)
+- You want to test multiple implementations of the same interface
+
+### Code Example
+
+```cpp
+// === interfaces/sensor_reading.h ===
+#pragma once
+#include <cstdint>
+#include <optional>
+
+struct ISensor {
+  virtual ~ISensor() = default;
+  virtual std::optional<double> read() = 0;
+  virtual bool is_connected() = 0;
+};
+
+// === main/policy/temp_monitor.h ===
+#pragma once
+#include "sensor_reading.h"
+
+class TempMonitor {
+public:
+  explicit TempMonitor(ISensor* sensor) : sensor_(sensor) {}
+  bool has_valid_reading();
+  double last_reading();
+private:
+  ISensor* sensor_;
+};
+
+// === main/policy/temp_monitor.cpp ===
+#include "temp_monitor.h"
+#include <algorithm>
+
+bool TempMonitor::has_valid_reading() {
+  return sensor_->is_connected() && sensor_->read().has_value();
+}
+
+double TempMonitor::last_reading() {
+  auto v = sensor_->read();
+  return v.value_or(0.0);
+}
+
+// === test/host/test_temp_monitor.cpp ===
+#include <gtest/gtest.h>
+#include "temp_monitor.h"
+#include "sensor_reading.h"
+#include <optional>
+
+struct FakeSensor : ISensor {
+  std::optional<double> fake_value = std::nullopt;
+  bool connected = false;
+
+  std::optional<double> read() override { return fake_value; }
+  bool is_connected() override { return connected; }
+};
+
+TEST(TempMonitor, has_valid_reading_true_when_connected_and_has_value) {
+  FakeSensor fake;
+  fake.connected = true;
+  fake.fake_value = 23.5;
+  TempMonitor monitor(&fake);
+  EXPECT_TRUE(monitor.has_valid_reading());
+  EXPECT_DOUBLE_EQ(monitor.last_reading(), 23.5);
+}
+
+TEST(TempMonitor, has_valid_reading_false_when_disconnected) {
+  FakeSensor fake;
+  fake.connected = false;
+  fake.fake_value = 23.5;
+  TempMonitor monitor(&fake);
+  EXPECT_FALSE(monitor.has_valid_reading());
+}
+
+TEST(TempMonitor, has_valid_reading_false_when_no_value) {
+  FakeSensor fake;
+  fake.connected = true;
+  fake.fake_value = std::nullopt;
+  TempMonitor monitor(&fake);
+  EXPECT_FALSE(monitor.has_valid_reading());
+}
+```
+
+### Trade-offs
+
+| Pros | Cons |
+|------|------|
+| Full control over mock behavior | Requires interface in production code |
+| Works with `gmock` (`ON_CALL`, `EXPECT_CALL`) | Adds indirection to class design |
+| Tests are fully isolated | Can be verbose for simple cases |
+
+---
+
+## 2. Link-Time Seam
+
+### Concept
+
+Compile a different version of a file at link time to replace the production implementation. The test links its own `.cpp` that provides a minimal or fake implementation of the dependency.
+
+### When to Use
+
+- You cannot modify the existing production code to accept interfaces
+- The dependency is a single global function or static method
+- You want to test a module without any runtime injection mechanism
+
+### Code Example
+
+```cpp
+// === main/policy/heartbeat.h ===
+#pragma once
+bool heartbeat_send(uint32_t interval_ms);
+
+// === main/policy/heartbeat.cpp ===
+#include "heartbeat.h"
+#include "esp_timer.h"  // FreeRTOS/ESP-IDF — not available on host
+
+bool heartbeat_send(uint32_t interval_ms) {
+  esp_timer_start_periodic(..., interval_ms * 1000);
+  return true;
+}
+
+// === test/host/CMakeLists.txt ===
+# Replace real heartbeat.cpp with stub at link time
+add_executable(test_heartbeat
+    test_heartbeat.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../main/policy/heartbeat.cpp   # production
+    ${CMAKE_CURRENT_SOURCE_DIR}/stubs/heartbeat_stub.cpp          # our fake
+)
+```
+
+```cpp
+// === test/host/stubs/heartbeat_stub.cpp ===
+#include "heartbeat.h"
+
+bool heartbeat_send(uint32_t interval_ms) {
+  // No-op on host — just return true
+  (void)interval_ms;
+  return true;
+}
+```
+
+```cpp
+// === test/host/test_heartbeat.cpp ===
+#include <gtest/gtest.h>
+#include "heartbeat.h"
+
+TEST(Heartbeat, send_returns_true) {
+  EXPECT_TRUE(heartbeat_send(1000));
+}
+
+TEST(Heartbeat, send_accepts_zero_interval) {
+  EXPECT_TRUE(heartbeat_send(0));
+}
+```
+
+### Trade-offs
+
+| Pros | Cons |
+|------|------|
+| No production code changes needed | Only works when you control what's linked |
+| Works with any C/C++ function | Can mask integration issues if stub is too fake |
+| Simple to implement | No runtime control — compile-time replacement only |
+
+---
+
+## 3. `std::function` Injection
+
+### Concept
+
+Make behavior injectable via `std::function` member variables set at construction or via setters. No interface hierarchy needed.
+
+### When to Use
+
+- You want minimal boilerplate
+- The dependency is a simple callable (function, functor, lambda)
+- You don't need `gmock` expectations — simple behavior is enough
+
+### Code Example
+
+```cpp
+// === main/policy/resp_fallback.h ===
+#pragma once
+#include <functional>
+#include "resp_fallback_types.h"  // Response, FallbackResult
+
+class RespFallback {
+public:
+  using response_check_t = std::function<bool(const Response&)>;
+  using fallback_fn_t = std::function<FallbackResult(const Response*, Response*)>;
+
+  explicit RespFallback(response_check_t checker = nullptr,
+                        fallback_fn_t fallback_fn = nullptr)
+      : checker_(std::move(checker)), fallback_fn_(std::move(fallback_fn)) {}
+
+  FallbackResult process(const Response* req, Response* out);
+
+private:
+  response_check_t checker_;
+  fallback_fn_t fallback_fn_;
+};
+
+// === test/host/test_resp_fallback.cpp ===
+#include <gtest/gtest.h>
+#include "resp_fallback.h"
+
+TEST(RespFallback, uses_checker_when_provided) {
+  bool checker_called = false;
+  RespFallback rf(
+    [&checker_called](const Response&) {
+      checker_called = true;
+      return true;
+    },
+    nullptr
+  );
+  Response out;
+  Response in = { .payload = "test", .payload_len = 4, .status_code = 500 };
+  rf.process(&in, &out);
+  EXPECT_TRUE(checker_called);
+}
+
+TEST(RespFallback, uses_fallback_fn_when_checker_fails) {
+  bool fallback_called = false;
+  RespFallback rf(
+    [](const Response&) { return false; },  // checker returns false
+    [&fallback_called](const Response*, Response* out) {
+      fallback_called = true;
+      out->payload = "fallback";
+      out->status_code = 200;
+      return FallbackResult::FALLBACK_OK;
+    }
+  );
+  Response out;
+  Response in = { .payload = "error", .payload_len = 5, .status_code = 500 };
+  FallbackResult r = rf.process(&in, &out);
+  EXPECT_TRUE(fallback_called);
+  EXPECT_EQ(r, FallbackResult::FALLBACK_OK);
+}
+```
+
+### Trade-offs
+
+| Pros | Cons |
+|------|------|
+| Zero boilerplate — no interface needed | Cannot use `EXPECT_CALL` / `ON_CALL` with gmock |
+| Lambda-friendly | Lambdas can't be stored in `std::function` if they capture |
+| Works with existing code (add a setter) | Tests must provide real behavior if production doesn't |
+
+---
+
+## 4. gmock (GoogleMock) — Struct-Level MATCHER
+
+When using GoogleTest, `gmock` provides `MATCHER` and `ON_CALL` for fine-grained expectations on structs:
+
+```cpp
+#include <gmock/gmock.h>
+#include <gtest/gtest.h>
+
+struct Reading {
+  double temperature;
+  uint32_t timestamp;
+};
+
+MATCHER_P(TempNear, expected, "") {
+  return std::abs(arg.temperature - expected) < 0.5;
+}
+
+TEST(Sensor, reading_near_expected) {
+  ::testing::MockFunction<bool(const Reading&)> mock_check;
+  ON_CALL(mock_check, Call)
+    .WillByDefault(::testing::Return(true));
+
+  EXPECT_CALL(mock_check, Call(TempNear(25.0))).Times(1);
+
+  Reading r = { 25.1, 123456 };
+  mock_check.Call(r);
+}
+```
+
+For simple structs, `MATCHER` is cleaner than writing a full fake class.
+
+---
+
+## Choosing a Strategy
+
+| Situation | Recommended Strategy |
+|-----------|---------------------|
+| New code, you control design | Abstract Interface + `gmock` |
+| Testing existing code with no interface | Link-Time Seam |
+| Simple callable dependency, no gmock needed | `std::function` Injection |
+| Struct-level assertions | `MATCHER` / `ON_CALL` |
+| Need `EXPECT_CALL` with complex behavior | Abstract Interface + `gmock` |
+| FreeRTOS/ESP-IDF call in production code | Link-Time Seam (stub at link) |
+
+---
+
+## Anti-Patterns
+
+### Don't Over-Mock
+
+```cpp
+// BAD — mocking everything means you're not testing real code
+TEST(System, processes_data) {
+  auto mock_storage = std::make_unique<MockStorage>();
+  auto mock_network = std::make_unique<MockNetwork>();
+  ON_CALL(*mock_storage, read).WillByDefault(...);
+  ON_CALL(*mock_network, send).WillByDefault(...);
+  System sys(std::move(mock_storage), std::move(mock_network));
+  // This tests nothing real
+}
+```
+
+**Better:** Test `System` with real `Storage` and mocked `Network`, or vice versa. Only mock at boundaries.
+
+### Don't Mock Value Types
+
+```cpp
+// BAD — no need to mock a simple struct
+struct Config { int timeout_ms; bool enabled; };
+
+// GOOD — construct directly, no mock needed
+Config cfg{1000, true};
+```
+
+### Don't Mock Stateless Utilities
+
+```cpp
+// BAD — mocking a pure function like strlen is wasteful
+// GOOD — just call strlen in tests directly
+EXPECT_EQ(strlen("hello"), 5);
+```
+
+---
+
+## Combining Strategies
+
+You can combine strategies in the same project. For example:
+- Use **Abstract Interface** for `ISensor`, `IStorage` (core domain interfaces)
+- Use **Link-Time Seam** for FreeRTOS / ESP-IDF API calls
+- Use **`std::function`** for simple policy callbacks
+
+The key principle: **mock at boundaries, not deep inside the system**.

package/.claude/worktrees/kanban-overhaul/.claude/skills/cpp-testing/references/tdd-workflow.md

@@ -0,0 +1,308 @@
+# TDD Workflow for C++
+
+## Overview
+
+Test-Driven Development (TDD) follows a short red-green-refactor cycle:
+
+1. **Red** — Write a failing test before touching production code.
+2. **Green** — Write the minimum production code to make the test pass.
+3. **Refactor** — Clean up both test and production code, keeping tests green.
+
+The goal is **narrow, fast feedback**: every line of production code has a failing test that motivated it.
+
+---
+
+## The Cycle in Detail
+
+### Step 1: Red — Write a Failing Test
+
+Write the smallest possible test that describes the behavior you want:
+
+```cpp
+// test/host/test_rate_limiter.cpp
+#include <gtest/gtest.h>
+#include "rate_limiter.h"
+
+TEST(RateLimiter, allows_request_under_limit) {
+  RateLimiter rl(10);  // 10 requests per second
+  // First request should be allowed
+  EXPECT_TRUE(rl.allow());
+}
+```
+
+Compile and run. It **must fail** because `rate_limiter.h` / `rate_limiter.cpp` don't exist yet:
+
+```
+error: 'RateLimiter' file not found
+```
+
+This is the correct outcome — you've specified what you want before building it.
+
+### Step 2: Green — Write Minimum Production Code
+
+Create the stub to make it compile, then the implementation to make it pass:
+
+```cpp
+// main/policy/rate_limiter.h
+#pragma once
+class RateLimiter {
+public:
+  explicit RateLimiter(int max_per_second);
+  bool allow();
+};
+```
+
+```cpp
+// main/policy/rate_limiter.cpp
+#include "rate_limiter.h"
+
+RateLimiter::RateLimiter(int max_per_second) {}
+bool RateLimiter::allow() { return true; }  // minimum: always allow
+```
+
+Run tests — they should pass. You now have a compiling, passing test.
+
+### Step 3: Refactor
+
+Now add the second test:
+
+```cpp
+TEST(RateLimiter, blocks_request_over_limit) {
+  RateLimiter rl(2);
+  rl.allow();  // request 1
+  rl.allow();  // request 2
+  EXPECT_FALSE(rl.allow());  // request 3 — over limit
+}
+```
+
+Run tests — this new test **fails** (current impl always returns `true`). Go back to Step 2.
+
+```cpp
+// main/policy/rate_limiter.cpp — minimum change
+#include "rate_limiter.h"
+#include <atomic>
+
+RateLimiter::RateLimiter(int max_per_second) : max_per_second_(max_per_second), count_(0) {}
+
+bool RateLimiter::allow() {
+  int current = count_.load();
+  if (current >= max_per_second_) return false;
+  count_.store(current + 1);
+  return true;
+}
+```
+
+Run tests — all pass. Repeat the cycle.
+
+---
+
+## Structuring Tests for TDD
+
+### Arrange-Act-Assert (AAA)
+
+```cpp
+TEST(RateLimiter, blocks_over_limit) {
+  // Arrange
+  RateLimiter rl(1);
+  rl.allow();  // consume the one allowed request
+
+  // Act
+  bool allowed = rl.allow();
+
+  // Assert
+  EXPECT_FALSE(allowed);
+}
+```
+
+### One Logical Assertion Per Test
+
+Prefer multiple `EXPECT_*` calls that are all checking related aspects of one behavior over one test per `EXPECT_*`. Example:
+
+```cpp
+// Good — one test, multiple related EXPECTs
+TEST(RespFallback, error_returns_fallback_and_sets_status) {
+  Response in = { .payload = "error", .payload_len = 5, .status_code = 500 };
+  Response out;
+  FallbackResult r = resp_fallback_process(&in, &out);
+  EXPECT_EQ(r, FALLBACK_OK);
+  EXPECT_EQ(out.status_code, 200);
+  EXPECT_STREQ(out.payload, "default_response");
+}
+```
+
+### Test Naming for TDD
+
+Name tests to describe **behavior**, not implementation:
+
+```
+GOOD:  RespFallback_returns_fallback_when_upstream_fails
+GOOD:  Datacollector_append_returns_minus_one_when_full
+BAD:   TestRespFallback  (no behavior described)
+BAD:   Test1             (meaningless)
+```
+
+---
+
+## TDD for Embedded Firmware Modules
+
+### Example: `feature_flags.cpp` from scratch
+
+**Start:** You have an empty `feature_flags.cpp` with only a header stub.
+
+**Test 1:** `is_active_returns_false_for_unknown_feature`
+
+```cpp
+TEST(FeatureFlags, is_active_returns_false_for_unknown_feature) {
+  EXPECT_FALSE(feature_flags_is_active("nonexistent"));
+}
+```
+
+Compile → link error (no implementation). Add stub:
+
+```cpp
+bool feature_flags_is_active(const char* name) { return false; }
+```
+
+Test passes. (You chose the simplest implementation that makes the test pass.)
+
+**Test 2:** `is_active_returns_true_for_known_feature`
+
+```cpp
+TEST(FeatureFlags, is_active_returns_true_for_known_feature) {
+  EXPECT_TRUE(feature_flags_is_active("debug"));
+}
+```
+
+Test fails (still returns `false`). Implement:
+
+```cpp
+bool feature_flags_is_active(const char* name) {
+  if (strcmp(name, "debug") == 0) return true;
+  return false;
+}
+```
+
+Test passes.
+
+**Test 3:** `is_active_returns_false_for_nullptr`
+
+```cpp
+TEST(FeatureFlags, is_active_returns_false_for_nullptr) {
+  EXPECT_FALSE(feature_flags_is_active(nullptr));
+}
+```
+
+Add the null check. Tests pass.
+
+**Refactor:** Replace chain of `if/strcmp` with a lookup table:
+
+```cpp
+static bool flags[] = { false, false, false };  // debug=0, trace=1, legacy=2
+```
+
+The tests **still pass** because they assert on behavior, not representation.
+
+---
+
+## Red-Green-Refactor in Practice
+
+### Red Flags (stop and refactor if you see these)
+
+- **Test takes too long to write** — break it into smaller pieces
+- **Test requires many mocks** — the module under test may have too many dependencies (consider interface injection)
+- **Production code can't be tested in isolation** — the module needs refactoring before tests can be written
+- **Tests are brittle** — if renaming a private method breaks a test, you're testing the wrong thing
+
+### Refactoring Rules
+
+1. **Never change tests to make production code pass.** Change production code to make tests pass.
+2. **Keep tests deterministic.** No random values, no timing dependencies.
+3. **Test behavior, not implementation.** If you refactor internal representation and tests break, the tests were overspecified.
+4. **Run the full test suite after every refactor** — green before, green after.
+
+---
+
+## What to Test First
+
+### Priority 1: Happy Path (primary behavior)
+
+```cpp
+TEST(RateLimiter, allows_requests_under_limit) { ... }
+```
+
+### Priority 2: Edge Cases (boundary values)
+
+```cpp
+TEST(RateLimiter, allows_zero_limit_as_always_blocked) { ... }
+TEST(RateLimiter, handles_negative_limit) { ... }  // invalid input
+```
+
+### Priority 3: Error Paths
+
+```cpp
+TEST(Datacollector, append_returns_error_when_full) { ... }
+TEST(RespFallback, returns_invalid_when_nullptr) { ... }
+```
+
+### Priority 4: Negative Tests (the "what shouldn't happen")
+
+```cpp
+TEST(FeatureFlags, is_active_does_not_crash_on_nullptr) { ... }
+TEST(RateLimiter, does_not_allow_over_limit_regardless_of_speed) { ... }
+```
+
+---
+
+## Test Coverage in TDD
+
+TDD naturally drives coverage high because:
+- Every line of production code was written to satisfy a test
+- You can't add code without a failing test first
+
+However, TDD alone doesn't guarantee 80% coverage. Run `lcov` after the full suite to identify untested branches:
+
+```bash
+cmake --build build -j$(nproc)
+./test_policy
+lcov --capture --directory build --output coverage.info \
+  --exclude '*/test_*' --exclude '*/stubs/*' --exclude '*/build/*'
+lcov --list coverage.info  # inspect
+```
+
+Add missing tests for any uncovered lines before opening a PR.
+
+---
+
+## When TDD Is Not Worth It
+
+- **Trivial accessors** — `getter()` / `setter()` with no logic
+- **Generated code** — auto-generated `serde`, `protobuf` bindings
+- **One-off scripts** — not part of the production codebase
+- **Quick prototypes** — exploratory code that will be thrown away
+
+For these, write tests **after** if the code becomes permanent.
+
+---
+
+## TDD and the 80% Coverage Gate
+
+TDD gets you to ~60-70% coverage naturally. The last 10-20% requires disciplined addition of:
+
+1. **Branch coverage** — every `if/else` and `switch` branch
+2. **Error paths** — every function that can return an error code
+3. **Negative tests** — every `if (ptr == nullptr)` path
+
+Use `lcov --list coverage.info | grep -E "BRAN|BR" ` to find uncovered branches.
+
+---
+
+## Summary: TDD Checklist
+
+Before each commit:
+- [ ] Every new public method has at least one test
+- [ ] Tests follow AAA structure
+- [ ] Test names describe behavior (Subject_Behavior_Expected)
+- [ ] Tests pass on first run (green)
+- [ ] No test is skipped (`DISABLED_`) unless there's a tracked issue
+- [ ] 80% line coverage gate passes (`lcov`)
+- [ ] No new `// TODO` or `// FIXME` in test code