Developer Testing

Developer Testing

Manual Testing with Development Server

The recommended way to test changes is using the development server:

# Start the development server
./scripts/develop

# In another terminal, make changes to the code
# Then restart Home Assistant from the UI or by restarting the script

Test Configuration:

The config/configuration.yaml file contains mock entities for testing:

• Mock covers (position-capable and open/close-only)
• Mock temperature sensors
• Mock weather entity
• Mock presence sensors

Edit this file to create the test scenarios you need.

Automated Tests

This integration uses pytest for automated testing.

For comprehensive test documentation, see UNIT_TESTS.md which includes:

• Detailed test descriptions for all 751 tests
• Fixture documentation with usage examples
• Testing patterns and best practices
• Coverage goals and future expansion plans

Running Tests Locally

# Install test dependencies
pip install -r requirements-dev.txt

# Run all tests
pytest

# Run with coverage report
pytest --cov --cov-report=term-missing

# Run specific test file
pytest tests/test_calculation.py

# Run specific test
pytest tests/test_calculation.py::test_gamma_angle_calculation_sun_directly_in_front

# Run only unit tests (fast)
pytest -m unit

# Run with verbose output
pytest -v

# Use the test script
./scripts/test              # Run all tests
./scripts/test unit         # Run only unit tests
./scripts/test coverage     # Run with detailed coverage

Test Structure

• tests/conftest.py - Shared fixtures (hass mock, logger, configs, cover instances)
• tests/test_calculation.py - Position calculation tests (unit)
• tests/test_helpers.py - Helper function tests (unit)
• tests/test_inverse_state.py - Critical inverse state tests (unit)
• tests/test_managers/ - Manager class unit tests
• tests/test_pipeline/ - Pipeline handler unit tests
• tests/test_state/ - State provider tests
• tests/test_diagnostics/ - Diagnostics builder tests
• tests/test_engine/ - Engine module tests (SunGeometry, VenetianCoverCalculation)

Total: 751 tests (all passing)

Test Coverage

Current test coverage status:

Module	Coverage	Status
calculation.py	87%	✅ Comprehensive
helpers.py	100%	✅ Complete
const.py	100%	✅ Complete
inverse_state	100%	✅ Complete
pipeline/	~100%	✅ Complete
managers/	~96%	✅ Mostly complete
state/	~95%	✅ Mostly complete
diagnostics/	~90%	✅ Mostly complete
engine/	~90%	✅ Mostly complete
coordinator.py	~34%	🔄 Future work
Overall	61%	🔄 In progress

See UNIT_TESTS.md for detailed coverage information and future expansion plans.

Writing Tests

Tests use pytest fixtures from conftest.py. Example:

import pytest
from custom_components.adaptive_cover_pro.helpers import get_safe_state

@pytest.mark.unit
def test_get_safe_state_returns_state(hass):
    """Test get_safe_state returns state when available."""
    state_obj = MagicMock()
    state_obj.state = "25.5"
    hass.states.get.return_value = state_obj

    result = get_safe_state(hass, "sensor.temperature")

    assert result == "25.5"

Best Practices:

• Use descriptive test names that explain what is being tested
• Add docstrings explaining the test purpose
• Mark tests with @pytest.mark.unit for fast tests
• Use fixtures from conftest.py for common setup
• Keep tests simple and focused on one behavior

Continuous Integration

Tests run automatically on:

• Pull requests
• Pushes to main branch
• Pushes to feature branches
• Manual workflow dispatch

See .github/workflows/tests.yml for CI configuration.

CI Matrix:

• Python 3.11
• Python 3.12

CI Steps:

1. Checkout code
2. Set up Python environment
3. Install dependencies
4. Run tests with coverage
5. Upload coverage to Codecov (Python 3.12 only)

Test Philosophy

Priority Order:

1. Pure functions - Test utilities and helpers first (easiest)
2. Critical behaviors - Test inverse_state and documented behaviors
3. Core algorithms - Test calculation logic
4. Integration - Test coordinator and flows (future)

What We Test:

• Pure utility functions (no I/O)
• Position calculation algorithms
• Sun angle and azimuth calculations
• Blind spot detection logic
• Position clamping and validation
• Critical documented behaviors (inverse state order of operations)

What We Don't Test (Yet):

• Async coordinator logic (complex, lower priority initially)
• Config flow UI (requires Home Assistant test framework)
• Entity registration (lower ROI, can be added later)

Testing the Release Script

The release script supports dry-run mode for safe testing:

# Test beta release (no changes made)
./scripts/release beta --dry-run

# Test with explicit version
./scripts/release 2.5.1-beta.1 --dry-run

# Test production release (requires main branch)
git checkout main
./scripts/release patch --dry-run

Jupyter Notebooks

For algorithm testing and visualization:

# Install Jupyter dependencies
pip install jupyter matplotlib pvlib

# Start Jupyter
jupyter notebook

# Open notebooks/simulate_cover.ipynb

Use cases:

• Test position calculation algorithms
• Visualize cover positions over time
• Simulate different sun positions and configurations
• Generate plots for documentation

Simulation Tools

The custom_components/adaptive_cover_pro/simulation/ directory contains tools for simulating cover behavior over time.