Skip to main content

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.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytest-homeassistant 2026.11.1
File Size Uploaded Provenance Actions
pytest_homeassistant-2026.11.1.tar.gz 133.3 kB With provenance Details for pytest_homeassistant-2026.11.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pytest-homeassistant 2026.11.1
File Interpreter ABI Platform Actions
pytest_homeassistant-2026.11.1-py3-none-any.whl Python 3 none any Details for pytest_homeassistant-2026.11.1-py3-none-any.whl

Total release size: 315.2 kB

Release files / pytest_homeassistant-2026.11.1.tar.gz

Download URL pytest_homeassistant-2026.11.1.tar.gz
Size 133.3 kB
Tags Source
SHA-256 checksum
How to use checksums
c820d04708597e7f2fa5dc30392520b5c19e2af48ea6756c3088cee543f85b3b
BLAKE2b-256 checksum
How to use checksums
484f608b832e5cc1d18e27b30d01f966ebd31f3a983a1386ce7a3b77efceedca
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 9, 2026.

Transparency log

Release files / pytest_homeassistant-2026.11.1-py3-none-any.whl

Download URL pytest_homeassistant-2026.11.1-py3-none-any.whl
Size 181.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
293410940684db4d7bef5ebe5d75ff269c6e246d479049f6140d37641fb7a361
BLAKE2b-256 checksum
How to use checksums
6ba12bf3116d96bc7184c48b837244dd88828f4dd05ea449eebda94cd2424ebe
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 9, 2026.

Transparency log

Security for pytest-homeassistant 2026.11.1

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.

Select from 2 files

Attestation for pytest_homeassistant-2026.11.1.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 9, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page