Metadata-Version: 2.4
Name: pytest-homeassistant
Version: 2026.11.0b6
Summary: Pytest fixtures and test helpers for Home Assistant.
Author-email: The Home Assistant Authors <hello@home-assistant.io>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/home-assistant/core
Project-URL: Documentation, https://contributors.home-assistant.io
Requires-Python: >=3.14.2
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: homeassistant==2026.11.0b6
Requires-Dist: bleak-retry-connector==4.7.1
Requires-Dist: freezegun==1.5.5
Requires-Dist: paho-mqtt==2.1.0
Requires-Dist: pytest==9.0.3
Requires-Dist: pytest-aiohttp==1.1.1
Requires-Dist: pytest-asyncio==1.4.0
Requires-Dist: pytest-freezer==0.4.9
Requires-Dist: pytest-socket==0.8.1
Requires-Dist: pytest-xdist==3.8.0
Requires-Dist: requests-mock==1.12.1
Requires-Dist: respx==0.23.1
Requires-Dist: syrupy==6.1.1
Provides-Extra: bluetooth
Requires-Dist: aiohasupervisor==0.8.1; extra == "bluetooth"
Requires-Dist: aiousbwatcher==1.1.2; extra == "bluetooth"
Requires-Dist: bluetooth-adapters==2.4.0; extra == "bluetooth"
Requires-Dist: bluetooth-auto-recovery==1.6.4; extra == "bluetooth"
Requires-Dist: bluetooth-data-tools==1.29.24; extra == "bluetooth"
Requires-Dist: habluetooth==7.1.2; extra == "bluetooth"
Requires-Dist: serialx==1.15.1; extra == "bluetooth"
Provides-Extra: infrared
Requires-Dist: infrared-protocols==10.5.0; extra == "infrared"
Provides-Extra: radio-frequency
Requires-Dist: rf-protocols==4.3.0; extra == "radio-frequency"
Dynamic: license-file

# 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:

```shell
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`:

```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:

```python
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](LICENSE.md).
