Registry / testing / pytest-homeassistant-custom-component

pytest-homeassistant-custom-component

JSON →
library0.13.322pypypiunverified

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.

pip install pytest-homeassistant-custom-component
INSTALL
IMPORT
SIG · PYTEST-HOMEASSISTA
P
pytest-homeassistant-custom-component
testingpythonv0.13.322
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

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
Debug
Known issues
breakingCompatibility 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.
affects: All versions, especially across major Home Assistant releases.
gotchaHome 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.
affects: All versions
gotchaHome 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.
affects: All versions
gotchaTo 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.
affects: All versions
Upgrade
Version history
0.13.322latest on PyPI · released Apr 4, 2026
Audit
Dependencies
pytestrequiredThis package is a plugin for pytest.
Agent activity
5 hits · last 30 days
node
4
Resources
pytest-homeassistant-custom-component — pip install pytest-homeassistant-custom-component · libregistry