Add comprehensive unit tests for ESP32 Dimmer Driver library

Co-authored-by: pmarchini <49943249+pmarchini@users.noreply.github.com>
2026-02-07 11:18:07 +03:00 · 2026-01-24 22:16:56 +00:00
parent 3a121b800d
commit 497761efd0
8 changed files with 823 additions and 0 deletions
--- a/test_app/README.md
+++ b/test_app/README.md
@@ -0,0 +1,147 @@
+# 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
+
+## Running the Tests
+
+### Prerequisites
+
+- ESP-IDF v5.0 or higher installed
+- ESP32 development board (tests can run without actual hardware connected)
+
+### Build and Flash
+
+1. Navigate to the test_app directory:
+   ```bash
+   cd test_app
+   ```
+
+2. Set the target (if not already set):
+   ```bash
+   idf.py set-target esp32
+   ```
+
+3. Build the test application:
+   ```bash
+   idf.py build
+   ```
+
+4. Flash to your ESP32 board:
+   ```bash
+   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!
+========================================
+
+16 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
+
+## 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 focus on the software logic and can run without actual dimmer hardware connected. They test the API layer and state management.
+
+## Limitations
+
+- These tests do not verify actual hardware functionality (zero-crossing detection, TRIAC firing)
+- ISR behavior is not directly tested (requires hardware/simulation)
+- Timing-critical code paths are not fully tested without hardware
+
+For hardware integration testing, additional tests would be needed with actual hardware or simulation.
+
+## 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:
+```c
+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()`:
+```c
+RUN_TEST(test_new_feature_basic_functionality);
+```