pytest-homeassistant
Pytest fixtures and helpers for testing Home Assistant integrations. Create a Home Assistant instance, mock configuration entries and external services, simulate events, and check integration behavior.
Installation and compatibility
Install the package into your custom integration's virtual environment:
uv pip install pytest-homeassistant
Use the package release that matches your Home Assistant version. Upgrade them
together.
The plugin loads automatically. Do not install it together with
pytest-homeassistant-custom-component, which supplies overlapping fixtures.
Bluetooth, infrared, and radio-frequency helpers have optional dependencies:
install the corresponding bluetooth, infrared, or radio-frequency extra
when using those helpers. Integration-specific libraries must also be installed
by the consuming project. SQLite recorder tests work with the base installation;
MySQL/PostgreSQL tests additionally need their database driver and
sqlalchemy-utils.
Writing tests
Add this pytest configuration to your project's pyproject.toml:
[tool.pytest.ini_options]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"
# Let Home Assistant install its httpx alias before respx is imported.
addopts = "-p no:respx"
pythonpath = ["."]
testpaths = ["tests"]
The package's HTTP mocks still use respx directly; only its separate pytest
plugin is disabled. The hass fixture enables custom integrations by default.
Tests request fixtures such as hass by name and import helpers from
pytest_homeassistant. For example, tests/test_config_entry.py can create a
configuration entry without setting up the integration:
from homeassistant.core import HomeAssistant
from pytest_homeassistant.common import MockConfigEntry
async def test_config_entry(hass: HomeAssistant) -> None:
entry = MockConfigEntry(domain="my_integration", data={"host": "example.local"})
entry.add_to_hass(hass)
assert hass.config_entries.async_get_entry(entry.entry_id) is entry
Run your tests with pytest.
Use @pytest.mark.usefixtures("entity_registry_enabled_by_default") when a test
needs entities that are normally disabled in the entity registry.
Test data and configuration
Load test data with helpers such as load_fixture and load_json_object_fixture
from pytest_homeassistant.common. They read tests/fixtures by default. When
given an integration name, they use tests/components/<domain>/fixtures if that
integration's test directory exists, otherwise tests/fixtures. Set ha_test_root
to use another test directory. Paths are relative to pytest's project root.
Snapshots are stored next to the consuming test in snapshots/.
The hass fixture uses the shared tests/testing_config path by default, without
creating or copying a directory. Set ha_test_config_dir relative to the project
root to use another path. For tests that need an isolated writable directory,
override hass_config_dir to return hass_tmp_config_dir. That fixture copies the
shared configuration if it exists, or provides an empty temporary directory.
What's included
| Module | Purpose |
|---|---|
pytest_homeassistant.plugins |
Shared fixtures and pytest hooks, including hass, HTTP and WebSocket clients, registry fixtures, and mocks for storage, networking, and authentication. |
pytest_homeassistant.common |
Helpers such as MockConfigEntry, fixture file loaders, event capture, service mocks, and simulated time changes. |
pytest_homeassistant.components.common |
Shared assertions for entities, platforms, and integration behavior. |
pytest_homeassistant.components.bluetooth |
Bluetooth device, advertisement, and scanner test helpers. |
pytest_homeassistant.components.mqtt.common |
MQTT client mocks, message helpers, and shared assertions. |
pytest_homeassistant.components.recorder.common |
Recorder setup, database, and history test helpers. |
pytest_homeassistant.components.diagnostics |
Helpers for requesting integration and device diagnostics. |
pytest_homeassistant.components.repairs |
Helpers for listing repair issues and starting and completing repair flows. |
pytest_homeassistant.components.infrared.common, .radio_frequency.common |
Mock IR and RF entities and commands, plus integration setup helpers. |
pytest_homeassistant.test_util.aiohttp |
Mock HTTP client responses and sessions. |
pytest_homeassistant.syrupy |
Snapshot extensions for Home Assistant objects. |
pytest_homeassistant.typing |
Type aliases for shared test fixtures. |
Migrating from pytest-homeassistant-custom-component
Replace the old package dependency with pytest-homeassistant and change imports
of pytest_homeassistant_custom_component to pytest_homeassistant. Existing
hass, enable_custom_integrations, registry, HTTP, recorder, and snapshot
fixtures keep their names.
The wrapper fixture requesting enable_custom_integrations can be removed;
custom integrations are enabled by default.
License
Apache License 2.0. See LICENSE.md.
Metadata
Release files for pytest-homeassistant 2026.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pytest_homeassistant-2026.11.0.tar.gz | 133.2 kB | With provenance | Details for pytest_homeassistant-2026.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pytest_homeassistant-2026.11.0-py3-none-any.whl | Python 3 | none | any | Details for pytest_homeassistant-2026.11.0-py3-none-any.whl |
Total release size: 315.2 kB
Release files / pytest_homeassistant-2026.11.0.tar.gz
| Download URL | pytest_homeassistant-2026.11.0.tar.gz |
|---|---|
| Size | 133.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1b8ed0e65531caaf46c6792dfc8fdb62329cac2ddfff10ec99017da3e806976d
|
|
BLAKE2b-256 checksum How to use checksums |
8d134339c9a672d0c84fa08748a08dafa0118d3f489e47a6e259fddad6e83090
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / pytest_homeassistant-2026.11.0-py3-none-any.whl
| Download URL | pytest_homeassistant-2026.11.0-py3-none-any.whl |
|---|---|
| Size | 181.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6c8929d1dbe00c19c4ec1b0f2823146b207162116b99b99100a5c0971755f986
|
|
BLAKE2b-256 checksum How to use checksums |
52bd5a035b6c8d87bd3316ba9308a42ce7782a1d9449d02f1b9eafeb97229af3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for pytest-homeassistant 2026.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pytest_homeassistant-2026.11.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.