ha-testcontainer 1.0.1__py3-none-any.whl

ha_testcontainer/__init__.py

@@ -0,0 +1,23 @@
+"""ha_testcontainer – Test container for Home Assistant.
+
+Usage::
+
+    from ha_testcontainer import HATestContainer, HAVersion
+
+    with HATestContainer(version=HAVersion.STABLE, config_path="ha-config") as ha:
+        print(ha.get_url())
+        resp = ha.api("GET", "states")
+        print(resp.json())
+"""
+
+from .container import HATestContainer, HAVersion
+from .visual import PAGE_LOAD_TIMEOUT, HA_SETTLE_MS, inject_ha_token, assert_snapshot
+
+__all__ = [
+    "HATestContainer",
+    "HAVersion",
+    "PAGE_LOAD_TIMEOUT",
+    "HA_SETTLE_MS",
+    "inject_ha_token",
+    "assert_snapshot",
+]

ha_testcontainer/container.py

@@ -0,0 +1,475 @@
+"""Home Assistant test container.
+
+Provides :class:`HATestContainer`, a :class:`~testcontainers.core.container.DockerContainer`
+subclass that:
+
+* Starts the official Home Assistant Docker image (stable / beta / dev / pinned version).
+* Performs the HA onboarding flow programmatically so tests don't need to touch the UI.
+* Creates and exposes a long-lived API token for REST and WebSocket access.
+* Optionally mounts a custom config directory and/or a ``custom_components`` directory.
+* Works as a context manager or with explicit ``start()`` / ``stop()`` calls.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode
+
+import requests
+import websocket
+from testcontainers.core.container import DockerContainer
+from testcontainers.core.waiting_utils import wait_for_logs
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+#: Registry prefix for the official Home Assistant image.
+HA_IMAGE = "ghcr.io/home-assistant/home-assistant"
+
+#: Port that Home Assistant listens on inside the container.
+HA_PORT = 8123
+
+#: How long (seconds) to wait for the web-server to become reachable.
+STARTUP_TIMEOUT = 120
+
+#: Default credentials used for the programmatic onboarding step.
+DEFAULT_USERNAME = "testadmin"
+DEFAULT_PASSWORD = "testpassword123"  # noqa: S105 - test-only credential
+
+
+class HAVersion:
+    """Convenience constants for well-known HA image tags."""
+
+    STABLE = "stable"
+    BETA = "beta"
+    DEV = "dev"
+
+
+# ---------------------------------------------------------------------------
+# Main class
+# ---------------------------------------------------------------------------
+
+
+class HATestContainer(DockerContainer):
+    """Disposable Home Assistant container for automated tests.
+
+    Parameters
+    ----------
+    version:
+        Docker image tag.  Use :class:`HAVersion` constants or pass a
+        specific release string such as ``"2024.6.0"``.
+    config_path:
+        Host path to mount as ``/config`` inside the container.  When
+        omitted HA creates a minimal default configuration at start-up.
+    custom_components_path:
+        Host path to mount as ``/config/custom_components``.  Ignored when
+        *config_path* is given and already contains a ``custom_components``
+        sub-directory (HA will pick it up automatically from the config
+        volume).
+    username:
+        Admin username created during programmatic onboarding.
+    password:
+        Admin password created during programmatic onboarding.
+    port:
+        Container port to expose (default: 8123).
+    """
+
+    def __init__(
+        self,
+        version: str = HAVersion.STABLE,
+        config_path: str | Path | None = None,
+        custom_components_path: str | Path | None = None,
+        username: str = DEFAULT_USERNAME,
+        password: str = DEFAULT_PASSWORD,
+        port: int = HA_PORT,
+    ) -> None:
+        image = f"{HA_IMAGE}:{version}"
+        super().__init__(image=image)
+
+        self._ha_port = port
+        self._username = username
+        self._password = password
+        self._token: str | None = None
+
+        self.with_exposed_ports(port)
+        self.with_env("TZ", "UTC")
+
+        if config_path is not None:
+            resolved = Path(config_path).resolve()
+            self.with_volume_mapping(str(resolved), "/config", "rw")
+        elif custom_components_path is not None:
+            resolved_cc = Path(custom_components_path).resolve()
+            self.with_volume_mapping(str(resolved_cc), "/config/custom_components", "rw")
+
+    # ------------------------------------------------------------------
+    # Context-manager helpers
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "HATestContainer":
+        self.start()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.stop()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def start(self) -> "HATestContainer":
+        """Start the container and complete onboarding."""
+        super().start()
+        self._wait_for_ha()
+        self._perform_onboarding()
+        return self
+
+    def get_url(self) -> str:
+        """Return the base URL of the running HA instance."""
+        host = self.get_container_host_ip()
+        port = self.get_exposed_port(self._ha_port)
+        return f"http://{host}:{port}"
+
+    def get_token(self) -> str:
+        """Return the long-lived access token for the admin user.
+
+        Raises :class:`RuntimeError` if the container has not been started yet.
+        """
+        if self._token is None:
+            raise RuntimeError(
+                "No token available – call start() first or use as a context manager."
+            )
+        return self._token
+
+    def api(
+        self,
+        method: str,
+        path: str,
+        **kwargs: Any,
+    ) -> requests.Response:
+        """Make an authenticated REST API call.
+
+        Parameters
+        ----------
+        method:
+            HTTP verb (``"GET"``, ``"POST"``, …).
+        path:
+            API path, with or without a leading ``/api/``.
+            E.g. ``"states"`` or ``"/api/states"``.
+        **kwargs:
+            Forwarded to :func:`requests.request` (``json``, ``params``, …).
+
+        Returns
+        -------
+        requests.Response
+        """
+        if not path.startswith("/api/"):
+            path = f"/api/{path.lstrip('/')}"
+        url = f"{self.get_url()}{path}"
+        headers = kwargs.pop("headers", {})
+        headers["Authorization"] = f"Bearer {self.get_token()}"
+        headers.setdefault("Content-Type", "application/json")
+        return requests.request(method, url, headers=headers, timeout=30, **kwargs)
+
+    def setup_integration(self, domain: str) -> dict[str, Any]:
+        """Set up a HA integration via the config-flow API.
+
+        Initiates the config flow for *domain* and, if it completes in one
+        step (e.g. UIX), returns the resulting entry data.
+
+        Parameters
+        ----------
+        domain:
+            Integration domain, e.g. ``"uix"``.
+
+        Returns
+        -------
+        dict
+            The response JSON from the config-flow endpoint.
+        """
+        resp = self.api(
+            "POST",
+            "/api/config/config_entries/flow",
+            json={"handler": domain},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def push_lovelace_config(self, config: dict[str, Any]) -> None:
+        """Push a Lovelace dashboard configuration via the WebSocket API.
+
+        ``POST /api/lovelace/config`` was removed from recent HA releases.
+        This method uses the ``lovelace/config/save`` WebSocket command
+        instead, which is the current supported approach.
+
+        The WebSocket call is executed in a dedicated thread with its own
+        event loop so this method is safe to call from inside
+        pytest-playwright's already-running asyncio event loop (where
+        :func:`asyncio.run` would raise a ``RuntimeError``).
+
+        Parameters
+        ----------
+        config:
+            Lovelace configuration dict to save, e.g.
+            ``{"title": "Home", "views": [...]}``.
+
+        Raises
+        ------
+        RuntimeError
+            If the WebSocket command fails or authentication is rejected.
+        """
+        result: dict[str, Any] = {}
+        exc_holder: list[BaseException] = []
+
+        def _run() -> None:
+            try:
+                result.update(self._ws_call({"id": 1, "type": "lovelace/config/save", "config": config}))
+            except BaseException as e:  # noqa: BLE001
+                exc_holder.append(e)
+
+        t = threading.Thread(target=_run, daemon=True)
+        t.start()
+        t.join(timeout=30)
+        if t.is_alive():
+            raise TimeoutError("push_lovelace_config timed out after 30 s")
+        if exc_holder:
+            raise exc_holder[0]
+        if not result.get("success"):
+            raise RuntimeError(f"lovelace/config/save failed: {result}")
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _wait_for_ha(self) -> None:
+        """Block until HA's web server responds (or *STARTUP_TIMEOUT* elapses)."""
+        # First wait for the "Home Assistant is running" log line so we know
+        # the internal startup sequence is complete.
+        try:
+            wait_for_logs(self, "Home Assistant is running", timeout=STARTUP_TIMEOUT)
+        except Exception:  # noqa: BLE001
+            pass  # fall through to the HTTP poll below
+
+        # Then confirm the HTTP endpoint is reachable.
+        url = f"{self.get_url()}/api/"
+        deadline = time.monotonic() + STARTUP_TIMEOUT
+        last_exc: Exception | None = None
+        while time.monotonic() < deadline:
+            try:
+                resp = requests.get(url, timeout=5)
+                # 200 = already set up, 401 = running but needs auth,
+                # 403 = forbidden (onboarding state)
+                if resp.status_code in (200, 401, 403):
+                    return
+            except requests.exceptions.ConnectionError as exc:
+                last_exc = exc
+            time.sleep(2)
+
+        raise TimeoutError(
+            f"Home Assistant did not become ready within {STARTUP_TIMEOUT}s."
+            + (f"  Last error: {last_exc}" if last_exc else "")
+        )
+
+    def _needs_onboarding(self) -> bool:
+        """Return True when the HA onboarding wizard has not been completed."""
+        try:
+            resp = requests.get(
+                f"{self.get_url()}/api/onboarding",
+                timeout=10,
+            )
+            if resp.status_code == 200:
+                steps = resp.json()
+                return any(not s.get("done", False) for s in steps)
+        except requests.exceptions.RequestException:
+            pass
+        return False
+
+    def _perform_onboarding(self) -> None:
+        """Run through the HA onboarding API to create the admin user and token."""
+        if not self._needs_onboarding():
+            # Already onboarded (e.g. pre-populated .storage files).
+            # Try to authenticate with the supplied credentials.
+            self._token = self._password_login()
+            return
+
+        base_url = self.get_url()
+        client_id = f"{base_url}/"
+
+        # Step 1 – create the first admin user.
+        resp = requests.post(
+            f"{base_url}/api/onboarding/users",
+            json={
+                "client_id": client_id,
+                "name": "Test Admin",
+                "username": self._username,
+                "password": self._password,
+                "language": "en",
+            },
+            timeout=30,
+        )
+        resp.raise_for_status()
+        auth_code = resp.json()["auth_code"]
+
+        # Step 2 – exchange the auth code for an access token.
+        token_resp = requests.post(
+            f"{base_url}/auth/token",
+            data=urlencode(
+                {
+                    "client_id": client_id,
+                    "grant_type": "authorization_code",
+                    "code": auth_code,
+                }
+            ),
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            timeout=15,
+        )
+        token_resp.raise_for_status()
+        short_lived_token = token_resp.json()["access_token"]
+
+        # Step 3 – complete remaining onboarding steps (core_config, analytics,
+        # integration).  These are optional from an API standpoint but HA marks
+        # them as required before the UI proceeds.
+        for step in ("core_config", "analytics"):
+            requests.post(
+                f"{base_url}/api/onboarding/{step}",
+                json={"client_id": client_id},
+                headers={"Authorization": f"Bearer {short_lived_token}"},
+                timeout=15,
+            )
+        # The integration step requires redirect_uri in addition to client_id.
+        requests.post(
+            f"{base_url}/api/onboarding/integration",
+            json={"client_id": client_id, "redirect_uri": client_id},
+            headers={"Authorization": f"Bearer {short_lived_token}"},
+            timeout=15,
+        )
+
+        # Step 4 – mint a long-lived token so tests are not time-limited.
+        self._token = self._mint_long_lived_token(short_lived_token)
+
+    def _password_login(self) -> str:
+        """Authenticate with username/password and return a long-lived token.
+
+        Used when the container is started with a pre-populated config that
+        already has a user (i.e. onboarding is skipped).
+        """
+        base_url = self.get_url()
+        client_id = f"{base_url}/"
+
+        # Initiate login flow.
+        flow_resp = requests.post(
+            f"{base_url}/auth/login_flow",
+            json={
+                "client_id": client_id,
+                "handler": ["homeassistant", None],
+                "redirect_uri": client_id,
+            },
+            timeout=15,
+        )
+        flow_resp.raise_for_status()
+        flow_id = flow_resp.json()["flow_id"]
+
+        # Submit credentials.
+        cred_resp = requests.post(
+            f"{base_url}/auth/login_flow/{flow_id}",
+            json={"username": self._username, "password": self._password},
+            timeout=15,
+        )
+        cred_resp.raise_for_status()
+        auth_code = cred_resp.json()["result"]
+
+        # Exchange code for token.
+        token_resp = requests.post(
+            f"{base_url}/auth/token",
+            data=urlencode(
+                {
+                    "client_id": client_id,
+                    "grant_type": "authorization_code",
+                    "code": auth_code,
+                }
+            ),
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            timeout=15,
+        )
+        token_resp.raise_for_status()
+        short_lived_token = token_resp.json()["access_token"]
+
+        # Mint a long-lived token.
+        return self._mint_long_lived_token(short_lived_token)
+
+    def _ws_call(self, command: dict[str, Any]) -> dict[str, Any]:
+        """Open an authenticated WebSocket connection, send *command*, return result.
+
+        The ``"id"`` field in *command* is used as the expected message ID in
+        the response.  Caller is responsible for setting a unique ID.
+
+        Parameters
+        ----------
+        command:
+            A dict representing the WebSocket command.  Must include ``"id"``
+            and ``"type"`` keys.
+
+        Returns
+        -------
+        dict
+            The parsed result message from Home Assistant.
+
+        Raises
+        ------
+        RuntimeError
+            If authentication fails.
+        """
+        ws_url = self.get_url().replace("http://", "ws://") + "/api/websocket"
+        ws = websocket.create_connection(ws_url, timeout=15)
+        try:
+            ws.recv()  # auth_required
+            ws.send(json.dumps({"type": "auth", "access_token": self.get_token()}))
+            auth_result = json.loads(ws.recv())
+            if auth_result.get("type") != "auth_ok":
+                raise RuntimeError(f"WebSocket auth failed: {auth_result}")
+            ws.send(json.dumps(command))
+            return json.loads(ws.recv())
+        finally:
+            ws.close()
+
+    def _mint_long_lived_token(self, short_lived_token: str) -> str:
+        """Create a long-lived access token via the HA WebSocket API.
+
+        The legacy ``POST /api/auth/long_lived_access_token`` endpoint was
+        removed in recent HA stable releases.  The WebSocket flow is:
+
+        1. Authenticate with the short-lived token.
+        2. Send an ``auth/long_lived_access_token`` command.
+        3. Return the resulting token string.
+        """
+        ws_url = self.get_url().replace("http://", "ws://") + "/api/websocket"
+        ws = websocket.create_connection(ws_url, timeout=15)
+        try:
+            # Server sends auth_required immediately after connect.
+            ws.recv()
+            # Authenticate with the short-lived token.
+            ws.send(json.dumps({"type": "auth", "access_token": short_lived_token}))
+            auth_result = json.loads(ws.recv())
+            if auth_result.get("type") != "auth_ok":
+                raise RuntimeError(f"WebSocket auth failed: {auth_result}")
+            # Request a long-lived token.
+            ws.send(
+                json.dumps(
+                    {
+                        "id": 1,
+                        "type": "auth/long_lived_access_token",
+                        "client_name": "ha-testcontainer",
+                        "lifespan": 3650,
+                    }
+                )
+            )
+            result = json.loads(ws.recv())
+            if not result.get("success"):
+                raise RuntimeError(f"Failed to create long-lived token: {result}")
+            return result["result"]
+        finally:
+            ws.close()

ha_testcontainer/visual.py

@@ -0,0 +1,199 @@
+"""Visual testing helpers for ha-testcontainer.
+
+This module provides the Playwright-based helpers that component authors import
+in their own test files.  The key exports are:
+
+- :data:`PAGE_LOAD_TIMEOUT`  — ms to wait for HA to fully render
+- :data:`HA_SETTLE_MS`       — additional settle time before snapshotting
+- :func:`inject_ha_token`    — bypass the HA login screen via localStorage
+- :func:`assert_snapshot`    — take a screenshot and compare to a baseline
+
+Usage in a component's test file::
+
+    from ha_testcontainer.visual import PAGE_LOAD_TIMEOUT, assert_snapshot
+
+    def test_my_card(ha_page, ha_url):
+        ha_page.goto(f"{ha_url}/lovelace/0", wait_until="networkidle",
+                     timeout=PAGE_LOAD_TIMEOUT)
+        assert_snapshot(ha_page, "my_card_baseline")
+
+Where baselines are stored
+--------------------------
+Baseline PNGs are placed in a ``snapshots/`` sub-directory **next to the
+calling test file** in the **consumer's own repository**.  They are part of
+the consumer project's version history — not part of ha-testcontainer.
+
+ha-testcontainer itself does not commit any snapshot files.  Any PNGs that
+are generated locally (e.g. when running the example tests) are gitignored
+inside this repository.
+
+Run with ``SNAPSHOT_UPDATE=1`` (or pass ``update=True``) to create or refresh
+baselines in the consumer's project.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import os
+import shutil
+import time
+from pathlib import Path
+
+from playwright.sync_api import Page
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+#: Milliseconds to allow for HA's frontend to fully paint before asserting
+#: or screenshotting.  Applies to ``page.goto`` wait and explicit waits.
+PAGE_LOAD_TIMEOUT: int = 60_000
+
+#: Additional settle time (ms) between page load and snapshot capture, to let
+#: animations and async HA state updates complete.
+HA_SETTLE_MS: int = 3_000
+
+
+# ---------------------------------------------------------------------------
+# Authentication helper
+# ---------------------------------------------------------------------------
+
+
+def inject_ha_token(page: Page, ha_url: str, token: str) -> None:
+    """Bypass the HA login screen by injecting a long-lived token into localStorage.
+
+    Home Assistant reads ``hassTokens`` from localStorage on page load.
+    Injecting it before the first navigation skips the onboarding/login flow.
+
+    Parameters
+    ----------
+    page:
+        An unnavigated Playwright :class:`~playwright.sync_api.Page`.
+    ha_url:
+        Base URL of the running HA instance, e.g. ``http://localhost:8123``.
+    token:
+        Long-lived access token obtained from :meth:`HATestContainer.get_token`.
+    """
+    expires_ms = int(time.time() * 1000) + 365 * 24 * 3600 * 1000
+    hass_tokens_json = json.dumps({
+        "access_token": token,
+        "token_type": "Bearer",
+        "expires_in": 31536000,
+        "refresh_token": None,
+        "hassUrl": ha_url,
+        "clientId": f"{ha_url}/",
+        "expires": expires_ms,
+    })
+    # Use add_init_script so the localStorage entry is written on every
+    # document load — including HA's own SPA redirects — before any page JS
+    # runs.  page.evaluate() after domcontentloaded is racy: HA's redirect
+    # destroys the execution context before evaluate() can run.
+    page.add_init_script(
+        f"localStorage.setItem('hassTokens', {json.dumps(hass_tokens_json)});"
+    )
+    page.goto(ha_url, wait_until="domcontentloaded", timeout=PAGE_LOAD_TIMEOUT)
+
+
+# ---------------------------------------------------------------------------
+# Snapshot helper
+# ---------------------------------------------------------------------------
+
+
+def assert_snapshot(
+    page: Page,
+    name: str,
+    *,
+    snapshots_dir: Path | str | None = None,
+    update: bool = False,
+) -> None:
+    """Take a screenshot and compare it to a stored baseline PNG.
+
+    On the **first run** (or when *update* is ``True`` / ``SNAPSHOT_UPDATE=1``),
+    the screenshot is saved as the baseline.  Subsequent runs compare the new
+    screenshot against the baseline; any pixel difference fails the test.
+
+    Baseline PNGs (``<name>.png``) are placed in the ``snapshots/`` directory
+    next to the calling test file in the **consumer's own repository** and
+    should be committed there.
+    Actual screenshots (``<name>.actual.png``) are transient and should be
+    gitignored in the consumer's project.
+
+    Parameters
+    ----------
+    page:
+        Playwright page to screenshot.
+    name:
+        Filename stem for the PNG, e.g. ``"01_dashboard"``.
+    snapshots_dir:
+        Directory in which to store baseline and actual PNGs.
+        Defaults to a ``snapshots/`` sub-directory **next to the calling
+        test file** so baselines live alongside the tests that create them.
+    update:
+        When ``True``, overwrite the baseline instead of comparing.
+        Also triggered by the ``SNAPSHOT_UPDATE=1`` environment variable.
+    """
+    resolved_dir = _resolve_snapshots_dir(snapshots_dir)
+    resolved_dir.mkdir(parents=True, exist_ok=True)
+
+    baseline = resolved_dir / f"{name}.png"
+    actual = resolved_dir / f"{name}.actual.png"
+
+    page.wait_for_timeout(HA_SETTLE_MS)
+    page.screenshot(path=str(actual), full_page=False)
+
+    should_update = update or os.environ.get("SNAPSHOT_UPDATE") == "1"
+
+    baseline_existed = baseline.exists()
+
+    if not baseline_existed or should_update:
+        shutil.copy(actual, baseline)
+        print(f"\n[snapshot] baseline {'updated' if baseline_existed else 'created'}: {baseline}")
+        return
+
+    # Pixel-level comparison using Pillow when available, falling back to bytes.
+    try:
+        from PIL import Image, ImageChops  # type: ignore[import]
+
+        img_base = Image.open(baseline).convert("RGB")
+        img_actual = Image.open(actual).convert("RGB")
+        diff = ImageChops.difference(img_base, img_actual)
+        bbox = diff.getbbox()
+        assert bbox is None, (
+            f"Snapshot mismatch for '{name}'. "
+            f"Differing region: {bbox}. "
+            "Run with SNAPSHOT_UPDATE=1 to accept new baseline."
+        )
+    except ImportError:
+        # Pillow not installed — byte-level fallback.
+        assert baseline.read_bytes() == actual.read_bytes(), (
+            f"Snapshot mismatch for '{name}'. "
+            "Run with SNAPSHOT_UPDATE=1 to accept new baseline."
+        )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_snapshots_dir(snapshots_dir: Path | str | None) -> Path:
+    """Return the resolved snapshots directory path.
+
+    When *snapshots_dir* is ``None`` (the default), walk the call stack to
+    find the first frame outside this module and place the ``snapshots/``
+    sub-directory next to that file.  This means snapshot baselines
+    automatically live alongside the test file that calls
+    :func:`assert_snapshot`, with no configuration required.
+    """
+    if snapshots_dir is not None:
+        return Path(snapshots_dir)
+
+    this_file = Path(__file__).resolve()
+    for frame_info in inspect.stack()[2:]:
+        caller_file = Path(frame_info.filename).resolve()
+        if caller_file != this_file:
+            return caller_file.parent / "snapshots"
+
+    # Fallback: use the current working directory.
+    return Path.cwd() / "snapshots"

ha_testcontainer-1.0.1.dist-info/METADATA

@@ -0,0 +1,432 @@
+Metadata-Version: 2.4
+Name: ha-testcontainer
+Version: 1.0.1
+Summary: Full test container for Home Assistant with demo config, custom components, and visual testing
+License: MIT License
+        
+        Copyright (c) 2026 Lint Free Technology
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Lint-Free-Technology/ha-testcontainer
+Project-URL: Issues, https://github.com/Lint-Free-Technology/ha-testcontainer/issues
+Keywords: home-assistant,testcontainers,testing,docker,playwright
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: testcontainers>=4.9
+Requires-Dist: requests>=2.32
+Requires-Dist: websocket-client>=1.6
+Provides-Extra: visual
+Requires-Dist: playwright>=1.50; extra == "visual"
+Requires-Dist: pytest-playwright>=0.5; extra == "visual"
+Requires-Dist: Pillow>=10.0; extra == "visual"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-playwright>=0.5; extra == "test"
+Requires-Dist: playwright>=1.50; extra == "test"
+Requires-Dist: Pillow>=10.0; extra == "test"
+Dynamic: license-file
+
+# ha-testcontainer
+
+> A full, reusable test container for Home Assistant.
+
+`ha-testcontainer` is a Python library that wraps the official Home Assistant
+Docker image in a [Testcontainers](https://testcontainers.com/)-based class.
+It handles all the plumbing — startup, programmatic onboarding, long-lived
+token creation, and custom component mounting — so your tests can focus on
+what matters.
+
+[UIX (UI eXtension)](https://github.com/Lint-Free-Technology/uix) is the
+primary consumer and uses this library as a replacement for its legacy local
+test stack.
+
+---
+
+## Features
+
+| Capability | Detail |
+|---|---|
+| **Version flexibility** | `stable`, `beta`, `dev`, or any pinned tag (`2024.6.0`) |
+| **Automatic onboarding** | Creates an admin user and mints a long-lived API token with no manual interaction |
+| **Demo entities** | Built-in HA `demo` integration gives you lights, sensors, weather objects immediately |
+| **Custom config** | Mount any `configuration.yaml` tree via `config_path=` |
+| **Custom components** | Mount any `custom_components/` directory via `custom_components_path=` |
+| **Fetch any component** | `scripts/fetch_component.py owner/repo` — downloads any GitHub-hosted HA component |
+| **Fetch any frontend plugin** | `scripts/fetch_plugin.py owner/repo` — downloads any JS dashboard plugin; registers it as a Lovelace resource |
+| **Storage-mode dashboard** | Default Lovelace dashboard in storage mode; REST-pushable for tests |
+| **REST API helper** | `ha.api("GET", "states")` — authenticated calls with zero boilerplate |
+| **Integration setup** | `ha.setup_integration("my_domain")` — drives config-flow programmatically |
+| **Playwright visual tests** | Session-scoped browser context, token injection, pixel-diff snapshot comparison |
+| **Boilerplate example** | `examples/test_custom_component.py` — copy, fill in TODO values, done |
+
+---
+
+## Quick start
+
+### 1 — Install
+
+```bash
+pip install -e ".[test]"
+playwright install chromium
+```
+
+### 2 — Fetch a custom component
+
+```bash
+# Any GitHub-hosted HA custom component (Python, goes into custom_components/):
+python scripts/fetch_component.py Lint-Free-Technology/uix
+python scripts/fetch_component.py Lint-Free-Technology/uix 5.3.1   # pinned version
+
+# Or via make (COMPONENT is required):
+make setup COMPONENT=Lint-Free-Technology/uix
+make setup COMPONENT=Lint-Free-Technology/uix VERSION=5.3.1
+```
+
+### 2b — Fetch a frontend plugin (optional)
+
+Frontend plugins are JavaScript dashboard modules (Lovelace cards, etc.),
+distinct from Python custom components.  They are downloaded into
+`ha-config/www/dashboard/` and automatically served by HA at `/local/…`.
+
+```bash
+# Download and register a dashboard plugin:
+python scripts/fetch_plugin.py custom-cards/button-card
+python scripts/fetch_plugin.py thomasloven/lovelace-card-mod 3.4.4
+
+# Or via make:
+make fetch-plugin PLUGIN=custom-cards/button-card
+make fetch-plugin PLUGIN=thomasloven/lovelace-card-mod VERSION=3.4.4
+```
+
+### 3 — Run tests
+
+```bash
+make test           # unit + integration tests (no browser)
+make test-visual    # Playwright visual tests (requires Docker + Playwright)
+```
+
+See **[Testing](#testing)** below for a full breakdown of each tier.
+
+### 4 — Explore locally with docker compose
+
+```bash
+make up             # starts HA at http://localhost:8123
+make down
+```
+
+---
+
+## Usage in your own project
+
+```python
+from ha_testcontainer import HATestContainer, HAVersion
+
+with HATestContainer(
+    version=HAVersion.STABLE,          # or "beta", "dev", "2024.6.0"
+    config_path="ha-config",
+    custom_components_path="custom_components",
+) as ha:
+    # Set up any custom component via config-flow
+    ha.setup_integration("uix")
+
+    # REST API — authenticated, zero boilerplate
+    states = ha.api("GET", "states").json()
+
+    print(ha.get_url())    # http://localhost:<random-port>
+    print(ha.get_token())  # long-lived access token
+```
+
+### pytest fixture example
+
+```python
+# conftest.py
+import pytest
+from ha_testcontainer import HATestContainer
+
+@pytest.fixture(scope="session")
+def ha():
+    with HATestContainer(config_path="ha-config", custom_components_path="custom_components") as c:
+        c.setup_integration("uix")
+        yield c
+
+# test_my_component.py
+def test_api(ha):
+    resp = ha.api("GET", "states")
+    assert resp.status_code == 200
+```
+
+### Playwright visual test example
+
+See [`examples/test_custom_component.py`](examples/test_custom_component.py) for a
+fully annotated boilerplate that any component author can copy.
+
+```python
+from ha_testcontainer.visual import PAGE_LOAD_TIMEOUT, assert_snapshot
+
+def test_my_card(ha_page, ha_url):
+    ha_page.goto(f"{ha_url}/lovelace/0", wait_until="networkidle",
+                 timeout=PAGE_LOAD_TIMEOUT)
+    assert_snapshot(ha_page, "my_card_baseline")
+```
+
+Run `SNAPSHOT_UPDATE=1 pytest tests/visual/` to create or update baselines.
+
+---
+
+## Fetching custom components
+
+`scripts/fetch_component.py` works with **any** GitHub repository that follows
+the standard HA custom-component layout (a `custom_components/<name>/` directory
+in the repository root):
+
+```
+python scripts/fetch_component.py owner/repo             # latest release
+python scripts/fetch_component.py owner/repo 5.3.1       # specific version
+python scripts/fetch_component.py owner/repo --list      # list releases
+python scripts/fetch_component.py owner/repo --target-dir /other/path
+```
+
+The script auto-discovers all `custom_components/` sub-directories in the
+release archive, so multi-component repositories are handled correctly.
+
+---
+
+## Fetching frontend plugins (dashboard cards)
+
+`scripts/fetch_plugin.py` downloads **JavaScript dashboard modules** — Lovelace
+cards and similar frontend-only plugins — from GitHub releases.  These are
+distinct from Python custom components: they live in `www/` rather than
+`custom_components/`, and are loaded by the HA frontend via Lovelace resources.
+
+```
+python scripts/fetch_plugin.py owner/repo             # latest release
+python scripts/fetch_plugin.py owner/repo 1.2.3       # specific version
+python scripts/fetch_plugin.py owner/repo --list      # list releases
+python scripts/fetch_plugin.py owner/repo --plugin-name custom-name
+python scripts/fetch_plugin.py owner/repo --resource-type js   # legacy (default: module)
+```
+
+The script:
+1. Downloads JS files from the release (assets, zip assets, or source archive fallback).
+2. Places them at `ha-config/www/dashboard/<plugin-name>/<file>.js`.
+3. Registers each file as a Lovelace resource in `ha-config/lovelace_resources.yaml`.
+
+HA serves `ha-config/www/` at `/local/`, so the plugin is immediately available
+to Lovelace dashboards as `/local/dashboard/<plugin-name>/<file>.js`.
+
+---
+
+## Configuration
+
+### HA version
+
+| Value | Image tag pulled |
+|---|---|
+| `HAVersion.STABLE` (default) | `ghcr.io/home-assistant/home-assistant:stable` |
+| `HAVersion.BETA` | `ghcr.io/home-assistant/home-assistant:beta` |
+| `HAVersion.DEV` | `ghcr.io/home-assistant/home-assistant:dev` |
+| `"2024.6.0"` | `ghcr.io/home-assistant/home-assistant:2024.6.0` |
+
+Override at runtime:
+
+```bash
+HA_VERSION=beta pytest tests/
+HA_VERSION=2024.6.0 make test
+```
+
+### Config & custom components
+
+| Environment variable | Default | Purpose |
+|---|---|---|
+| `HA_VERSION` | `stable` | Image tag |
+| `HA_CONFIG_PATH` | `ha-config/` | Host dir mounted as `/config` |
+| `HA_CUSTOM_COMPONENTS_PATH` | `custom_components/` | Host dir mounted as `/config/custom_components` |
+
+---
+
+## Repository layout
+
+```
+ha-testcontainer/
+├── ha_testcontainer/
+│   ├── __init__.py          # public API: HATestContainer, HAVersion, visual helpers
+│   ├── container.py         # HATestContainer implementation
+│   └── visual.py            # PAGE_LOAD_TIMEOUT, assert_snapshot, inject_ha_token
+├── ha-config/
+│   ├── configuration.yaml        # demo HA config (default_config + demo integration)
+│   ├── lovelace_resources.yaml   # Lovelace resources list (managed by fetch_plugin.py)
+│   ├── www/                      # served at /local/ by HA; plugins downloaded here
+│   └── themes/                   # theme YAML files (auto-loaded)
+├── custom_components/
+│   └── README.md                 # populated by scripts/fetch_component.py (gitignored)
+├── scripts/
+│   ├── fetch_component.py        # download any HA Python component from GitHub releases
+│   └── fetch_plugin.py           # download any JS frontend plugin; register as resource
+├── examples/
+│   └── test_custom_component.py  # boilerplate visual test — copy & customise
+├── tests/
+│   ├── conftest.py               # session-scoped ha / ha_url / ha_token fixtures
+│   ├── test_container_unit.py    # unit tests — no Docker needed (14 tests)
+│   ├── test_container.py         # integration tests — requires Docker (10 tests)
+│   └── visual/
+│       ├── conftest.py      # Playwright fixtures (ha_page, ha_browser_context)
+│       └── snapshots/       # gitignored — no baselines committed here (see below)
+├── docker-compose.yml        # local dev: docker compose up
+├── Makefile                  # setup / test / update-snapshots targets
+└── pyproject.toml
+```
+
+---
+
+## Snapshot-based visual testing
+
+Snapshot tests follow a two-file convention:
+
+| File | Description |
+|---|---|
+| `snapshots/<name>.png` | **Committed baseline** — the ground truth, lives in the **consumer's repo** |
+| `snapshots/<name>.actual.png` | Generated on every run — gitignored |
+
+On the **first run** (or when `SNAPSHOT_UPDATE=1` is set), the actual
+screenshot becomes the baseline.  Subsequent runs diff the two; any pixel
+difference causes the test to fail.
+
+Baselines are placed **next to the calling test file** automatically — no
+configuration needed.
+
+> **Important — baselines are stored in the consumer's repo, not here.**
+> ha-testcontainer is a reusable library; it does not commit any snapshot PNG
+> files.  All `*.png` files under `tests/visual/snapshots/` are gitignored in
+> this repository.  When you write visual tests for your own component, baselines
+> are committed in *your* project's `tests/visual/snapshots/` directory.
+> They will never appear in ha-testcontainer's history.
+
+---
+
+## Testing
+
+The test suite has three tiers:
+
+### Tier 1 — Unit tests (no Docker required)
+
+These run in milliseconds and cover the Python logic of `HATestContainer`
+in isolation (URL construction, token handling, API path normalisation):
+
+```bash
+pip install -e ".[test]"                   # install once
+pytest tests/test_container_unit.py -v
+```
+
+Or via make:
+
+```bash
+make install
+make test
+```
+
+`make test` runs **all** non-browser tests, including both unit and
+integration tests, skipping the visual tier.
+
+### Tier 2 — Integration tests (Docker required)
+
+These start a real Home Assistant container and exercise the full lifecycle
+(onboarding, REST API, demo entities, Lovelace push):
+
+```bash
+# Prerequisites: Docker daemon running, HA image available
+pytest tests/test_container.py -v
+```
+
+The container is started once per pytest session (session-scoped fixture)
+and reused across all tests in the file.  Startup takes ~60 s the first time
+while HA initialises.
+
+Environment variables let you control which image and config directory are
+used:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `HA_VERSION` | `stable` | Image tag (`stable`, `beta`, `dev`, `2024.6.0`, …) |
+| `HA_CONFIG_PATH` | `ha-config/` | Host dir mounted as `/config` |
+| `HA_CUSTOM_COMPONENTS_PATH` | `custom_components/` | Host dir mounted as `/config/custom_components` |
+
+```bash
+HA_VERSION=beta pytest tests/test_container.py -v
+```
+
+### Tier 3 — Visual (Playwright) tests (Docker + Playwright required)
+
+```bash
+pip install -e ".[test]"
+playwright install chromium
+pytest tests/visual/ -v
+```
+
+Or via make:
+
+```bash
+make install
+make test-visual
+```
+
+Visual tests open a Chromium browser, log in to the running HA instance, and
+compare screenshots against committed baselines.  Baselines are stored in the
+**consumer's own repository** — see [Snapshot-based visual testing](#snapshot-based-visual-testing).
+
+### Version smoke tests (slow, optional)
+
+These pull the `stable`, `beta`, and `dev` images in sequence and verify that
+the container starts for each:
+
+```bash
+pytest tests/test_container.py -v -m version_smoke
+# or:
+make test-smoke
+```
+
+They are skipped by default to avoid pulling large images on every run.
+
+---
+
+
+
+UIX's `test/docker-compose.yaml` + `test/configuration.yaml` + `test/lovelace.yaml`
+are replaced by `make up` and UIX writing its own `tests/` using `HATestContainer`.
+
+1. Add `ha-testcontainer` as a dev dependency.
+2. Fetch UIX: `python scripts/fetch_component.py Lint-Free-Technology/uix`.
+3. Replace `docker compose -f test/docker-compose.yaml up` with `make up`.
+4. Copy `examples/test_custom_component.py` into UIX's `tests/visual/`, fill in
+   UIX-specific TODO values, and add UIX-specific test cases.
+5. Delete UIX's `test/` directory.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ha_testcontainer-1.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+ha_testcontainer/__init__.py,sha256=rMoTL2BjJzDO5X-aSnZchImvMvpfWFmr1uJzYiFy0-Y,594
+ha_testcontainer/container.py,sha256=MV1kbffUuhRHbh9CF1I3DPUSNeY6NbRlSyYPumYSFC4,17190
+ha_testcontainer/visual.py,sha256=taiVMlTNOOve-_0qBdQiK8NLITWs0eHLxeX0W3RxHhA,7564
+ha_testcontainer-1.0.1.dist-info/licenses/LICENSE,sha256=ALaaPLr8B2tnawyHtHtOWNWKYtC5EwdCkPum_paUHsM,1077
+ha_testcontainer-1.0.1.dist-info/METADATA,sha256=NwMLsaGQb3csi3ZNIIvwPzfCHHp6zslws5rs20XKvIQ,15759
+ha_testcontainer-1.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ha_testcontainer-1.0.1.dist-info/top_level.txt,sha256=iOAfoZ69H1jesQ1GAzbQ6_3-7To1T6AXCSGJuNWR9Yw,17
+ha_testcontainer-1.0.1.dist-info/RECORD,,

ha_testcontainer-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ha_testcontainer-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lint Free Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ha_testcontainer-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+ha_testcontainer