fahnen_esp32/.pio/libdeps/esp01_1m/FastLED/TESTCASE_INSTRUCTIONS.md

FastLED TEST_CASE Execution Guide

Overview

FastLED uses the doctest framework for C++ unit testing. Tests are organized in files named test_*.cpp in the tests/ directory. Each file can contain multiple TEST_CASE macros that define individual test functions.

Test Structure

• Test Files: Located in tests/test_*.cpp (e.g., test_algorithm.cpp, test_easing.cpp)
• TEST_CASEs: Individual test functions defined with TEST_CASE("name") macro
• SUBCASEs: Nested test sections within TEST_CASEs using SUBCASE("name")
• Assertions: CHECK(), CHECK_EQ(), CHECK_LT(), etc. for validation

Quick Start

Using the MCP Server (Recommended)

1. Start the MCP server:

   uv run mcp_server.py
   

2. Available MCP tools:

   • run_tests: Run tests with various options
   • list_test_cases: List available TEST_CASEs
   • test_instructions: Show detailed instructions

Command Line Usage

1. Run all tests:

   uv run test.py
   # or using the user rule:
   bash test
   

2. Run only C++ tests:

   uv run test.py --cpp
   

3. Run specific test file:

   uv run test.py --cpp algorithm
   # This runs test_algorithm.cpp
   

Running Specific TEST_CASEs

Method 1: Direct Executable (Most Precise)

First, compile the tests, then run the specific executable with doctest filtering:

# 1. Compile the test (if not already compiled)
uv run test.py --cpp algorithm

# 2. Run specific TEST_CASE
./tests/.build/bin/test_algorithm --test-case="reverse an int list"

# 3. Run with verbose output
./tests/.build/bin/test_algorithm --test-case="reverse an int list" --verbose

Method 2: Using MCP Server

Use the run_tests tool with specific parameters:

• test_type: "specific"
• specific_test: "algorithm" (without test_ prefix)
• test_case: "reverse an int list"
• verbose: true (optional)

Method 3: List Available TEST_CASEs First

# Using MCP list_test_cases tool, or manually:
grep -r "TEST_CASE" tests/test_algorithm.cpp

Common Test Files and Their Purpose

File	Purpose	Example TEST_CASEs
test_algorithm.cpp	Algorithm utilities	"reverse an int list"
test_easing.cpp	Easing functions	"8-bit easing functions", "easeInOutQuad16"
test_hsv16.cpp	HSV color space	"HSV to RGB conversion", "HSV hue wraparound"
test_math.cpp	Mathematical functions	"sin32 accuracy", "random number generation"
test_vector.cpp	Vector container	"vector push_back", "vector iteration"
test_fx.cpp	Effects framework	"fx engine initialization"
test_apa102_hd.cpp	APA102 HD driver	"APA102 color mapping"
test_bitset.cpp	Bitset operations	"bitset operations"

Example Workflows

Debug a Failing Test

1. List TEST_CASEs in a specific file:

   # Using MCP server list_test_cases tool with test_file: "easing"
   

2. Run with verbose output:

   uv run test.py --cpp easing --verbose
   

3. Run specific failing TEST_CASE:

   ./tests/.build/bin/test_easing --test-case="8-bit easing functions" --verbose
   

Test Development Workflow

1. Clean build and run:

   uv run test.py --cpp mytest --clean --verbose
   

2. Run only failed tests:

   cd tests/.build && ctest --rerun-failed
   

3. Test with different compilers:

   uv run test.py --cpp mytest --clang
   

Finding Specific Tests

1. Search for TEST_CASEs by pattern:

   # Using MCP list_test_cases tool with search_pattern: "easing"
   

2. Manual search:

   grep -r "TEST_CASE.*easing" tests/
   

Doctest Command Line Options

When running test executables directly, you can use these doctest options:

• --test-case=<name>: Run specific TEST_CASE
• --test-case-exclude=<name>: Exclude specific TEST_CASE
• --subcase=<name>: Run specific SUBCASE
• --subcase-exclude=<name>: Exclude specific SUBCASE
• --list-test-cases: List all TEST_CASEs in the executable
• --list-test-suites: List all test suites
• --verbose: Show detailed output including successful assertions
• --success: Show successful assertions too
• --no-colors: Disable colored output
• --force-colors: Force colored output
• --no-breaks: Disable breaking into debugger
• --no-skip: Don't skip any tests

Examples:

# List all TEST_CASEs in a test file
./tests/.build/bin/test_easing --list-test-cases

# Run multiple TEST_CASEs with pattern
./tests/.build/bin/test_easing --test-case="*quad*"

# Exclude specific TEST_CASEs
./tests/.build/bin/test_easing --test-case-exclude="*16-bit*"

# Run with full verbose output
./tests/.build/bin/test_easing --success --verbose

Understanding Test Output

Successful Test:

[doctest] run with "--help" for options
===============================================================================
TEST_CASE:  reverse an int list
===============================================================================
tests/test_algorithm.cpp:12
all tests passed!
===============================================================================
[doctest] test cases:      1 |      1 passed |      0 failed |      0 skipped
[doctest] assertions:      5 |      5 passed |      0 failed |
[doctest] Status: SUCCESS!

Failed Test:

===============================================================================
TEST_CASE:  reverse an int list
===============================================================================
tests/test_algorithm.cpp:12
tests/test_algorithm.cpp:20: ERROR: CHECK_EQ(vec[0], 6) is NOT correct!
  values: CHECK_EQ(5, 6)

===============================================================================
[doctest] test cases:      1 |      0 passed |      1 failed |      0 skipped
[doctest] assertions:      5 |      4 passed |      1 failed |
[doctest] Status: FAILURE!

Tips and Best Practices

1. Use --verbose to see detailed test output and assertions
2. Use --clean when testing after significant code changes
3. List TEST_CASEs first to see what's available before running specific tests
4. Individual TEST_CASE execution is useful for debugging specific functionality
5. Check test output carefully - doctest provides detailed failure information with line numbers
6. Use pattern matching with --test-case="*pattern*" to run related tests
7. Combine with debugger - tests are compiled with debug symbols (-g3)

Environment Setup

• Tests are compiled with Debug flags (-g3, -O0) for better debugging
• GDB integration available for crash analysis
• Static analysis warnings enabled as errors
• Cross-platform support (Linux, macOS, Windows)
• Uses zig/clang as the default compiler for consistency

Troubleshooting

Common Issues:

1. Test executable not found:

   # Make sure tests are compiled first
   uv run test.py --cpp <test_name>
   

2. TEST_CASE name not found:

   # List available TEST_CASEs
   ./tests/.build/bin/test_<name> --list-test-cases
   

3. Compilation errors:

   # Clean build
   uv run test.py --cpp <test_name> --clean
   

4. Permission denied on executable:

   chmod +x tests/.build/bin/test_<name>
   

Integration with Development

Git Hooks

Consider adding a pre-commit hook to run relevant tests:

#!/bin/bash
# Run tests for changed files
uv run test.py --cpp

IDE Integration

Most IDEs can be configured to run individual TEST_CASEs directly from the editor by configuring the test executable path and doctest arguments.