Merge pull request #240 from homeassistant-ai/feature/custom-test-port

feat: add HA_TEST_PORT env var for custom test container port

Author: Julien Larocque-Dupont

tests/src/e2e/conftest.py

@@ -3,10 +3,16 @@
 
 This provides testcontainers integration but falls back to the existing
 Docker environment if testcontainers has issues.
+
+Environment Variables:
+    HA_TEST_PORT: Optional fixed port for Home Assistant container (default: dynamic)
+                  Set this to bind to a specific host port instead of random assignment.
+                  Example: HA_TEST_PORT=8123
 """
 
 import asyncio
 import logging
+import os
 import shutil
 import sys
 import tempfile
@@ -103,12 +109,22 @@ def ha_container_with_fresh_config():
         f"📁 Fresh HA config prepared at: {config_path} with proper permissions"
     )
 
-    # Create testcontainer with automatic port assignment
+    # Create testcontainer with port configuration
     # renovate: datasource=docker depName=ghcr.io/home-assistant/home-assistant
     container = DockerContainer("ghcr.io/home-assistant/home-assistant:2025.11.3")
-    container = container.with_exposed_ports(
-        8123
-    )  # Expose port, let testcontainers assign host port
+
+    # Check for custom port via environment variable
+    custom_port = os.environ.get("HA_TEST_PORT")
+    if custom_port:
+        try:
+            port = int(custom_port)
+            container = container.with_bind_ports(8123, port)
+            logger.info(f"🔌 Using fixed port {port} (from HA_TEST_PORT)")
+        except ValueError:
+            logger.warning(f"⚠️ Invalid HA_TEST_PORT '{custom_port}', using dynamic port")
+            container = container.with_exposed_ports(8123)
+    else:
+        container = container.with_exposed_ports(8123)  # Dynamic port assignment
     container = container.with_volume_mapping(
         str(config_path), "/config", "rw"
     )  # Ensure read-write mount

tests/test_env_manager.py

@@ -4,6 +4,10 @@
 
 Interactive test environment for Home Assistant MCP Server development.
 Uses testcontainers to manage a Home Assistant instance for testing.
+
+Environment Variables:
+    HA_TEST_PORT: Optional fixed port for Home Assistant container (default: random)
+                  Example: HA_TEST_PORT=8123
 """
 
 import logging
@@ -97,11 +101,25 @@ def start_container(self) -> None:
         # Set up config directory
         config_dir = self._setup_config_directory()
 
-        # Create and start container
+        # Create container with port configuration
+        # renovate: datasource=docker depName=ghcr.io/home-assistant/home-assistant
+        container = DockerContainer("ghcr.io/home-assistant/home-assistant:2025.11.3")
+
+        # Check for custom port via environment variable
+        custom_port = os.environ.get("HA_TEST_PORT")
+        if custom_port:
+            try:
+                port = int(custom_port)
+                container = container.with_bind_ports(8123, port)
+                logger.info(f"🔌 Using fixed port {port} (from HA_TEST_PORT)")
+            except ValueError:
+                logger.warning(f"⚠️ Invalid HA_TEST_PORT '{custom_port}', using random port")
+                container = container.with_bind_ports(8123, None)
+        else:
+            container = container.with_bind_ports(8123, None)  # Random host port
+
         self.container = (
-            # renovate: datasource=docker depName=ghcr.io/home-assistant/home-assistant
-            DockerContainer("ghcr.io/home-assistant/home-assistant:2025.11.3")
-            .with_bind_ports(8123, None)  # Random host port
+            container
             .with_volume_mapping(str(config_dir), "/config", "rw")
             .with_env("TZ", "UTC")
             .with_kwargs(privileged=True)