gridfleet-testkit 0.1.0__py3-none-any.whl

gridfleet_testkit/__init__.py

@@ -0,0 +1,29 @@
+"""Supported Python integration helpers for GridFleet."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .appium import (
+    build_appium_options,
+    create_appium_driver,
+    get_connection_target_from_driver,
+    get_device_config_for_driver,
+)
+from .client import GRID_URL, GRIDFLEET_API_URL, GridFleetClient, HeartbeatThread, register_run_cleanup
+
+try:
+    __version__ = version("gridfleet-testkit")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "GRIDFLEET_API_URL",
+    "GRID_URL",
+    "GridFleetClient",
+    "HeartbeatThread",
+    "__version__",
+    "build_appium_options",
+    "create_appium_driver",
+    "get_connection_target_from_driver",
+    "get_device_config_for_driver",
+    "register_run_cleanup",
+]

gridfleet_testkit/appium.py

@@ -0,0 +1,167 @@
+"""Public Appium driver helpers for GridFleet integrations."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from .client import GridFleetClient
+
+from .client import GRID_URL
+
+
+def _catalog_payload(catalog_client: Any | None) -> dict[str, Any]:
+    if catalog_client is None:
+        from .client import GridFleetClient
+
+        catalog_client = GridFleetClient()
+    if hasattr(catalog_client, "get_driver_pack_catalog"):
+        payload = catalog_client.get_driver_pack_catalog()
+    elif callable(catalog_client):
+        payload = catalog_client()
+    else:
+        payload = catalog_client
+    if isinstance(payload, dict):
+        return payload
+    if isinstance(payload, list):
+        return {"packs": payload}
+    raise ValueError("Driver pack catalog client returned an invalid payload")
+
+
+def _enabled_platform_matches(catalog: dict[str, Any], platform_id: str) -> list[tuple[dict[str, Any], dict[str, Any]]]:
+    packs = catalog.get("packs")
+    if not isinstance(packs, list):
+        raise ValueError("Driver pack catalog payload must include a packs list")
+    matches: list[tuple[dict[str, Any], dict[str, Any]]] = []
+    for pack in packs:
+        if not isinstance(pack, dict) or pack.get("state") != "enabled":
+            continue
+        platforms = pack.get("platforms")
+        if not isinstance(platforms, list):
+            continue
+        for platform in platforms:
+            if isinstance(platform, dict) and platform.get("id") == platform_id:
+                matches.append((pack, platform))
+    return matches
+
+
+def _resolve_pack_platform(
+    *,
+    pack_id: str | None,
+    platform_id: str | None,
+    catalog_client: Any | None,
+) -> tuple[str, dict[str, Any]]:
+    resolved_pack_id = pack_id or os.getenv("GRIDFLEET_TESTKIT_PACK_ID")
+    resolved_platform_id = platform_id or os.getenv("GRIDFLEET_TESTKIT_PLATFORM_ID")
+    if not resolved_platform_id:
+        raise ValueError(
+            "Appium options require pack_id + platform_id, platform_id with an unambiguous catalog match, "
+            "or an explicit raw platformName capability."
+        )
+
+    catalog = _catalog_payload(catalog_client)
+    matches = _enabled_platform_matches(catalog, resolved_platform_id)
+    if resolved_pack_id:
+        for pack, platform in matches:
+            if pack.get("id") == resolved_pack_id:
+                return resolved_pack_id, platform
+        raise ValueError(f"Enabled driver pack platform {resolved_pack_id}:{resolved_platform_id} was not found")
+
+    if len(matches) == 1:
+        pack, platform = matches[0]
+        pack_id_value = pack.get("id")
+        if not isinstance(pack_id_value, str) or not pack_id_value:
+            raise ValueError("Driver pack catalog entry is missing id")
+        return pack_id_value, platform
+    if len(matches) > 1:
+        raise ValueError(f"Multiple enabled driver packs provide platform_id {resolved_platform_id!r}; pass pack_id")
+    raise ValueError(f"Enabled driver pack platform for platform_id {resolved_platform_id!r} was not found")
+
+
+def _required_platform_string(platform: dict[str, Any], key: str) -> str:
+    value = platform.get(key)
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"Driver pack platform is missing {key}")
+    return value
+
+
+def build_appium_options(
+    *,
+    pack_id: str | None = None,
+    platform_id: str | None = None,
+    capabilities: Mapping[str, Any] | None = None,
+    test_name: str | None = None,
+    catalog_client: Any | None = None,
+) -> Any:
+    """Build Appium options from driver-pack catalog platform metadata."""
+    from appium.options.common import AppiumOptions
+
+    params = dict(capabilities or {})
+    explicit_platform_name = params.get("platformName")
+    if explicit_platform_name is not None and (pack_id is not None or platform_id is not None):
+        raise ValueError("Use either pack_id/platform_id or the raw platformName capability, not both.")
+
+    options = AppiumOptions()
+    if explicit_platform_name is None:
+        _pack_id, platform_data = _resolve_pack_platform(
+            pack_id=pack_id,
+            platform_id=platform_id,
+            catalog_client=catalog_client,
+        )
+        options.platform_name = _required_platform_string(platform_data, "appium_platform_name")
+        options.set_capability("appium:automationName", _required_platform_string(platform_data, "automation_name"))
+        options.set_capability("appium:platform", _required_platform_string(platform_data, "id"))
+
+    for key, value in params.items():
+        options.set_capability(key, value)
+
+    if test_name is not None:
+        options.set_capability("gridfleet:testName", test_name)
+    return options
+
+
+def create_appium_driver(
+    *,
+    pack_id: str | None = None,
+    platform_id: str | None = None,
+    capabilities: Mapping[str, Any] | None = None,
+    test_name: str | None = None,
+    grid_url: str = GRID_URL,
+    catalog_client: Any | None = None,
+) -> Any:
+    """Create an Appium remote driver through Selenium Grid."""
+    from appium import webdriver
+
+    options = build_appium_options(
+        pack_id=pack_id,
+        platform_id=platform_id,
+        capabilities=capabilities,
+        test_name=test_name,
+        catalog_client=catalog_client,
+    )
+    return webdriver.Remote(grid_url, options=options)
+
+
+def get_connection_target_from_driver(driver: Any) -> str:
+    """Return the runtime connection target from a live Appium driver."""
+    capabilities = driver.capabilities
+    connection_target = capabilities.get("appium:udid")
+    if not isinstance(connection_target, str) or not connection_target:
+        raise ValueError("Could not determine device connection target from session capabilities")
+    return connection_target
+
+
+def get_device_config_for_driver(
+    driver: Any,
+    *,
+    gridfleet_client: GridFleetClient | None = None,
+    reveal: bool = True,
+) -> dict[str, Any]:
+    """Fetch device config for a live Appium driver using its runtime connection target."""
+    from .client import GridFleetClient
+
+    client = gridfleet_client or GridFleetClient()
+    return client.get_device_config(get_connection_target_from_driver(driver), reveal=reveal)

gridfleet_testkit/client.py

@@ -0,0 +1,242 @@
+"""Public GridFleet client helpers for external test suites."""
+
+from __future__ import annotations
+
+import atexit
+import contextlib
+import logging
+import os
+import signal
+import threading
+from typing import Any, cast
+
+import httpx
+
+GRID_URL = os.getenv("GRID_URL", "http://localhost:4444")
+GRIDFLEET_API_URL = os.getenv("GRIDFLEET_API_URL", "http://localhost:8000/api")
+GRIDFLEET_TESTKIT_USERNAME = os.getenv("GRIDFLEET_TESTKIT_USERNAME")
+GRIDFLEET_TESTKIT_PASSWORD = os.getenv("GRIDFLEET_TESTKIT_PASSWORD")
+
+logger = logging.getLogger("gridfleet_testkit")
+
+
+def _default_auth() -> httpx.BasicAuth | None:
+    """Build httpx Basic auth from env vars, or return None when unset."""
+    username = GRIDFLEET_TESTKIT_USERNAME
+    password = GRIDFLEET_TESTKIT_PASSWORD
+    if not username or not password:
+        return None
+    return httpx.BasicAuth(username, password)
+
+
+class HeartbeatThread(threading.Thread):
+    """Background thread that sends periodic heartbeat pings for an active test run."""
+
+    def __init__(
+        self,
+        base_url: str,
+        run_id: str,
+        interval: int = 30,
+        auth: httpx.BasicAuth | None = None,
+    ):
+        super().__init__(daemon=True)
+        self.base_url = base_url.rstrip("/")
+        self.run_id = run_id
+        self.interval = interval
+        self._auth = auth
+        self._stop_event = threading.Event()
+
+    def run(self) -> None:
+        while not self._stop_event.wait(self.interval):
+            try:
+                resp = httpx.post(
+                    f"{self.base_url}/runs/{self.run_id}/heartbeat",
+                    timeout=10,
+                    auth=self._auth,
+                )
+                resp.raise_for_status()
+                result = resp.json()
+                if result.get("state") in ("expired", "cancelled"):
+                    logger.warning("Run %s is %s, stopping heartbeat", self.run_id, result["state"])
+                    break
+            except Exception:
+                logger.debug("Heartbeat failed for run %s, will retry", self.run_id)
+
+    def stop(self) -> None:
+        self._stop_event.set()
+
+
+class GridFleetClient:
+    """Client for the GridFleet API, used by test fixtures and CI flows."""
+
+    def __init__(
+        self,
+        base_url: str = GRIDFLEET_API_URL,
+        auth: httpx.BasicAuth | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self._auth = auth if auth is not None else _default_auth()
+
+    def get_device_config(self, connection_target: str, reveal: bool = True) -> dict[str, Any]:
+        """Fetch device config by looking up the current runtime connection target."""
+        resp = httpx.get(
+            f"{self.base_url}/devices",
+            params={"connection_target": connection_target},
+            timeout=10,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+        devices = cast("list[dict[str, Any]]", resp.json())
+        if not devices:
+            raise ValueError(f"No device found with connection target: {connection_target}")
+        device_id = devices[0]["id"]
+        config_resp = httpx.get(
+            f"{self.base_url}/devices/{device_id}/config",
+            params={"reveal": str(reveal).lower()},
+            timeout=10,
+            auth=self._auth,
+        )
+        config_resp.raise_for_status()
+        return cast("dict[str, Any]", config_resp.json())
+
+    def get_device_capabilities(self, device_id: str) -> dict[str, Any]:
+        """Fetch the current Appium capabilities for a specific device."""
+        resp = httpx.get(
+            f"{self.base_url}/devices/{device_id}/capabilities",
+            timeout=10,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+        return cast("dict[str, Any]", resp.json())
+
+    def get_driver_pack_catalog(self) -> dict[str, Any]:
+        """Fetch enabled driver pack catalog data used for Appium platform selection."""
+        resp = httpx.get(
+            f"{self.base_url}/driver-packs/catalog",
+            timeout=10,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+        return cast("dict[str, Any]", resp.json())
+
+    def reserve_devices(
+        self,
+        name: str,
+        requirements: list[dict[str, Any]],
+        ttl_minutes: int = 60,
+        heartbeat_timeout_sec: int = 120,
+        created_by: str | None = None,
+    ) -> dict[str, Any]:
+        """Reserve devices for a test run and return the manager response."""
+        resp = httpx.post(
+            f"{self.base_url}/runs",
+            json={
+                "name": name,
+                "requirements": requirements,
+                "ttl_minutes": ttl_minutes,
+                "heartbeat_timeout_sec": heartbeat_timeout_sec,
+                "created_by": created_by,
+            },
+            timeout=30,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+        return cast("dict[str, Any]", resp.json())
+
+    def signal_ready(self, run_id: str) -> None:
+        httpx.post(
+            f"{self.base_url}/runs/{run_id}/ready",
+            timeout=10,
+            auth=self._auth,
+        ).raise_for_status()
+
+    def signal_active(self, run_id: str) -> None:
+        httpx.post(
+            f"{self.base_url}/runs/{run_id}/active",
+            timeout=10,
+            auth=self._auth,
+        ).raise_for_status()
+
+    def heartbeat(self, run_id: str) -> dict[str, Any]:
+        resp = httpx.post(
+            f"{self.base_url}/runs/{run_id}/heartbeat",
+            timeout=10,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+        return cast("dict[str, Any]", resp.json())
+
+    def claim_device(self, run_id: str, *, worker_id: str) -> dict[str, Any]:
+        resp = httpx.post(
+            f"{self.base_url}/runs/{run_id}/claim",
+            json={"worker_id": worker_id},
+            timeout=10,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+        return cast("dict[str, Any]", resp.json())
+
+    def release_device(self, run_id: str, *, device_id: str, worker_id: str) -> None:
+        resp = httpx.post(
+            f"{self.base_url}/runs/{run_id}/release",
+            json={"device_id": device_id, "worker_id": worker_id},
+            timeout=10,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+
+    def report_preparation_failure(
+        self,
+        run_id: str,
+        device_id: str,
+        message: str,
+        source: str = "ci_preparation",
+    ) -> dict[str, Any]:
+        resp = httpx.post(
+            f"{self.base_url}/runs/{run_id}/devices/{device_id}/preparation-failed",
+            json={"message": message, "source": source},
+            timeout=10,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+        return cast("dict[str, Any]", resp.json())
+
+    def complete_run(self, run_id: str) -> None:
+        httpx.post(
+            f"{self.base_url}/runs/{run_id}/complete",
+            timeout=10,
+            auth=self._auth,
+        ).raise_for_status()
+
+    def cancel_run(self, run_id: str) -> None:
+        httpx.post(
+            f"{self.base_url}/runs/{run_id}/cancel",
+            timeout=10,
+            auth=self._auth,
+        ).raise_for_status()
+
+    def start_heartbeat(self, run_id: str, interval: int = 30) -> HeartbeatThread:
+        thread = HeartbeatThread(self.base_url, run_id, interval, auth=self._auth)
+        thread.start()
+        return thread
+
+
+def register_run_cleanup(
+    client: GridFleetClient,
+    run_id: str,
+    heartbeat_thread: HeartbeatThread | None = None,
+) -> None:
+    """Register exit and signal handlers that release reserved devices."""
+
+    def cleanup(*_args: object) -> None:
+        if heartbeat_thread:
+            heartbeat_thread.stop()
+        try:
+            client.complete_run(run_id)
+        except Exception:
+            with contextlib.suppress(Exception):
+                client.cancel_run(run_id)
+
+    atexit.register(cleanup)
+    signal.signal(signal.SIGTERM, cleanup)
+    signal.signal(signal.SIGINT, cleanup)

gridfleet_testkit/py.typed

@@ -0,0 +1 @@
+

gridfleet_testkit/pytest_plugin.py

@@ -0,0 +1,247 @@
+"""Supported pytest plugin surface for GridFleet Appium tests."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import TYPE_CHECKING, Any
+
+import httpx
+import pytest
+
+from .appium import (
+    build_appium_options,
+    get_device_config_for_driver,
+)
+from .client import GRID_URL, GRIDFLEET_API_URL, GridFleetClient, _default_auth
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+logger = logging.getLogger("gridfleet_testkit")
+KNOWN_DEVICE_TYPES = {"real_device", "emulator", "simulator"}
+KNOWN_CONNECTION_TYPES = {"usb", "network"}
+
+
+def _normalize_usage_error_message(message: str) -> str:
+    if message.startswith("Appium options require"):
+        return (
+            "appium_driver requires pack_id + platform_id, platform_id with an unambiguous catalog match, "
+            "or an explicit 'platformName' capability."
+        )
+    return message
+
+
+def _report_session_status(session_id: str, status: str) -> None:
+    """Report final session status to the GridFleet API."""
+    try:
+        resp = httpx.patch(
+            f"{GRIDFLEET_API_URL}/sessions/{session_id}/status",
+            json={"status": status},
+            timeout=5,
+            auth=_default_auth(),
+        )
+        resp.raise_for_status()
+    except httpx.HTTPError as exc:
+        logger.warning("Failed to report session status to GridFleet: %s", exc)
+
+
+def _register_session(driver: Any, test_name: str) -> None:
+    """Register a newly-created Grid session with the GridFleet API."""
+    capabilities = getattr(driver, "capabilities", {})
+    if not isinstance(capabilities, dict):
+        capabilities = {}
+
+    payload: dict[str, Any] = {
+        "session_id": driver.session_id,
+        "test_name": test_name,
+    }
+    device_id = capabilities.get("appium:gridfleet:deviceId") or capabilities.get("gridfleet:deviceId")
+    if isinstance(device_id, str) and device_id:
+        payload["device_id"] = device_id
+
+    connection_target = capabilities.get("appium:udid") or capabilities.get("appium:deviceName")
+    if isinstance(connection_target, str) and connection_target:
+        payload["connection_target"] = connection_target
+
+    try:
+        resp = httpx.post(
+            f"{GRIDFLEET_API_URL}/sessions",
+            json=payload,
+            timeout=5,
+            auth=_default_auth(),
+        )
+        resp.raise_for_status()
+    except httpx.HTTPError as exc:
+        logger.warning("Failed to register session with GridFleet: %s", exc)
+
+
+def _register_error_session(payload: dict[str, Any]) -> None:
+    """Register a device-less error session with the GridFleet API.
+
+    Used when driver creation fails before a Grid session is established so
+    the failure is still visible in the Dashboard Sessions view.
+    """
+    try:
+        resp = httpx.post(
+            f"{GRIDFLEET_API_URL}/sessions",
+            json=payload,
+            timeout=5,
+            auth=_default_auth(),
+        )
+        resp.raise_for_status()
+    except httpx.HTTPError as exc:
+        logger.warning("Failed to register error session with GridFleet: %s", exc)
+
+
+def _build_driver_options(request: pytest.FixtureRequest) -> Any:
+    params = getattr(request, "param", {})
+    capabilities = {key: value for key, value in params.items() if key not in {"pack_id", "platform_id"}}
+    try:
+        return build_appium_options(
+            pack_id=params.get("pack_id"),
+            platform_id=params.get("platform_id"),
+            capabilities=capabilities,
+            test_name=request.node.name,
+            catalog_client=GridFleetClient(),
+        )
+    except ValueError as exc:
+        raise pytest.UsageError(_normalize_usage_error_message(str(exc))) from exc
+
+
+def _raw_attempted_capabilities(options: Any) -> dict[str, Any]:
+    capabilities = getattr(options, "capabilities", {})
+    raw_capabilities = dict(capabilities) if isinstance(capabilities, dict) else {}
+    platform_name = getattr(options, "platform_name", None)
+    if isinstance(platform_name, str) and platform_name:
+        raw_capabilities.setdefault("platformName", platform_name)
+    return raw_capabilities
+
+
+def _infer_requested_platform_id(params: dict[str, Any], raw_capabilities: dict[str, Any]) -> str | None:
+    platform_id = params.get("platform_id")
+    if isinstance(platform_id, str) and platform_id:
+        return platform_id
+    platform_hint = raw_capabilities.get("appium:platform")
+    return platform_hint if isinstance(platform_hint, str) and platform_hint else None
+
+
+def _read_enum_capability(raw_capabilities: dict[str, Any], *keys: str, allowed: set[str]) -> str | None:
+    for key in keys:
+        value = raw_capabilities.get(key)
+        if isinstance(value, str) and value in allowed:
+            return value
+    return None
+
+
+def _build_error_session_payload(
+    *,
+    request: pytest.FixtureRequest,
+    options: Any,
+    exc: Exception,
+    session_id: str,
+) -> dict[str, Any]:
+    params = getattr(request, "param", {})
+    raw_capabilities = _raw_attempted_capabilities(options)
+    payload: dict[str, Any] = {
+        "session_id": session_id,
+        "test_name": request.node.name,
+        "status": "error",
+        "requested_platform_id": _infer_requested_platform_id(params, raw_capabilities),
+        "requested_device_type": _read_enum_capability(
+            raw_capabilities,
+            "appium:device_type",
+            "device_type",
+            allowed=KNOWN_DEVICE_TYPES,
+        ),
+        "requested_connection_type": _read_enum_capability(
+            raw_capabilities,
+            "appium:connection_type",
+            "connection_type",
+            allowed=KNOWN_CONNECTION_TYPES,
+        ),
+        "requested_capabilities": raw_capabilities,
+        "error_type": type(exc).__name__,
+        "error_message": str(exc),
+    }
+    return payload
+
+
+@pytest.fixture
+def appium_driver(request: pytest.FixtureRequest) -> Generator[Any, None, None]:
+    """
+    Create an Appium Remote driver through the Selenium Grid.
+
+    Parametrize with a dict of pack/catalog selection plus capabilities:
+        @pytest.mark.parametrize(
+            "appium_driver",
+            [{"pack_id": "appium-uiautomator2", "platform_id": "android_mobile"}],
+            indirect=True,
+        )
+    """
+    try:
+        options = _build_driver_options(request)
+    except ValueError as exc:
+        raise pytest.UsageError(_normalize_usage_error_message(str(exc))) from exc
+    from appium import webdriver
+
+    try:
+        driver = webdriver.Remote(GRID_URL, options=options)
+    except Exception as exc:
+        # Driver creation failed before a Grid session was established (e.g.
+        # SessionNotCreatedException). Register a device-less error session so the
+        # failure is visible in the Dashboard Sessions view.
+        synthetic_id = f"error-{uuid.uuid4()}"
+        _register_error_session(
+            _build_error_session_payload(request=request, options=options, exc=exc, session_id=synthetic_id)
+        )
+        raise
+    session_id = driver.session_id
+    if not isinstance(session_id, str) or not session_id:
+        raise RuntimeError("Created Appium driver did not expose a session ID")
+    _register_session(driver, request.node.name)
+
+    yield driver
+
+    status: str | None = None
+    if hasattr(request.node, "rep_call"):
+        if request.node.rep_call.passed:
+            status = "passed"
+        elif request.node.rep_call.failed:
+            status = "failed"
+        else:
+            status = "error"
+
+    try:
+        driver.quit()
+    finally:
+        if status is not None:
+            _report_session_status(session_id, status)
+
+
+@pytest.hookimpl(tryfirst=True, hookwrapper=True)
+def pytest_runtest_makereport(item: pytest.Item) -> Generator[Any, None, None]:
+    """Store the test outcome on the item for fixture teardown reporting."""
+    outcome: Any = yield
+    rep = outcome.get_result()
+    setattr(item, f"rep_{rep.when}", rep)
+
+
+@pytest.fixture(scope="session")
+def gridfleet_client() -> GridFleetClient:
+    return GridFleetClient()
+
+
+@pytest.fixture
+def device_config(appium_driver: Any, gridfleet_client: GridFleetClient) -> dict[str, Any]:
+    """
+    Fetch device config after the Grid assigns a runtime connection target.
+
+    Usage:
+        def test_login(appium_driver, device_config):
+            username = device_config["app_username"]
+    """
+    try:
+        return get_device_config_for_driver(appium_driver, gridfleet_client=gridfleet_client)
+    except ValueError:
+        pytest.skip("Could not determine device connection target from session capabilities")

gridfleet_testkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: gridfleet-testkit
+Version: 0.1.0
+Summary: Supported pytest and run-orchestration helpers for GridFleet integrations
+Project-URL: Homepage, https://github.com/quidow/gridfleet
+Project-URL: Repository, https://github.com/quidow/gridfleet
+Project-URL: Documentation, https://github.com/quidow/gridfleet/tree/main/docs/reference/testkit.md
+Project-URL: Issues, https://github.com/quidow/gridfleet/issues
+Project-URL: Security, https://github.com/quidow/gridfleet/security/advisories/new
+Author: GridFleet contributors
+License-Expression: Apache-2.0
+Keywords: appium,gridfleet,pytest,selenium,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pytest>=9.0.3
+Provides-Extra: appium
+Requires-Dist: appium-python-client>=4.5; extra == 'appium'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.20.2; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.15.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# GridFleet Testkit
+
+`testkit/` is the supported Python integration surface for external pytest/Appium suites that run through GridFleet.
+
+## What This Package Owns
+
+- Stable import root: `gridfleet_testkit`
+- Supported pytest plugin: `gridfleet_testkit.pytest_plugin`
+- Supported public helpers:
+  - `build_appium_options`
+  - `create_appium_driver`
+  - `get_connection_target_from_driver`
+  - `get_device_config_for_driver`
+  - `GridFleetClient`
+  - `HeartbeatThread`
+  - `register_run_cleanup`
+- Manual hardware examples under `testkit/examples/`
+
+## What It Does Not Own
+
+- Appium server installation or host-level driver setup
+- Selenium Grid lifecycle
+- Device registration, verification, or readiness setup
+- CI orchestration beyond the documented client helpers
+
+The supported contract is the installable package and documented import pattern. The example scripts are onboarding aids, not CI-backed conformance tests.
+
+## Install
+
+From PyPI:
+
+```bash
+pip install "gridfleet-testkit[appium]"
+```
+
+From a local checkout:
+
+```bash
+uv pip install -e ./testkit[appium]
+```
+
+From a copied `testkit/` directory inside another repository:
+
+```bash
+uv pip install -e ./testkit[appium]
+```
+
+From a Git checkout or VCS URL that contains this package:
+
+```bash
+uv pip install "git+https://github.com/<org>/<repo>.git#subdirectory=testkit"
+```
+
+The package supports Python 3.10 and newer.
+
+## Environment
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `GRID_URL` | `http://localhost:4444` | Selenium Grid hub URL used by the pytest Appium fixture |
+| `GRIDFLEET_API_URL` | `http://localhost:8000/api` | GridFleet API base used for session reporting, config lookup, run helpers, and driver-pack catalog lookup |
+| `GRIDFLEET_TESTKIT_USERNAME` | unset | Machine-auth username sent as HTTP Basic auth on every API call. Required when the manager runs with `GRIDFLEET_AUTH_ENABLED=true`. Use the same value as the manager's `GRIDFLEET_MACHINE_AUTH_USERNAME`. |
+| `GRIDFLEET_TESTKIT_PASSWORD` | unset | Machine-auth password sent as HTTP Basic auth on every API call. Required when the manager runs with `GRIDFLEET_AUTH_ENABLED=true`. Use the same value as the manager's `GRIDFLEET_MACHINE_AUTH_PASSWORD`. |
+| `GRIDFLEET_TESTKIT_PACK_ID` | unset | Optional default driver pack id for Appium option building |
+| `GRIDFLEET_TESTKIT_PLATFORM_ID` | unset | Optional default platform id for Appium option building |
+
+The package assumes a running GridFleet API, a reachable Selenium Grid hub, and platform-specific Appium driver setup on the registered hosts. When auth is disabled on the manager, leave `GRIDFLEET_TESTKIT_USERNAME` / `GRIDFLEET_TESTKIT_PASSWORD` unset and the testkit will send no `Authorization` header.
+
+## Pytest Plugin
+
+Load the supported plugin from your test project:
+
+```python
+pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
+```
+
+Minimal usage:
+
+```python
+import pytest
+
+@pytest.mark.parametrize(
+    "appium_driver",
+    [{"pack_id": "appium-uiautomator2", "platform_id": "android_mobile"}],
+    indirect=True,
+)
+def test_session_starts(appium_driver):
+    assert appium_driver.session_id is not None
+```
+
+The plugin resolves `pack_id` and `platform_id` against the enabled driver-pack catalog, then injects Appium `platformName`, `appium:automationName`, `appium:platform`, and `gridfleet:testName`.
+
+When exactly one enabled pack provides a platform id, `platform_id` alone is accepted. For environment-portable tests, set `GRIDFLEET_TESTKIT_PACK_ID` and `GRIDFLEET_TESTKIT_PLATFORM_ID`, then parametrize with `{}`.
+
+If you need raw Appium control instead, omit `pack_id` and `platform_id`, then pass `platformName` as a normal capability key.
+
+### Plugin Lifecycle
+
+- Creates an Appium session through `GRID_URL`
+- Injects `gridfleet:testName` with the pytest test name
+- Reports final session status back to `GRIDFLEET_API_URL`
+- Exposes `device_config` for post-session config lookup using the runtime connection target
+- Relies on manager-owned runtime isolation for Appium driver sub-ports and XCUITest build paths
+
+## Direct Appium Usage
+
+If you need to create a driver outside pytest, use the public Appium helpers:
+
+```python
+from gridfleet_testkit import create_appium_driver, get_device_config_for_driver
+
+driver = create_appium_driver(
+    pack_id="appium-uiautomator2",
+    platform_id="firetv_real",
+    test_name="manual-smoke",
+)
+
+try:
+    assert driver.session_id is not None
+    device_config = get_device_config_for_driver(driver)
+finally:
+    driver.quit()
+```
+
+`create_appium_driver(...)` reuses the same driver-pack catalog resolver as the pytest fixture. Managed nodes still get their host-scoped runtime allocations from the manager, so callers should not hard-code `systemPort`, `chromedriverPort`, `mjpegServerPort`, `wdaLocalPort`, or `derivedDataPath`. `get_device_config_for_driver(...)` is the non-pytest equivalent of the `device_config` fixture. If you only need the options object, use `build_appium_options(...)`.
+
+## Client Helpers
+
+| Helper | Purpose |
+| --- | --- |
+| `GridFleetClient.get_device_config(connection_target, reveal=True)` | Look up a device by runtime connection target and fetch its config |
+| `GridFleetClient.get_driver_pack_catalog()` | Fetch enabled driver-pack catalog data for Appium platform selection |
+| `GridFleetClient.reserve_devices(...)` | Create a run/reservation and return the manager response |
+| `GridFleetClient.signal_ready(run_id)` | Move a run to `ready` |
+| `GridFleetClient.signal_active(run_id)` | Move a run to `active` |
+| `GridFleetClient.heartbeat(run_id)` | Send a run heartbeat and read current state |
+| `GridFleetClient.report_preparation_failure(run_id, device_id, message, source="ci_preparation")` | Exclude one reserved device after setup fails |
+| `GridFleetClient.complete_run(run_id)` | Complete a run |
+| `GridFleetClient.cancel_run(run_id)` | Cancel a run |
+| `GridFleetClient.start_heartbeat(run_id, interval=30)` | Start a background heartbeat thread |
+| `register_run_cleanup(client, run_id, heartbeat_thread=None)` | Register `atexit` and signal cleanup that completes or cancels a run |
+
+### Reservation Flow
+
+```python
+from gridfleet_testkit import GridFleetClient, register_run_cleanup
+
+client = GridFleetClient("http://manager-ip:8000/api")
+
+run = client.reserve_devices(
+    name="my-test-run",
+    requirements=[
+        {
+            "pack_id": "appium-uiautomator2",
+            "platform_id": "firetv_real",
+            "os_version": "8",
+            "allocation": "all_available",
+            "min_count": 1,
+        }
+    ],
+    ttl_minutes=45,
+    created_by="local-dev",
+)
+
+run_id = run["id"]
+worker_count = len(run["devices"])
+heartbeat_thread = client.start_heartbeat(run_id, interval=30)
+register_run_cleanup(client, run_id, heartbeat_thread)
+
+# If one reserved device fails setup:
+client.report_preparation_failure(
+    run_id,
+    device_id="device-123",
+    message="Driver bootstrap timed out during CI setup",
+    source="local-dev",
+)
+
+client.signal_ready(run_id)
+client.signal_active(run_id)
+```
+
+Use `count` for exact reservations. Use `allocation: "all_available"` when CI should reserve every currently eligible matching device and size its worker pool from `len(run["devices"])`.
+
+## Examples
+
+Baseline screenshot examples:
+
+- `examples/test_android_mobile_screenshot.py`
+- `examples/test_android_tv_screenshot.py`
+- `examples/test_firetv_screenshot.py`
+- `examples/test_ios_simulator_screenshot.py`
+- `examples/test_tvos_screenshot.py`
+- `examples/test_roku_screenshot.py`
+
+Advanced example:
+
+- `examples/test_roku_sideload_screenshot.py`
+
+The baseline examples share the same flow:
+
+1. Create a session through Selenium Grid
+2. Print the resolved connection context
+3. Save a screenshot
+4. Assert that the screenshot file exists and is non-empty
+
+## Platform Notes
+
+- Android Mobile / Android TV / Fire TV:
+  - require the UiAutomator2 driver
+  - rely on Grid routing hints generated from GridFleet metadata
+- Fire TV:
+  - baseline example supports optional `appium:os_version` filtering when you need a specific Fire OS release
+- iOS simulator:
+  - baseline example intentionally targets the simulator lane with `appium:device_type=simulator`
+- tvOS:
+  - baseline example intentionally targets a real device and assumes the host already satisfies XCUITest and WebDriverAgent prerequisites
+- Roku:
+  - screenshot examples install and activate the bundled sample dev app before capture
+  - both Roku examples depend on Roku dev credentials

gridfleet_testkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+gridfleet_testkit/__init__.py,sha256=aIHLcVP6WZeL5C3b1y4wyNX9edR9SVBwyGfn-qHjtNM,764
+gridfleet_testkit/appium.py,sha256=jJgWKpr8MEhBlVdT9S7qlaNBE3voZ75nB-fUMzXXmI4,6269
+gridfleet_testkit/client.py,sha256=-beG-7CIbfIpRXr_75SwcfP_hJ6S3HnLJTgqnNaHgkM,8022
+gridfleet_testkit/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+gridfleet_testkit/pytest_plugin.py,sha256=ldMxAqgCHuG5SkPyEY7S4U6Oxz2Sux5ur-rAryEQdGw,8569
+gridfleet_testkit-0.1.0.dist-info/METADATA,sha256=EBhfyqFSfkwc_jgw0NK0aXEAiZxPyAa6TAziQnYrArA,9993
+gridfleet_testkit-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+gridfleet_testkit-0.1.0.dist-info/entry_points.txt,sha256=L54RzqsaWcj2VehfndWEwgu5FX5J_rCq7dww-e7DoU0,55
+gridfleet_testkit-0.1.0.dist-info/RECORD,,

gridfleet_testkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gridfleet_testkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+gridfleet = gridfleet_testkit.pytest_plugin