Esp32 Test Plan

# Run all host unit tests
bash test --cpp

# Run a specific test by name
bash test TestName

# Run test in debug mode (ASAN/LSAN/UBSAN — always use when a test fails)
bash test TestName --debug

# Compile for WASM (catches most cross-platform issues without hardware)
bash compile wasm --examples Blink
bash compile wasm --examples Chromancer

# Compile for a specific ESP32 variant
bash compile esp32dev --examples Blink
bash compile esp32s3 --examples Blink
bash compile esp32c3 --examples Blink

# Run linting
bash lint

# Hardware validation (requires connected ESP32)
bash autoresearch --rmt          # For RMT-based LED drivers
bash autoresearch --spi          # For SPI-based LED drivers
bash autoresearch --parlio       # For PARLIO (ESP32-S3 parallel)

// Example test structure for tests/fl/my_feature.cpp
#include "test.h"
#include "FastLED.h"
#include "fl/my_feature.h"

using namespace fl;

namespace {

TEST_CASE("MyFeature - basic operation") {
    MyFeature f;
    FL_CHECK_EQ(f.compute(0), 0);
    FL_CHECK_EQ(f.compute(255), 255);
}

TEST_CASE("MyFeature - boundary values") {
    MyFeature f;
    FL_REQUIRE_TRUE(f.compute(256) <= 255); // no overflow
}

} // namespace

# Test Plan: [Feature Name]

## Change Reference
- Implementation contract: [link or description]
- Related issue: [GitHub issue number]

## Test Layers

### Layer 1: Host Unit Tests
**Command**: `bash test TestName`

| Test Case | Input | Expected Output | Status |
|-----------|-------|-----------------|--------|
| [description] | [input] | [expected] | ⬜ Pending |

### Layer 2: WASM Compile Check
**Command**: `bash compile wasm --examples Blink`

| Check | Expected | Status |
|-------|----------|--------|
| Compiles without errors | No compiler errors | ⬜ Pending |
| Compiles without warnings | 0 new warnings | ⬜ Pending |

### Layer 3: Platform Compile Checks
**Command**: `bash compile <platform> --examples Blink`

| Platform | Command | Status |
|---------|---------|--------|
| ESP32 | `bash compile esp32dev --examples Blink` | ⬜ Pending |
| ESP32-S3 | `bash compile esp32s3 --examples Blink` | ⬜ Pending |
| ESP32-C3 | `bash compile esp32c3 --examples Blink` | ⬜ Pending |
| AVR (Uno) | `bash compile uno --examples Blink` | ⬜ Pending |

### Layer 4: Hardware Validation
**Command**: `bash autoresearch --<driver>`

| Test Case | Setup | Expected Behavior | Status |
|-----------|-------|-------------------|--------|
| [description] | [board + wiring] | [expected LED output] | ⬜ Pending (hardware) |

## Infrastructure Requirements
- [ ] New test file: `tests/fl/[name].cpp`
- [ ] Example sketch modification (if testing new API): `examples/[name]/`
- [ ] Hardware board: [ESP32 variant] + [LED strip type]

## No-Hardware Tests
[Tests that run on host — must cover the majority of logic]

## Hardware-Required Tests
[Tests that need real ESP32 + LED strip]
- Must be verified by a human with the hardware
- Document serial output and visual confirmation

## Coverage Goals
- All new public API functions have at least one test case
- All error paths have a negative test case
- Critical timing constants have a verification test or hardware measurement
- No regressions: `bash test --cpp` passes with zero new failures

## Pass/Fail Criteria

| Criterion | Measurement |
|-----------|------------|
| Host tests pass | `bash test --cpp` exits 0 |
| WASM compiles | `bash compile wasm` exits 0 |
| Platform compiles | All listed platforms exit 0 |
| Hardware validated | Human-verified LED output correct |
| No regressions | 0 new test failures vs. main branch |