@polderlabs/bizar 9.0.0 → 10.0.7

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

@@ -1,364 +0,0 @@
-# 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/skills/cpp-testing/references/tdd-workflow.md

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