Pytest Home Assistant Custom Component

0.13.322 · active · verified Fri Apr 10

pytest-homeassistant-custom-component is an experimental pytest plugin designed to facilitate testing of Home Assistant custom components. It automatically extracts test plugins and provides fixtures tailored for Home Assistant's architecture. The current version is 0.13.322, with a frequent release cadence that closely tracks Home Assistant core versions.

Warnings

breaking Compatibility with Home Assistant core versions is critical. The plugin is frequently updated to track HA core releases, and an older plugin version may not be compatible with a newer (or much older) Home Assistant core version due to internal API changes. Always align your `pytest-homeassistant-custom-component` version with the target HA core version you are testing against.
Fix: Refer to the plugin's release notes on GitHub for the supported Home Assistant core version for your `pytest-homeassistant-custom-component` version. Update the plugin to the latest version if you update Home Assistant core.
gotcha Home Assistant core requires Python 3.12+ (as of recent versions), and this plugin specifies `requires_python >=3.14`. Ensure your test environment uses a compatible Python version that satisfies both the plugin and the Home Assistant core version you intend to test.
Fix: Verify your Python environment's version (`python --version`) and ensure it meets the minimum requirement. Use tools like `pyenv` or `conda` to manage Python versions if needed.
gotcha Home Assistant is an asynchronous application. All test functions interacting with Home Assistant fixtures or APIs must be defined as `async def` and use `await` for asynchronous operations.
Fix: Always define your test functions as `async def test_my_feature(...)` when using `pytest-homeassistant-custom-component` fixtures and ensure all async calls are `await`-ed.
gotcha To effectively test a custom component, you need to instruct the test environment to load it. The `enable_custom_integration` fixture is essential for making your custom component available to the `hass` instance during tests.
Fix: In your test functions, use `await enable_custom_integration("your_integration_domain")` before attempting to set up or interact with your custom component.

Install

pip install pytest-homeassistant-custom-component Install plugin

Quickstart

This quickstart demonstrates how to write a basic asynchronous pytest test using the `hass` fixture provided by the plugin. Save this code as `test_example.py` in your project's `tests/` directory and run `pytest` from your terminal. For actual custom component testing, you'd typically use `enable_custom_integration` and interact with Home Assistant's state machine, services, and entities.

import pytest

# Assuming you have a 'custom_components/my_integration/' directory
# with a basic __init__.py and possibly sensor.py, etc.

# To make the test runnable without a full custom integration, 
# we'll just demonstrate the 'hass' fixture.
# For real tests, you'd enable your component like:
# await enable_custom_integration("my_integration")

async def test_basic_hass_fixture(hass):
    """Verify the hass fixture is available and functional."""
    assert hass is not None
    assert hass.loop is not None
    assert hass.config is not None
    
    # Example: Check that the event bus is active
    assert hass.bus.listeners is not None
    
    # In a real test, you'd interact with services, states, etc.
    # For example:
    # await hass.async_block_till_done()
    # assert hass.states.get("sensor.my_test_sensor") is not None

view raw JSON →