Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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.0b6

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.0b6
File Size Uploaded Provenance Actions
pytest_homeassistant-2026.11.0b6.tar.gz 133.3 kB With provenance Details for pytest_homeassistant-2026.11.0b6.tar.gz

Built distribution (wheel)

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

Total release size: 315.2 kB

Release files / pytest_homeassistant-2026.11.0b6.tar.gz

Download URL pytest_homeassistant-2026.11.0b6.tar.gz
Size 133.3 kB
Tags Source
SHA-256 checksum
How to use checksums
6065be360993744de4df589fa86799bf607d5ba2eab466e4cb58dd5bcb021dfd
BLAKE2b-256 checksum
How to use checksums
4f09bcaa1065c7e4729a8351e2c9c699c41b030f9a145c546dae540c540304ed
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 4, 2026.

Transparency log

Release files / pytest_homeassistant-2026.11.0b6-py3-none-any.whl

Download URL pytest_homeassistant-2026.11.0b6-py3-none-any.whl
Size 182.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7a794a71d95b5e91e9747ecc92e6f15fff479b9c643c3eb930b9f2a4ba49d0fd
BLAKE2b-256 checksum
How to use checksums
fbbb1f8b2b48adcb8510a256deace59bf895a80da77d234bed56dabce56cde3a
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 4, 2026.

Transparency log

Security for pytest-homeassistant 2026.11.0b6

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.0b6.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 4, 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