LLM Vision for Home Assistant

To set up a local testing environment, follow these steps to create a virtual environment and install the necessary dependencies.

Prerequisites

• Python 3.13
• pip
• Git

1. Create and Activate a Virtual Environment

Navigate to the project root and create a .venv directory.

macOS/Linux:

cd ha-llmvision
python -m venv .venv
source .venv/bin/activate

Windows:

cd ha-llmvision
python -m venv .venv
.venv\Scripts\activate

2. Install Test Dependencies

Upgrade pip and install the dependencies listed in requirements-test.txt (which includes pytest, Home Assistant utilities, mocking libraries, and coverage tools).

pip install --upgrade pip
pip install -r requirements-test.txt

3. Verify Installation

You can verify the setup by checking the pytest version and running a simple test.

pytest --version
python -c "import sys; print('custom_components' in str(sys.path))"
pytest tests/test_const.py::TestConstants::test_domain -v

# Navigate to the project root directory
cd ha-llmvision

# Create a virtual environment
python -m venv .venv

# Activate (macOS/Linux)
source .venv/bin/activate

# Upgrade pip and install dependencies
pip install --upgrade pip
pip install -r requirements-test.txt

Use pytest to execute different types of tests. The project uses markers to distinguish between unit and integration tests.

Unit Tests

Run all unit tests (excluding integration tests):

pytest tests/ -m "not integration" -v

Integration Tests

Integration tests in tests/test_api.py require a running Home Assistant instance and specific configuration files.

1. Create tests/.instance containing your HA URL (e.g., http://localhost:8123).
2. Create tests/.token containing a long-lived access token.
3. Run:

pytest tests/test_api.py -v

Running Specific Tests

• Specific file: pytest tests/test_memory.py -v
• Specific class: pytest tests/test_memory.py::TestMemory -v
• Specific function: pytest tests/test_memory.py::TestMemory::test_init_without_entry -v

Test Output Options

• Quiet mode: -q
• Show print statements: -v -s
• Stop on first failure: -x
• Show local variables on failure: -l

# Run all unit tests
pytest tests/ -v

# Run only unit tests
pytest tests/ -m "not integration" -v

# Run ALL tests including integration tests
pytest tests/ -v --run-integration

When writing new tests, follow the Arrange, Act, Assert (AAA) pattern and use pytest fixtures for setup.

Recommended Test Structure

import pytest
from unittest.mock import Mock, patch, AsyncMock

class TestClassName:
    @pytest.fixture
    def mock_dependency(self):
        return Mock()

    def test_method_name(self, mock_dependency):
        # Arrange
        instance = ClassName(mock_dependency)
        
        # Act
        result = instance.method_name()
        
        # Assert
        assert result == expected_value

    @pytest.mark.asyncio
    async def test_async_method(self):
        result = await async_function()
        assert result is not None

Best Practices

1. Descriptive Names: Use test_method_name_when_condition_then_expected_result.
2. Mocking: Always mock external dependencies like API calls or file systems.
3. Async Tests: Use the @pytest.mark.asyncio decorator for asynchronous functions.
4. Fixtures: Use fixtures for common setup. Available fixtures in tests/conftest.py include mock_hass and mock_config_entry.
5. Independence: Ensure tests do not share state.

Common Pitfalls

• Async Warnings: If you see RuntimeWarning: coroutine was never awaited, ensure you added @pytest.mark.asyncio.
• Mocking Errors: Ensure you patch the location where the function is used, not where it is defined.
• Shared State: If tests pass individually but fail together, use scope="function" in your fixtures to ensure a fresh instance per test.

"""Unit tests for module_name.py module."""
import pytest
from unittest.mock import Mock, patch, AsyncMock


class TestClassName:
    """Test ClassName class."""

    @pytest.fixture
    def mock_dependency(self):
        """Create a mock dependency."""
        return Mock()

    def test_method_name(self, mock_dependency):
        """Test method_name does something."""
        # Arrange
        instance = ClassName(mock_dependency)
        
        # Act
        result = instance.method_name()
        
        # Assert
        assert result == expected_value

    @pytest.mark.asyncio
    async def test_async_method(self):
        """Test async method."""
        result = await async_function()
        assert result is not None

If tests fail, you can use several debugging methods.

pytest Debugging

• Drop into debugger on failure: pytest tests/ --pdb
• Drop into debugger at start of each test: pytest tests/ --trace
• Show all log output (DEBUG level): pytest tests/ -v --log-cli-level=DEBUG

Manual Breakpoints

Insert import pdb; pdb.set_trace() in your test code to pause execution.

VS Code Integration

Create a .vscode/launch.json file to debug specific test files using the VS Code debugger:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Pytest Current File",
            "type": "python",
            "request": "launch",
            "module": "pytest",
            "args": [
                "${file}",
                "-v",
                "-s"
            ],
            "console": "integratedTerminal",
            "justMyCode": false
        }
    ]
}