> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt > Use this file to discover all available pages before exploring further. # Testing > Learn how to run and write tests for Home Assistant Core Home Assistant has an extensive test suite to ensure code quality and prevent regressions. All contributions must include tests. ## Running Tests ### Prerequisites Ensure you have installed test dependencies: ```bash theme={null} uv pip install -r requirements_test_all.txt ``` ### Run All Tests ```bash theme={null} pytest tests/ ``` ### Run Specific Tests ```bash theme={null} # Run tests for a specific component pytest tests/components/light/ # Run a specific test file pytest tests/components/light/test_init.py # Run a specific test function pytest tests/components/light/test_init.py::test_light_turn_on # Run tests matching a pattern pytest -k "test_light" ``` ### Useful pytest Options ```bash theme={null} # Run with verbose output pytest -v # Stop on first failure pytest -x # Show print statements pytest -s # Run tests in parallel (faster) pytest -n auto # Only run tests that failed last time pytest --lf # Show test durations pytest --durations=10 ``` ## Test Configuration Test configuration is defined in `pyproject.toml`: ```toml theme={null} [tool.pytest.ini_options] testpaths = ["tests"] norecursedirs = [".git", "testing_config"] asyncio_mode = "auto" asyncio_default_fixture_loop_scope = "function" log_format = "%(asctime)s.%(msecs)03d %(levelname)-8s %(threadName)s %(name)s:%(filename)s:%(lineno)s %(message)s" log_date_format = "%Y-%m-%d %H:%M:%S" asyncio_debug = true ``` ### Key Settings * **testpaths** - Directory containing tests * **asyncio\_mode = "auto"** - Automatically detect and run async tests * **asyncio\_debug = true** - Enable asyncio debug mode to catch issues * **filterwarnings** - Configure which warnings to show or ignore ## Test Plugins Home Assistant's test suite uses several pytest plugins: * **pytest-asyncio** (1.3.0) - Support for async test functions * **pytest-aiohttp** (1.1.0) - Fixtures for testing aiohttp applications * **pytest-cov** (7.0.0) - Code coverage measurement * **pytest-freezer** (0.4.9) - Freeze time in tests * **pytest-socket** (0.7.0) - Disable or restrict socket calls * **pytest-timeout** (2.4.0) - Set timeouts for tests * **pytest-sugar** (1.0.0) - Better test output formatting ## Writing Tests ### Test Structure Tests are organized to mirror the source code structure: ``` tests/ ├── components/ │ └── light/ │ ├── __init__.py │ ├── test_init.py │ ├── test_config_flow.py │ └── test_device_trigger.py ├── helpers/ │ └── test_entity.py └── util/ └── test_dt.py ``` ### Basic Test Example ```python theme={null} """Tests for the light component.""" import pytest from homeassistant.core import HomeAssistant from homeassistant.components import light async def test_light_turn_on(hass: HomeAssistant) -> None: """Test turning on a light.""" # Setup await async_setup_component(hass, light.DOMAIN, {}) # Action await hass.services.async_call( light.DOMAIN, "turn_on", {"entity_id": "light.test"}, blocking=True, ) # Assert state = hass.states.get("light.test") assert state.state == "on" ``` ### Common Fixtures Home Assistant provides useful fixtures: * **hass** - Home Assistant instance * **aiohttp\_client** - Test client for HTTP requests * **hass\_ws\_client** - WebSocket client * **snapshot** - Snapshot testing for data structures ### Async Tests Most Home Assistant code is async, so tests should be too: ```python theme={null} async def test_async_function(hass: HomeAssistant) -> None: """Test an async function.""" result = await my_async_function() assert result == expected_value ``` ### Freezing Time Use `freezegun` or `pytest-freezer` to control time in tests: ```python theme={null} from freezegun import freeze_time @freeze_time("2026-03-10 12:00:00") async def test_time_dependent_behavior(hass: HomeAssistant) -> None: """Test behavior at a specific time.""" # Your test code ``` ### Mocking Use `unittest.mock` for mocking: ```python theme={null} from unittest.mock import patch, Mock async def test_with_mock(hass: HomeAssistant) -> None: """Test with mocked external dependency.""" with patch("homeassistant.components.light.async_get_data") as mock_get: mock_get.return_value = {"brightness": 255} # Your test code ``` ### Testing Config Flows ```python theme={null} from homeassistant import config_entries from homeassistant.data_entry_flow import FlowResultType async def test_config_flow(hass: HomeAssistant) -> None: """Test the config flow.""" result = await hass.config_entries.flow.async_init( "my_integration", context={"source": config_entries.SOURCE_USER}, ) assert result["type"] == FlowResultType.FORM assert result["step_id"] == "user" ``` ## Code Coverage Home Assistant uses `coverage.py` to measure test coverage. ### Run Tests with Coverage ```bash theme={null} # Run tests and generate coverage report pytest --cov=homeassistant --cov-report=html # View HTML report open htmlcov/index.html ``` ### Coverage Configuration Coverage is configured in `pyproject.toml`: ```toml theme={null} [tool.coverage.run] source = ["homeassistant"] [tool.coverage.report] exclude_lines = [ "pragma: no cover", "def __repr__", "raise AssertionError", "raise NotImplementedError", "if TYPE_CHECKING:", "@overload", ] ``` ### Coverage Requirements * New code should have **high test coverage** (aim for 90%+) * All public APIs must be tested * Edge cases and error conditions should be covered ## Test Best Practices ### Do's * **Write tests first** - Consider TDD (Test-Driven Development) * **Test behavior, not implementation** - Tests should verify what code does, not how it does it * **Use descriptive names** - Test names should clearly describe what they test * **Keep tests isolated** - Each test should be independent * **Test error cases** - Don't just test the happy path * **Use fixtures appropriately** - Leverage pytest fixtures for setup/teardown ### Don'ts * **Don't test external services** - Mock external dependencies * **Don't write flaky tests** - Tests should be deterministic * **Don't share state** - Avoid global variables or shared mutable objects * **Don't test private methods** - Test public interfaces instead * **Don't make network calls** - Use mocks or pytest-socket will catch them ## Debugging Tests ### Using pdb ```python theme={null} async def test_debug_example(hass: HomeAssistant) -> None: """Test with debugger.""" import pdb; pdb.set_trace() # Test code ``` ### Logging in Tests ```python theme={null} import logging _LOGGER = logging.getLogger(__name__) async def test_with_logging(hass: HomeAssistant) -> None: """Test with logging.""" _LOGGER.debug("Debug message") # Test code ``` Run pytest with `-s` to see log output: ```bash theme={null} pytest -s tests/components/light/test_init.py ``` ## Continuous Integration Home Assistant uses GitHub Actions for CI. Tests run automatically on: * Pull requests * Commits to the `dev` branch * Commits to the `master` branch All tests must pass before a PR can be merged. ## Component-Specific Testing ### Testing Integrations Integrations typically need tests for: * **Config flow** - Setup and configuration * **Entity creation** - Entities are created correctly * **State updates** - Entities reflect correct states * **Services** - Service calls work as expected * **Unloading** - Clean shutdown and resource cleanup ### Testing Helpers Helper modules should have: * Unit tests for all public functions * Tests for edge cases * Tests for error handling ## Resources * [pytest documentation](https://docs.pytest.org/) * [pytest-asyncio documentation](https://pytest-asyncio.readthedocs.io/) * [Home Assistant Developer Docs](https://developers.home-assistant.io/docs/development_testing) * [Testing integrations guide](https://developers.home-assistant.io/docs/development_testing#testing-your-integration)