pytest-homeassistant-custom-component

What it is and what it does

pytest-homeassistant-custom-component extracts testing fixtures and helper functions from Home Assistant's core test suite and packages them for use in custom component projects. It allows developers to write integration tests using the same pytest fixtures (like `hass`, `MockConfigEntry`) and patterns as the main Home Assistant repository, without needing to fork or copy test code.

The package is automatically regenerated daily to track Home Assistant releases, including beta versions. It provides fixtures for async testing, mocking, snapshots via syrupy, and other common testing scenarios. Developers import helpers from `pytest_homeassistant_custom_component.common` instead of `tests.common`, and the package handles the extraction and versioning so that custom components can stay in sync with the Home Assistant testing API.

Use it for:

• Write pytest-based unit and integration tests for a Home Assistant custom component using the same fixtures as core Home Assistant
• Ensure custom component tests remain compatible with new Home Assistant releases by updating to the latest daily build
• Mock Home Assistant entities, config entries, and services in custom component tests without duplicating core test utilities
• Use snapshot testing via syrupy for custom component configuration or state validation aligned with Home Assistant conventions
• Set up async test fixtures and mocking for MQTT, database, or API-based custom components

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides pytest fixtures and testing utilities extracted from Home Assistant's test suite, enabling custom component developers to write tests using the same patterns as the core project.

Yes, if you are developing a Home Assistant custom component and want to follow the same testing patterns as core Home Assistant. The active daily maintenance and permissive MIT license make it practical. Be aware that the Python 3.14 requirement and large dependency tree may require careful environment management, and the alpha status means the API could shift with Home Assistant updates.

Install

pytest-homeassistant-custom-component on PyPI

pip install pytest-homeassistant-custom-component

uv add pytest-homeassistant-custom-component

poetry add pytest-homeassistant-custom-component

Installing pytest-homeassistant-custom-component

Before you install

Active maintenance with releases within days. Low install friction; however, requires Python 3.14 and a large dependency tree of 30 runtime dependencies including pytest, sqlalchemy, pydantic, and homeassistant, which may complicate environment setup.

License in practice

MIT license (permissive) allows use in both open and closed projects with minimal restrictions.

Quickstart

pip install pytest-homeassistant-custom-component

from pytest_homeassistant_custom_component.common import MockConfigEntry
from homeassistant.core import HomeAssistant

async def test_setup(hass: HomeAssistant):
    entry = MockConfigEntry(domain='my_domain')
    entry.add_to_hass(hass)

Requires Python 3.14; custom_components folder structure and enable_custom_integrations fixture required for versions >=2021.6.0b0; asyncio_mode = auto config required in pytest

Verify before relying

• Whether the Python 3.14 requirement reflects actual compatibility or is aspirational given Home Assistant's own support timeline
• Performance impact of the large dependency footprint on CI/CD pipeline times
• Stability guarantees for alpha-stage package given daily automatic updates

Package facts

Evidence: pytest_homeassistant_custom_component-0.13.355-py3-none-any.whl

Tags

More Testing packages