Automatically run guides and gather screenshots of the steps

pyproject.toml

@@ -9,9 +9,11 @@ dependencies = ["homeassistant>=2025.12.2", "numpy>=2.3.2", "highspy>=1.12.0"]
 
 [dependency-groups]
 dev = [
+    "beautifulsoup4>=4.14.3",
     "freezegun>=1.5.2",
     "matplotlib>=3.10.8",
     "networkx>=3.4.2",
+    "playwright>=1.57.0",
     "mdformat-beautysh>=1.0.0",
     "mdformat-config>=0.2.1",
     "mdformat-footnote>=0.1.1",
@@ -134,6 +136,9 @@ addopts = ["--strict-markers", "--strict-config"]
 filterwarnings = ["error"]
 markers = [
     "scenario: marks tests as scenario tests (select with '-m \"scenario\"')",
+    "browser: marks tests as browser automation tests (select with '-m \"browser\"')",
+    "guide: marks tests as guide screenshot tests (select with '-m \"guide\"')",
+    "enable_socket: marks tests that need real socket access",
 ]
 
 [tool.coverage.run]

tests/conftest.py

@@ -119,6 +119,17 @@ def configure_logging() -> None:
 
 
 @pytest.fixture(autouse=True)
-def auto_enable_custom_integrations(enable_custom_integrations: None) -> bool:
-    """Enable loading custom integrations in all tests."""
+def auto_enable_custom_integrations(request: pytest.FixtureRequest) -> bool:
+    """Enable loading custom integrations in all tests.
+
+    Skip for guide tests which use their own HA instance without
+    the pytest-homeassistant-custom-component fixtures.
+    """
+    # Skip for guide tests - they don't use the hass fixture
+    if "guide" in (mark.name for mark in request.node.iter_markers()):
+        return True
+
+    # For non-guide tests, request the enable_custom_integrations fixture
+    # which depends on the hass fixture
+    enable_custom_integrations = request.getfixturevalue("enable_custom_integrations")
     return enable_custom_integrations is None

tests/guides/.gitignore

@@ -0,0 +1,5 @@
+# Screenshot outputs (generated by guide tests)
+*/screenshots*
+
+# Log files
+*.log

tests/guides/__init__.py

@@ -0,0 +1 @@
+"""Guide tests with browser automation and live Home Assistant."""

tests/guides/conftest.py

@@ -0,0 +1,22 @@
+"""Configuration for guide tests.
+
+Guide tests are designed to run Home Assistant in-process with browser
+automation. They do NOT use pytest-homeassistant-custom-component fixtures
+since they need a full HTTP server for Playwright.
+
+These tests should be run with:
+    uv run python tests/guides/<test_file>.py
+
+Or via pytest with explicit socket enabling:
+    uv run pytest tests/guides/ --force-enable-socket -m guide
+"""
+
+import pytest
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Register guide marker."""
+    config.addinivalue_line(
+        "markers",
+        "guide: mark test as a guide test (runs full HA with HTTP, needs network)",
+    )