{"id":2723,"library":"pytest-homeassistant-custom-component","title":"Pytest Home Assistant Custom Component","description":"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.","status":"active","version":"0.13.322","language":"en","source_language":"en","source_url":"https://github.com/MatthewFlamm/pytest-homeassistant-custom-component","tags":["pytest","home assistant","testing","custom component","plugin","automation","iot"],"install":[{"cmd":"pip install pytest-homeassistant-custom-component","lang":"bash","label":"Install plugin"}],"dependencies":[{"reason":"This package is a plugin for pytest.","package":"pytest","optional":false}],"imports":[],"quickstart":{"code":"import pytest\n\n# Assuming you have a 'custom_components/my_integration/' directory\n# with a basic __init__.py and possibly sensor.py, etc.\n\n# To make the test runnable without a full custom integration, \n# we'll just demonstrate the 'hass' fixture.\n# For real tests, you'd enable your component like:\n# await enable_custom_integration(\"my_integration\")\n\nasync def test_basic_hass_fixture(hass):\n    \"\"\"Verify the hass fixture is available and functional.\"\"\"\n    assert hass is not None\n    assert hass.loop is not None\n    assert hass.config is not None\n    \n    # Example: Check that the event bus is active\n    assert hass.bus.listeners is not None\n    \n    # In a real test, you'd interact with services, states, etc.\n    # For example:\n    # await hass.async_block_till_done()\n    # assert hass.states.get(\"sensor.my_test_sensor\") is not None\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially across major Home Assistant releases."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"In your test functions, use `await enable_custom_integration(\"your_integration_domain\")` before attempting to set up or interact with your custom component.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}