@polderlabs/bizar 8.0.0 → 9.0.0

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

@@ -0,0 +1,175 @@
+# Framework Compare: GoogleTest vs Catch2 vs doctest
+
+## Overview
+
+All three frameworks are C++17-compatible, header-only (or single-header), and support fixtures, parametrics, and mocking. The choice is primarily ergonomic and project-specific.
+
+---
+
+## GoogleTest
+
+**Installation:** `apt install libgtest-dev` or `FetchContent` CMake include.
+
+**Strengths:**
+- `TEST_F` (fixture), `TEST_P` (parametric), death tests, `ScopedFakeTimer`
+- Widest ecosystem: `gmock` for mocking, `gtest-param-test` for parameterized
+- XML/JSON/HTML output for CI integration
+- Well-understood by embedded/firmware teams
+
+**Sample:**
+
+```cpp
+#include <gtest/gtest.h>
+
+class StackTest : public ::testing::Test {
+protected:
+  void SetUp() override { stack_.clear(); }
+  std::vector<int> stack_;
+};
+
+TEST_F(StackTest, push_increases_size) {
+  stack_.push_back(1);
+  EXPECT_EQ(stack_.size(), 1u);
+}
+
+TEST_F(StackTest, pop_returns_last_element) {
+  stack_.push_back(1);
+  stack_.push_back(2);
+  EXPECT_EQ(stack_.back(), 2);
+  stack_.pop_back();
+  EXPECT_EQ(stack_.size(), 1u);
+}
+```
+
+**Parametric example:**
+
+```cpp
+class StringEncodeTest : public ::testing::TestWithParam<const char*> {};
+
+TEST_P(StringEncodeTest, encodes_known_formats) {
+  const char* fmt = GetParam();
+  EXPECT_NO_THROW(encode(fmt));
+}
+
+INSTANTIATE_TEST_SUITE_P(KnownFormats, StringEncodeTest,
+  ::testing::Values("utf-8", "iso-8859-1", "windows-1252"));
+```
+
+**Best for:** Large codebases, embedded firmware, projects needing `gmock`, parametric tests, or death tests.
+
+---
+
+## Catch2
+
+**Installation:** Single header: `curl -L https://github.com/catchorg/Catch2/releases/download/v3.5.4/catch2_with_main.hpp -o include/catch2_with_main.hpp`
+
+**Strengths:**
+- BDD-style `SCENARIO` / `GIVEN` / `WHEN` / `THEN` DSL available
+- Minimal boilerplate — no `TEST_F` needed for simple cases
+- Rich assertion syntax: `REQUIRE`, `CHECK`, `REQUIRE_THAT`, `CHECK_THAT`
+
+**Sample:**
+
+```cpp
+#define CATCH_CONFIG_MAIN
+#include <catch2/catch_test_macros.hpp>
+
+unsigned int factorial(unsigned int n) {
+  return n <= 1 ? 1 : n * factorial(n - 1);
+}
+
+TEST_CASE("factorial computes correctly", "[factorial]") {
+  CHECK(factorial(0) == 1);
+  CHECK(factorial(1) == 1);
+  CHECK(factorial(4) == 24);
+  CHECK(factorial(5) == 120);
+}
+```
+
+**BDD-style:**
+
+```cpp
+SCENARIO("stack behavior") {
+  GIVEN("an empty stack") {
+    std::vector<int> stack;
+    WHEN("an element is pushed") {
+      stack.push_back(42);
+      THEN("size increases") { CHECK(stack.size() == 1); }
+    }
+  }
+}
+```
+
+**Best for:** Quick-to-write tests, BDD-style readability, smaller utilities.
+
+**Weakness:** Slower compile times than doctest; less ecosystem (no built-in mocking — pair with `trompeloeil` or manual fakes).
+
+---
+
+## doctest
+
+**Installation:** Single header: `curl -L https://github.com/doctest/doctest/releases/download/v2.4.11/doctest.h -o include/doctest.h`
+
+**Strengths:**
+- Fastest compile time of the three
+- Lightweight — minimal impact on build times
+- `CHECK`/`REQUIRE` similar to Catch2
+- Sub-test support via `SUBTEST`
+
+**Sample:**
+
+```cpp
+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
+#include <doctest/doctest.h>
+
+int add(int a, int b) { return a + b; }
+
+TEST_CASE("addition works") {
+  CHECK(add(2, 3) == 5);
+  CHECK(add(-1, 1) == 0);
+  REQUIRE(add(0, 0) == 0);  // REQUIRE aborts on failure
+}
+```
+
+**Best for:** Compile-time-sensitive projects, small-to-medium codebases, projects that already use many headers.
+
+**Weakness:** Smaller ecosystem; mocking requires manual fakes or `trompeloeil`.
+
+---
+
+## Side-by-Side Comparison
+
+| Feature | GoogleTest | Catch2 | doctest |
+|---------|-----------|--------|---------|
+| Header-only | No (needs gtest lib) | Yes | Yes |
+| Compile speed | Medium | Slow | Fast |
+| `TEST_F` (fixtures) | Yes | Via `SECTION` | Via `SUBCASE` |
+| `TEST_P` (parametric) | Yes | No | No |
+| Death tests | Yes | No | No |
+| Built-in mocking | gmock | No | No |
+| BDD DSL | No | Yes | No |
+| CI XML output | Yes | Yes | Yes |
+| C++17 required | Yes | Yes | Yes |
+| Ecosystem size | Large | Medium | Small |
+
+---
+
+## Recommendation for Embedded/Firmware Host Tests
+
+Default to **GoogleTest** + **gmock**:
+- `TEST_F` / `TEST_P` are well-suited to firmware policy modules
+- `gmock` provides struct-level mocking via `MATCHER` / `ON_CALL`
+- `EXPECT_DEATH` / `EXPECT_DEATH_IF_SUPPORTED` useful for error-injection tests
+- Widely understood — existing firmware teams will recognize it
+
+Use **Catch2** when you want BDD-style readability for payload parsing or protocol tests.
+
+Use **doctest** when build time is a bottleneck and you only need simple `CHECK` assertions.
+
+---
+
+## Mixing Frameworks
+
+It is possible to link multiple frameworks into the same binary, but avoid this — it causes confusion and doubled setup cost. Pick one framework per binary.
+
+If you need both BDD-style and parametric tests, use GoogleTest's `TEST_F` with `DESCRIPTION` or use Catch2's `SECTION` mechanism instead of `TEST_P`.

package/.claude/worktrees/kanban-overhaul/.claude/skills/cpp-testing/references/host-test-for-embedded.md

@@ -0,0 +1,499 @@
+# Host-Side Tests for Embedded Firmware
+
+## Goal
+
+Build a standalone Linux binary that links and executes C++ firmware code from `main/` or `components/` — with no ESP-IDF, no FreeRTOS, and no `idf.py`. The binary runs on the host (your laptop or CI runner) and exercises the real production code, just with mocked hardware/OS boundaries.
+
+This pattern is ideal for:
+- **Policy modules:** `feature_flags.cpp`, `resp_fallback.cpp`, `rate_limiter.cpp`
+- **Payload parsers:** `mqtt_payload.cpp`, `json_parser.cpp`
+- **Data collectors:** `datacollector.cpp`, `telemetry.cpp`
+
+---
+
+## Why Host-Side Tests?
+
+| On-Device (`idf.py test`) | Host-Side Binary |
+|---------------------------|------------------|
+| Runs on actual hardware | Runs on Linux/CI |
+| Needs device flashing | No hardware required |
+| Slow iteration | Fast iteration |
+| FreeRTOS available | No FreeRTOS |
+| ESP-IDF available | No ESP-IDF |
+| HW timing real | Deterministic |
+
+Host-side tests catch >80% of logic bugs before ever flashing. Use on-device tests only for hardware-specific behavior (interrupts, DMA, sensor drivers).
+
+---
+
+## Project Structure
+
+```
+projects/ams7_esp32/
+├── main/
+│   ├── policy/
+│   │   ├── feature_flags.cpp
+│   │   ├── feature_flags.h
+│   │   ├── resp_fallback.cpp
+│   │   └── resp_fallback.h
+│   ├── payload/
+│   │   ├── datacollector.cpp
+│   │   └── datacollector.h
+│   └── utils/
+│       └── hex_utils.cpp
+├── test/                          ← your host test directory
+│   └── host/
+│       ├── CMakeLists.txt
+│       ├── test_feature_flags.cpp
+│       ├── test_resp_fallback.cpp
+│       └── test_datacollector.cpp
+└── components/                    ← if you have ESP-IDF components
+```
+
+---
+
+## CMakeLists.txt Pattern
+
+```cmake
+# test/host/CMakeLists.txt
+cmake_minimum_required(VERSION 3.16)
+project(host_policy_tests)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# --- GoogleTest ---
+include(FetchContent)
+FetchContent_Declare(
+  googletest
+  GIT_REPOSITORY https://github.com/google/googletest.git
+  GIT_TAG v1.14.0
+)
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+FetchContent_MakeAvailable(googletest)
+
+# --- Test executable ---
+add_executable(test_policy
+    test_feature_flags.cpp
+    test_resp_fallback.cpp
+    test_datacollector.cpp
+)
+
+# --- Link firmware modules under test ---
+# Point FIRMWARE_ROOT at the project root or adjust as needed
+target_include_directories(test_policy PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../main
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../main/policy
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../main/payload
+)
+
+# Link the real implementation files directly (no ESP-IDF)
+target_sources(test_policy PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../main/policy/feature_flags.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../main/policy/resp_fallback.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../main/payload/datacollector.cpp
+)
+
+target_link_libraries(test_policy PRIVATE
+    gtest
+    gmock
+    pthread
+)
+
+# --- Optional: gcov coverage ---
+if(COVERAGE)
+    target_compile_options(test_policy PRIVATE -fprofile-arcs -ftest-coverage)
+    target_link_libraries(test_policy PRIVATE gcov)
+endif()
+```
+
+**Build and run:**
+
+```bash
+cd test/host
+mkdir build && cd build
+cmake .. -DCOVERAGE=ON
+cmake --build . -j$(nproc)
+./test_policy
+# or with coverage:
+cmake --build . -j$(nproc) && lcov --capture --directory . --output coverage.info --exclude '*/test_*' --exclude '*/build/*'
+```
+
+---
+
+## Pattern 1: Testing `feature_flags.cpp`
+
+### Firmware header (minimal)
+
+```cpp
+// main/policy/feature_flags.h
+#pragma once
+#include <stdbool.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+bool feature_flags_is_active(const char* name);
+const char* feature_flags_get_version(void);
+
+#ifdef __cplusplus
+}
+#endif
+```
+
+### Firmware implementation (real code)
+
+```cpp
+// main/policy/feature_flags.cpp
+#include "feature_flags.h"
+#include <string.h>
+
+static bool debug_flag   = false;
+static bool trace_flag   = false;
+static bool legacy_mode  = false;
+
+bool feature_flags_is_active(const char* name) {
+  if (name == nullptr) return false;
+  if (strcmp(name, "debug") == 0)   return debug_flag;
+  if (strcmp(name, "trace") == 0)   return trace_flag;
+  if (strcmp(name, "legacy") == 0)  return legacy_mode;
+  return false;
+}
+
+const char* feature_flags_get_version(void) {
+  return "1.2.0";
+}
+```
+
+### Host test
+
+```cpp
+// test/host/test_feature_flags.cpp
+#include <gtest/gtest.h>
+#include "feature_flags.h"
+#include <string.h>
+
+TEST(FeatureFlags, is_active_returns_false_for_nullptr) {
+  EXPECT_FALSE(feature_flags_is_active(nullptr));
+}
+
+TEST(FeatureFlags, is_active_returns_false_for_unknown_feature) {
+  EXPECT_FALSE(feature_flags_is_active("nonexistent"));
+}
+
+TEST(FeatureFlags, is_active_returns_true_for_known_enabled_feature) {
+  // In real firmware these might be set at boot; for host test
+  // we test the implementation directly — no mocking needed here
+  // because the flags are compile-time false in this build.
+  EXPECT_FALSE(feature_flags_is_active("debug"));   // currently disabled
+}
+
+TEST(FeatureFlags, get_version_returns_semver_string) {
+  const char* ver = feature_flags_get_version();
+  ASSERT_NE(nullptr, ver);
+  EXPECT_STREQ("1.2.0", ver);
+}
+```
+
+---
+
+## Pattern 2: Testing `resp_fallback.cpp` with Mocked Response
+
+### Firmware header
+
+```cpp
+// main/policy/resp_fallback.h
+#pragma once
+#include <stddef.h>
+
+typedef struct {
+  const char* payload;
+  size_t payload_len;
+  int status_code;
+} Response;
+
+typedef enum {
+  FALLBACK_OK,
+  FALLBACK_MISSING,
+  FALLBACK_INVALID
+} FallbackResult;
+
+FallbackResult resp_fallback_process(const Response* req, Response* out);
+```
+
+### Firmware implementation
+
+```cpp
+// main/policy/resp_fallback.cpp
+#include "resp_fallback.h"
+#include <string.h>
+
+static const char* s_fallback_payload = "default_response";
+static bool s_fallback_available = true;
+
+void resp_fallback_set_fallback_available(bool available) {
+  s_fallback_available = available;
+}
+
+FallbackResult resp_fallback_process(const Response* req, Response* out) {
+  if (req == nullptr || out == nullptr) return FALLBACK_INVALID;
+  if (req->status_code >= 200 && req->status_code < 300) {
+    // Pass-through for success codes
+    out->payload = req->payload;
+    out->payload_len = req->payload_len;
+    out->status_code = req->status_code;
+    return FALLBACK_OK;
+  }
+  // Error code — try fallback
+  if (!s_fallback_available) return FALLBACK_MISSING;
+  out->payload = s_fallback_payload;
+  out->payload_len = strlen(s_fallback_payload);
+  out->status_code = 200;
+  return FALLBACK_OK;
+}
+```
+
+### Host test with `std::function` injection
+
+```cpp
+// test/host/test_resp_fallback.cpp
+#include <gtest/gtest.h>
+#include "resp_fallback.h"
+#include <cstring>
+
+class RespFallbackTest : public ::testing::Test {
+protected:
+  void SetUp() override {
+    resp_fallback_set_fallback_available(true);
+  }
+  void TearDown() override {
+    resp_fallback_set_fallback_available(true);
+  }
+};
+
+TEST_F(RespFallbackTest, success_codes_pass_through) {
+  Response in = { .payload = "ok", .payload_len = 2, .status_code = 200 };
+  Response out;
+  FallbackResult r = resp_fallback_process(&in, &out);
+  EXPECT_EQ(r, FALLBACK_OK);
+  EXPECT_EQ(out.status_code, 200);
+  EXPECT_STREQ(out.payload, "ok");
+}
+
+TEST_F(RespFallbackTest, error_code_returns_fallback) {
+  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_F(RespFallbackTest, error_code_when_fallback_unavailable_returns_missing) {
+  resp_fallback_set_fallback_available(false);
+  Response in = { .payload = "error", .payload_len = 5, .status_code = 500 };
+  Response out;
+  FallbackResult r = resp_fallback_process(&in, &out);
+  EXPECT_EQ(r, FALLBACK_MISSING);
+}
+
+TEST_F(RespFallbackTest, null_request_returns_invalid) {
+  Response out;
+  EXPECT_EQ(resp_fallback_process(nullptr, &out), FALLBACK_INVALID);
+}
+
+TEST_F(RespFallbackTest, null_output_returns_invalid) {
+  Response in = { .payload = "ok", .payload_len = 2, .status_code = 200 };
+  EXPECT_EQ(resp_fallback_process(&in, nullptr), FALLBACK_INVALID);
+}
+```
+
+---
+
+## Pattern 3: Testing `datacollector.cpp`
+
+### Firmware header
+
+```cpp
+// main/payload/datacollector.h
+#pragma once
+#include <stddef.h>
+#include <stdint.h>
+
+#define DATACOLLECTOR_MAX_READINGS 64
+
+typedef struct {
+  double readings[DATACOLLECTOR_MAX_READINGS];
+  size_t count;
+} Datacollector;
+
+void datacollector_init(Datacollector* dc);
+int datacollector_append(Datacollector* dc, double value);
+double datacollector_latest(const Datacollector* dc);
+size_t datacollector_count(const Datacollector* dc);
+void datacollector_clear(Datacollector* dc);
+```
+
+### Firmware implementation
+
+```cpp
+// main/payload/datacollector.cpp
+#include "datacollector.h"
+#include <string.h>
+
+void datacollector_init(Datacollector* dc) {
+  memset(dc, 0, sizeof(*dc));
+}
+
+int datacollector_append(Datacollector* dc, double value) {
+  if (dc->count >= DATACOLLECTOR_MAX_READINGS) return -1;
+  dc->readings[dc->count++] = value;
+  return 0;
+}
+
+double datacollector_latest(const Datacollector* dc) {
+  if (dc->count == 0) return 0.0;  // Note: consider throwing instead
+  return dc->readings[dc->count - 1];
+}
+
+size_t datacollector_count(const Datacollector* dc) {
+  return dc->count;
+}
+
+void datacollector_clear(Datacollector* dc) {
+  memset(dc, 0, sizeof(*dc));
+}
+```
+
+### Host test
+
+```cpp
+// test/host/test_datacollector.cpp
+#include <gtest/gtest.h>
+#include "datacollector.h"
+#include <cmath>
+
+class DatacollectorTest : public ::testing::Test {
+protected:
+  void SetUp() override { datacollector_init(&dc_); }
+  Datacollector dc_;
+};
+
+TEST_F(DatacollectorTest, init_clears_readings) {
+  EXPECT_EQ(datacollector_count(&dc_), 0u);
+}
+
+TEST_F(DatacollectorTest, append_increments_count) {
+  EXPECT_EQ(datacollector_append(&dc_, 1.0), 0);
+  EXPECT_EQ(datacollector_count(&dc_), 1u);
+  EXPECT_EQ(datacollector_append(&dc_, 2.0), 0);
+  EXPECT_EQ(datacollector_count(&dc_), 2u);
+}
+
+TEST_F(DatacollectorTest, latest_returns_last_value) {
+  datacollector_append(&dc_, 1.0);
+  datacollector_append(&dc_, 2.0);
+  datacollector_append(&dc_, 3.0);
+  EXPECT_DOUBLE_EQ(datacollector_latest(&dc_), 3.0);
+}
+
+TEST_F(DatacollectorTest, latest_returns_zero_when_empty) {
+  // Current impl returns 0 — this documents current behavior
+  EXPECT_DOUBLE_EQ(datacollector_latest(&dc_), 0.0);
+}
+
+TEST_F(DatacollectorTest, append_returns_minus_one_when_full) {
+  for (int i = 0; i < DATACOLLECTOR_MAX_READINGS; ++i) {
+    EXPECT_EQ(datacollector_append(&dc_, static_cast<double>(i)), 0);
+  }
+  EXPECT_EQ(datacollector_append(&dc_, 999.0), -1);  // full
+}
+
+TEST_F(DatacollectorTest, clear_resets_count) {
+  datacollector_append(&dc_, 1.0);
+  datacollector_append(&dc_, 2.0);
+  datacollector_clear(&dc_);
+  EXPECT_EQ(datacollector_count(&dc_), 0u);
+}
+```
+
+---
+
+## Handling FreeRTOS Dependencies
+
+If a firmware module calls FreeRTOS APIs (e.g., `vTaskDelay`, `xQueueSend`), create a **stub library** that provides no-op or fake implementations:
+
+```cpp
+// test/host/stubs/freertos_stubs.cpp
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+extern "C" {
+
+void vTaskDelay(const TickType_t xTicksToDelay) {
+  (void)xTicksToDelay;  // no-op on host
+}
+
+BaseType_t xQueueSend(QueueHandle_t, const void*, TickType_t) {
+  return pdTRUE;  // fake success
+}
+
+}  // extern "C"
+```
+
+Then in `CMakeLists.txt`:
+
+```cmake
+target_sources(test_policy PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../main/policy/feature_flags.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/stubs/freertos_stubs.cpp  # link stubs
+)
+```
+
+Keep stubs minimal. If a module requires extensive FreeRTOS mocking, consider testing it as an integration test on-device instead.
+
+---
+
+## CI Integration
+
+```yaml
+# .github/workflows/host-tests.yml (GitHub Actions example)
+name: Host-Side Tests
+
+on: [push, pull_request]
+
+jobs:
+  host-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install deps
+        run: sudo apt-get update && sudo apt-get install -y cmake g++ lcov
+      - name: Build and test
+        run: |
+          cd test/host
+          mkdir -p build && cd build
+          cmake .. -DCOVERAGE=ON
+          cmake --build . -j$(nproc)
+          ./test_policy || exit 1
+          lcov --capture --directory . --output coverage.info \
+            --exclude '*/test_*' --exclude '*/build/*' --exclude '*/stubs/*'
+          lcov --filter coverage.info --output filtered.info \
+            --exclude '*/test_*' --exclude '*/stubs/*'
+          lcov --list filtered.info
+          # 80% gate:
+          lcov --filter filtered.info --output-filtered.info \
+            | grep -q "lines\.\.\.\." || true
+```
+
+---
+
+## Key Principles
+
+1. **Link real `.cpp` files** — not headers only. You want to test the compiled implementation.
+2. **No ESP-IDF includes** in test sources — if a header pulls in `esp_log.h`, create a local stub or use `-D` flags to mock it out.
+3. **Use `extern "C"`** when linking firmware `.cpp` files that have C linkage.
+4. **Test behavior, not structure** — assert on return values, state changes, and side effects visible through the public API.
+5. **Deterministic only** — host tests must be free of timing, threading races, and hardware dependencies.