Esp32Dimmer/test_app/README.md

ESP32 Dimmer Driver Unit Tests

This directory contains unit tests for the ESP32 Dimmer Driver library.

Test Structure

The tests are organized using the ESP-IDF Unity testing framework and cover the following functionality:

Test Categories

1. Dimmer Creation Tests

   • test_createDimmer_returns_valid_pointer: Verifies that createDimmer returns a valid pointer
   • test_createDimmer_with_different_pins: Tests creating multiple dimmers with different GPIO pins

2. Power Control Tests

   • test_setPower_getPower_normal_values: Tests setting and getting power with normal values (0, 50, 99)
   • test_setPower_boundary_values: Tests boundary conditions (values above 99 are clamped)
   • test_getPower_when_dimmer_off: Verifies getPower returns 0 when dimmer is OFF

3. State Management Tests

   • test_setState_getState: Tests setting and getting the dimmer state (ON/OFF)
   • test_changeState_toggles_state: Verifies changeState toggles between ON and OFF
   • test_state_affects_getPower: Tests that state changes affect getPower behavior

4. Mode Management Tests

   • test_setMode_getMode: Tests setting and getting dimmer modes (NORMAL/TOGGLE)
   • test_toggleSettings_with_valid_values: Tests toggle settings with valid range
   • test_toggleSettings_boundary_values: Tests toggle settings with boundary values

5. Initialization Tests

   • test_begin_with_normal_mode: Tests initialization with NORMAL_MODE
   • test_begin_with_toggle_mode: Tests initialization with TOGGLE_MODE

6. Multiple Dimmer Tests

   • test_multiple_dimmers_independent: Verifies multiple dimmers operate independently

7. GPIO and Timer ISR Tests

   • test_gpio_output_timing_high: Verifies GPIO output pin goes HIGH after zero-crossing trigger (tests with power=99 for immediate response)
   • test_gpio_output_pulse_width: Tests the pulse completes and pin returns to LOW after full cycle
   • test_gpio_output_zero_crossing_response: Validates dimmer triggers output HIGH in response to zero-crossing events
   • test_multiple_dimmers_gpio_independence: Tests that ON dimmer triggers output while OFF dimmer remains LOW
   • test_timer_isr_respects_state_changes: Verifies timer ISR keeps pin LOW when OFF and triggers HIGH when ON

Running the Tests

Prerequisites

• ESP-IDF v5.0 or higher installed
• ESP32 development board (tests can run without actual hardware connected)

Validate Your Setup

Before running tests, you can validate your environment:

./validate_setup.sh

This will check:

• Python and ESP-IDF installation
• Required files and directories
• Serial port availability
• CMake installation

Build and Flash

1. Navigate to the test_app directory:

   cd test_app
   

2. Set the target (if not already set):

   idf.py set-target esp32
   

3. Build the test application:

   idf.py build
   

4. Flash to your ESP32 board:

   idf.py -p /dev/ttyUSB0 flash monitor
   

   Replace /dev/ttyUSB0 with your serial port.

Expected Output

When the tests run successfully, you should see output similar to:

========================================
ESP32 Dimmer Driver Unit Tests
========================================

Running test_createDimmer_returns_valid_pointer...
PASS

Running test_createDimmer_with_different_pins...
PASS

...

========================================
All tests completed!
========================================

19 Tests 0 Failures 0 Ignored
OK

Test Coverage

The unit tests cover:

• ✅ Dimmer object creation
• ✅ Power setting and retrieval with boundary conditions
• ✅ State management (ON/OFF)
• ✅ Mode management (NORMAL/TOGGLE)
• ✅ Toggle settings configuration
• ✅ Multiple independent dimmers
• ✅ State-dependent behavior
• ✅ GPIO output timing and pulse width
• ✅ Timer ISR behavior with zero-crossing events
• ✅ GPIO pin state changes based on power settings
• ✅ Multi-dimmer GPIO independence

Notes for Future Refactoring

These unit tests are designed to:

1. Enable safe refactoring: The tests verify the API contract, allowing you to refactor internal implementation while ensuring the public API behavior remains consistent.

2. Document expected behavior: Each test serves as executable documentation of how the library should behave.

3. Catch regressions: Running these tests after changes helps catch any unintended behavior changes.

4. Hardware independence: These tests include both API-level tests (hardware-independent) and GPIO/timer tests that verify the dimmer output behavior. The GPIO/timer tests simulate zero-crossing events and verify output pin timing, providing confidence in the core dimmer logic.

Limitations

• GPIO timing tests verify the mechanism is working but cannot precisely measure microsecond-level timing without specialized hardware
• Actual TRIAC firing with AC loads requires hardware validation
• Full zero-crossing detector integration requires real AC signal input

For complete hardware integration testing, additional tests with actual hardware, oscilloscope verification, and AC loads are recommended.

Adding New Tests

To add new tests:

1. Add new test functions to main/test_main.c
2. Use the Unity assertion macros (TEST_ASSERT_*, etc.)
3. Register the test with RUN_TEST() in the app_main() function
4. Follow the naming convention: test_<functionality>_<scenario>

Example:

void test_new_feature_basic_functionality(void)
{
    dimmertyp *dimmer = createDimmer(TEST_TRIAC_GPIO, TEST_ZC_GPIO);
    TEST_ASSERT_NOT_NULL(dimmer);
    
    // Your test code here
}

Then add to app_main():

RUN_TEST(test_new_feature_basic_functionality);