hacs.integration_blueprint: Skill for Claude Code

Testing

Home Assistant tests are integration tests by nature: you load a real config entry into a real hass instance and assert on hass.states — not on Python objects.

Read blueprint.tests.instructions.md first — it holds the rules: directory mirroring, pytest markers, which fixtures to define, the core-interface rule, registry assertions, what to mock and what never to mock, the full command list, and the do/don't list. This skill is the scaffolding and the judgement calls.

When a test is required

• Behavioural change, bug fix, or regression → add a proportionate test.
• Documentation-only, formatting-only, or anything that cannot affect runtime → no test needed.
• If a test is impractical (needs real hardware, non-deterministic timing), say so explicitly and describe the residual risk. Do not silently skip it, and never claim coverage that does not exist.

Bootstrap: tests/conftest.py

The suite currently has no conftest.py. Custom integrations are not loaded by default in tests, so the first thing any new test file needs is this — create it once:

"""Shared fixtures for <domain> tests."""

from collections.abc import Generator
from unittest.mock import AsyncMock, patch

import pytest
from pytest_homeassistant_custom_component.common import MockConfigEntry

from custom_components.<domain>.const import DOMAIN
from homeassistant.const import CONF_PASSWORD, CONF_USERNAME
from homeassistant.core import HomeAssistant


@pytest.fixture(autouse=True)
def auto_enable_custom_integrations(enable_custom_integrations: None) -> None:
    """Load the custom integration in every test."""


@pytest.fixture
def mock_config_entry() -> MockConfigEntry:
    """Return a config entry for the integration."""
    return MockConfigEntry(
        domain=DOMAIN,
        title="Example Device",
        data={CONF_USERNAME: "test-user", CONF_PASSWORD: "test-password"},
        unique_id="test-unique-id",
    )


@pytest.fixture
def mock_api_client() -> Generator[AsyncMock]:
    """Patch the API client with a mock that returns fixture data."""
    with patch(
        "custom_components.<domain>.{ClassPrefix}ApiClient",
        autospec=True,
    ) as client_class:
        client = client_class.return_value
        client.async_get_data.return_value = {"model": "Blueprint", "title": "ok"}
        yield client


@pytest.fixture
async def init_integration(
    hass: HomeAssistant,
    mock_config_entry: MockConfigEntry,
    mock_api_client: AsyncMock,
) -> MockConfigEntry:
    """Set up the integration and return the loaded entry."""
    mock_config_entry.add_to_hass(hass)
    assert await hass.config_entries.async_setup(mock_config_entry.entry_id)
    await hass.async_block_till_done()
    return mock_config_entry