gridfleet-testkit 0.5.0__tar.gz → 0.7.0__tar.gz

{gridfleet_testkit-0.5.0 → gridfleet_testkit-0.7.0}/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to the GridFleet testkit (`gridfleet-testkit` on PyPI) are documented here.
 
+## [0.7.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.6.0...gridfleet-testkit-v0.7.0) (2026-05-11)
+
+
+### ⚠ BREAKING CHANGES
+
+* **testkit:** AllocatedDevice hydration now accepts device handles, not claim payloads.
+* **testkit:** GridFleetClient claim/release helpers and NoClaimableDevicesError are removed.
+
+### Features
+
+* **testkit:** drop claim release client api ([8d1f295](https://github.com/quidow/gridfleet/commit/8d1f29504e6d640ce9d85c70594a515868045be8))
+* **testkit:** inject grid run id capability ([b4ae38c](https://github.com/quidow/gridfleet/commit/b4ae38ce9969ae325bffdb9716ba7d6c52a699ac))
+* **testkit:** resolve device handle by connection target ([22b4299](https://github.com/quidow/gridfleet/commit/22b4299d6bc4302503a2c2b6f17018ceebc03084))
+
+
+### Bug Fixes
+
+* **agent:** release adapter-owned doctor refactor ([#165](https://github.com/quidow/gridfleet/issues/165)) ([f3ae257](https://github.com/quidow/gridfleet/commit/f3ae25787e2c8ef926312f11d2313c6513f8bfa9))
+
+
+### Dependencies
+
+* **deps:** bump urllib3 from 2.6.3 to 2.7.0 in /testkit ([#186](https://github.com/quidow/gridfleet/issues/186)) ([dd7a1df](https://github.com/quidow/gridfleet/commit/dd7a1df8fb29ae76f618abab947db2027471b536))
+
+
+### Code Refactoring
+
+* **testkit:** drop claim response allocation metadata ([f0eec3e](https://github.com/quidow/gridfleet/commit/f0eec3e9c9f804439241ddbbb56b196bc467effd))
+
+## [0.6.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.5.0...gridfleet-testkit-v0.6.0) (2026-05-10)
+
+
+### ⚠ BREAKING CHANGES
+
+* **backend:** clients sending {drain: true|false} to /api/devices/ {id}/maintenance, /api/devices/bulk/enter-maintenance, or the group bulk equivalent must drop the field. The enter-maintenance behaviour is unchanged from drain=false (always stop the node).
+
+### Features
+
+* **backend:** device state model drift fixes (D1-D6) ([#144](https://github.com/quidow/gridfleet/issues/144)) ([09556fd](https://github.com/quidow/gridfleet/commit/09556fdac8ddb458f1655f9001f25240443062fb))
+
 ## [0.5.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.4.0...gridfleet-testkit-v0.5.0) (2026-05-08)
 
 

{gridfleet_testkit-0.5.0 → gridfleet_testkit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridfleet-testkit
-Version: 0.5.0
+Version: 0.7.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

{gridfleet_testkit-0.5.0 → gridfleet_testkit-0.7.0}/gridfleet_testkit/__init__.py

@@ -2,8 +2,7 @@
 
 `device_config` values returned by the manager are verbatim; the testkit no
 longer distinguishes between masked and revealed payloads. Code that wants
-the live Appium-side config can use either inline `config` from
-`claim_device(include=("config",))` or `client.get_device_config(connection_target)`.
+the live Appium-side config can use `client.get_device_config(connection_target)`.
 
 Environment variables read by the client:
 
@@ -32,31 +31,27 @@ from .appium import (
     get_device_test_data_for_driver,
 )
 from .client import (
-    CooldownResult,
     GridFleetClient,
     HeartbeatThread,
-    NoClaimableDevicesError,
     ReserveCapabilitiesUnsupportedError,
     UnknownIncludeError,
     _default_api_url,
     _default_grid_url,
     register_run_cleanup,
 )
-from .sessions import build_error_session_payload
+from .sessions import build_error_session_payload, resolve_device_handle_from_driver
 
 try:
     __version__ = version("gridfleet-testkit")
 except PackageNotFoundError:
-    __version__ = "0.5.0"
+    __version__ = "0.7.0"
 
 __all__ = [
     "GRIDFLEET_API_URL",
     "GRID_URL",
     "AllocatedDevice",
-    "CooldownResult",
     "GridFleetClient",
     "HeartbeatThread",
-    "NoClaimableDevicesError",
     "ReserveCapabilitiesUnsupportedError",
     "UnavailableInclude",
     "UnknownIncludeError",
@@ -70,6 +65,7 @@ __all__ = [
     "hydrate_allocated_device",
     "hydrate_allocated_device_from_driver",
     "register_run_cleanup",
+    "resolve_device_handle_from_driver",
 ]
 
 

{gridfleet_testkit-0.5.0 → gridfleet_testkit-0.7.0}/gridfleet_testkit/allocation.py

@@ -19,7 +19,7 @@ class UnavailableInclude:
 
 @dataclass(frozen=True)
 class AllocatedDevice:
-    """Combined view of a claimed device, ready for driver creation."""
+    """Combined view of an allocated device, ready for driver creation."""
 
     run_id: str
     device_id: str
@@ -35,8 +35,6 @@ class AllocatedDevice:
     connection_type: str
     manufacturer: str | None
     model: str | None
-    claimed_by: str
-    claimed_at: str
     config: dict[str, Any] | None
     live_capabilities: dict[str, Any] | None
     test_data: dict[str, Any] | None = None
@@ -115,7 +113,7 @@ def _parse_unavailable_includes(payload: dict[str, Any]) -> tuple[UnavailableInc
 
 
 def hydrate_allocated_device(
-    claim_response: dict[str, Any],
+    device_handle: dict[str, Any],
     *,
     run_id: str,
     client: GridFleetClient,
@@ -123,15 +121,8 @@ def hydrate_allocated_device(
     fetch_capabilities: bool = False,
     fetch_test_data: bool = False,
 ) -> AllocatedDevice:
-    """Combine a claim response with optional static config and live capabilities.
-
-    Accepts a ``ClaimResponse`` payload from ``GridFleetClient.claim_device`` only.
-    Reserve responses (``RunCreateResponse.devices`` entries before any worker
-    has claimed) lack ``claimed_by`` / ``claimed_at`` and will raise
-    ``ValueError``. Iterate ``reserve_response['devices']`` and call
-    ``claim_device`` per worker before hydrating.
-    """
-    payload = dict(claim_response)
+    """Combine a device handle with optional static config and live capabilities."""
+    payload = dict(device_handle)
     device_id = _string_value(payload, "device_id")
     if _needs_device_detail(payload):
         payload = _merge_device_detail(payload, client.get_device(device_id))
@@ -178,8 +169,6 @@ def hydrate_allocated_device(
         connection_type=_string_value(payload, "connection_type"),
         manufacturer=_optional_string_value(payload, "manufacturer"),
         model=_optional_string_value(payload, "model"),
-        claimed_by=_string_value(payload, "claimed_by"),
-        claimed_at=_string_value(payload, "claimed_at"),
         config=config,
         live_capabilities=live_capabilities,
         test_data=test_data,

{gridfleet_testkit-0.5.0 → gridfleet_testkit-0.7.0}/gridfleet_testkit/appium.py

@@ -98,6 +98,7 @@ def build_appium_options(
     from appium.options.common import AppiumOptions  # noqa: PLC0415
 
     params = dict(capabilities or {})
+    params.setdefault("gridfleet:run_id", os.environ.get("GRIDFLEET_RUN_ID", "free"))
     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.")

{gridfleet_testkit-0.5.0 → gridfleet_testkit-0.7.0}/gridfleet_testkit/client.py

@@ -7,10 +7,9 @@ import logging
 import os
 import signal
 import threading
-import time
 from collections.abc import Callable
-from datetime import datetime, timezone
-from typing import TYPE_CHECKING, Any, Literal, TypedDict, cast
+from typing import TYPE_CHECKING, Any, Literal, cast
+from urllib.parse import quote
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -40,31 +39,6 @@ def __getattr__(name: str) -> str:
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
-class CooldownSetResult(TypedDict):
-    """Response shape when a cooldown is applied without reaching the escalation threshold."""
-
-    status: Literal["cooldown_set"]
-    reservation: dict[str, Any]
-    device_operational_state: str
-    device_hold: str | None
-    retry_after_sec: int
-    excluded_until: str
-
-
-class CooldownEscalatedResult(TypedDict):
-    """Response shape when the cooldown count reaches the threshold and the device is escalated to maintenance."""
-
-    status: Literal["maintenance_escalated"]
-    reservation: dict[str, Any]
-    device_operational_state: str
-    device_hold: str | None
-    cooldown_count: int
-    threshold: int
-
-
-CooldownResult = CooldownSetResult | CooldownEscalatedResult
-
-
 def _default_auth() -> httpx.BasicAuth | None:
     """Build httpx Basic auth from env vars, or return None when unset."""
     username = os.getenv("GRIDFLEET_TESTKIT_USERNAME")
@@ -74,23 +48,6 @@ def _default_auth() -> httpx.BasicAuth | None:
     return httpx.BasicAuth(username, password)
 
 
-class NoClaimableDevicesError(RuntimeError):
-    """Raised when the manager reports that no run devices are claimable yet."""
-
-    def __init__(
-        self,
-        message: str,
-        *,
-        retry_after_sec: int,
-        run_id: str = "",
-        next_available_at: str | None = None,
-    ) -> None:
-        self.run_id = run_id
-        self.retry_after_sec = retry_after_sec
-        self.next_available_at = next_available_at
-        super().__init__(message)
-
-
 class UnknownIncludeError(ValueError):
     """Backend rejected one or more `?include=` keys."""
 
@@ -103,29 +60,11 @@ class ReserveCapabilitiesUnsupportedError(ValueError):
     """`?include=capabilities` is not supported on reserve."""
 
     def __init__(self, message: str | None = None) -> None:
-        super().__init__(message or "include=capabilities is not supported on reserve; use include on claim_device")
+        super().__init__(message or "include=capabilities is not supported on reserve")
 
 
 def _raise_for_status(resp: Any, *, run_id: str) -> None:
-    if resp.status_code == 409:
-        try:
-            payload = resp.json()
-        except Exception:
-            payload = None
-        error = payload.get("error") if isinstance(payload, dict) else None
-        if isinstance(error, dict):
-            details = error.get("details")
-            if isinstance(details, dict) and details.get("error") == "no_claimable_devices":
-                retry_after = details.get("retry_after_sec")
-                if not isinstance(retry_after, int):
-                    retry_after = 5
-                next_available_at = details.get("next_available_at")
-                raise NoClaimableDevicesError(
-                    str(error.get("message") or "No unclaimed devices available in this run"),
-                    run_id=run_id,
-                    retry_after_sec=retry_after,
-                    next_available_at=next_available_at if isinstance(next_available_at, str) else None,
-                )
+    del run_id
     if resp.status_code == 422:
         try:
             payload = resp.json()
@@ -144,15 +83,6 @@ def _raise_for_status(resp: Any, *, run_id: str) -> None:
     resp.raise_for_status()
 
 
-def _is_safe_release_conflict(resp: Any) -> bool:
-    try:
-        payload = resp.json()
-    except Exception:
-        return False
-    detail = payload.get("detail") if isinstance(payload, dict) else None
-    return isinstance(detail, str) and "is not claimed" in detail.lower()
-
-
 def _query_params(values: dict[str, Any]) -> list[tuple[str, str | int | float | bool | None]]:
     params: list[tuple[str, str | int | float | bool | None]] = []
     for key, value in values.items():
@@ -191,20 +121,6 @@ def _raise_or_warn(operation: str, suppress_errors: bool, exc: Exception) -> Non
     logger.warning("Failed to %s with GridFleet: %s", operation, exc)
 
 
-def _parse_next_available_delay(next_available_at: str | None) -> int | None:
-    if not next_available_at:
-        return None
-    value = next_available_at.replace("Z", "+00:00")
-    try:
-        parsed = datetime.fromisoformat(value)
-    except ValueError:
-        return None
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=timezone.utc)
-    delay = int(parsed.timestamp() - time.time())
-    return max(1, delay) if delay > 0 else 1
-
-
 class HeartbeatThread(threading.Thread):
     """Background thread that sends periodic heartbeat pings for an active test run."""
 
@@ -313,19 +229,20 @@ class GridFleetClient:
         resp.raise_for_status()
         return cast("dict[str, Any]", resp.json())
 
-    def resolve_device_id_by_connection_target(self, connection_target: str) -> str:
-        """Look up the backend device id for a runtime connection target."""
+    def get_device_by_connection_target(self, target: str) -> dict[str, Any]:
+        """Fetch one device detail row by runtime connection target."""
         resp = httpx.get(
-            f"{self.base_url}/devices",
-            params={"connection_target": connection_target},
+            f"{self.base_url}/devices/by-connection-target/{quote(target, safe='')}",
             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}")
-        return cast("str", devices[0]["id"])
+        return cast("dict[str, Any]", resp.json())
+
+    def resolve_device_id_by_connection_target(self, connection_target: str) -> str:
+        """Look up the backend device id for a runtime connection target."""
+        device = self.get_device_by_connection_target(connection_target)
+        return cast("str", device["id"])
 
     def get_device_config(self, connection_target: str) -> dict[str, Any]:
         """Fetch device config by looking up the current runtime connection target."""
@@ -403,9 +320,7 @@ class GridFleetClient:
         """Reserve devices for a test run and return the manager response."""
         include_tuple = _normalize_include(include)
         if include_tuple is not None and "capabilities" in include_tuple:
-            raise ReserveCapabilitiesUnsupportedError(
-                "include='capabilities' is not supported on reserve; use include on claim_device instead"
-            )
+            raise ReserveCapabilitiesUnsupportedError("include='capabilities' is not supported on reserve")
         resp = httpx.post(
             f"{self.base_url}/runs",
             json={
@@ -449,89 +364,6 @@ class GridFleetClient:
         resp.raise_for_status()
         return cast("dict[str, Any]", resp.json())
 
-    def claim_device(
-        self,
-        run_id: str,
-        *,
-        worker_id: str,
-        include: Sequence[str] | None = None,
-    ) -> dict[str, Any]:
-        include_tuple = _normalize_include(include)
-        resp = httpx.post(
-            f"{self.base_url}/runs/{run_id}/claim",
-            json={"worker_id": worker_id},
-            params=_include_param(include_tuple),
-            timeout=10,
-            auth=self._auth,
-        )
-        _raise_for_status(resp, run_id=run_id)
-        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 release_device_safe(self, run_id: str, *, device_id: str, worker_id: str) -> bool:
-        """Release a claim while tolerating already-terminal run/device states.
-
-        Returns True when the manager accepts the release, False when the run is
-        gone or the claim is explicitly already unclaimed. Other HTTP errors,
-        including wrong-worker conflicts, still raise.
-        """
-        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,
-        )
-        if resp.status_code == 404 or (resp.status_code == 409 and _is_safe_release_conflict(resp)):
-            return False
-        resp.raise_for_status()
-        return True
-
-    def release_device_with_cooldown(
-        self,
-        run_id: str,
-        *,
-        device_id: str,
-        worker_id: str,
-        reason: str,
-        ttl_seconds: int,
-    ) -> CooldownResult:
-        resp = httpx.post(
-            f"{self.base_url}/runs/{run_id}/devices/{device_id}/release-with-cooldown",
-            json={"worker_id": worker_id, "reason": reason, "ttl_seconds": ttl_seconds},
-            timeout=10,
-            auth=self._auth,
-        )
-        resp.raise_for_status()
-        return cast("CooldownResult", resp.json())
-
-    def claim_device_with_retry(
-        self,
-        run_id: str,
-        *,
-        worker_id: str,
-        max_wait_sec: int = 300,
-        include: Sequence[str] | None = None,
-    ) -> dict[str, Any]:
-        deadline = time.monotonic() + max_wait_sec
-        include_tuple = _normalize_include(include)
-        while True:
-            try:
-                return self.claim_device(run_id, worker_id=worker_id, include=include_tuple)
-            except NoClaimableDevicesError as exc:
-                remaining = deadline - time.monotonic()
-                if remaining <= 0:
-                    raise
-                sleep_for = _parse_next_available_delay(exc.next_available_at) or exc.retry_after_sec
-                time.sleep(min(sleep_for, max(1, int(remaining))))
-
     def report_preparation_failure(
         self,
         run_id: str,
@@ -600,6 +432,27 @@ class GridFleetClient:
             return None
         return cast("dict[str, Any]", resp.json())
 
+    def notify_session_finished(
+        self,
+        session_id: str,
+        *,
+        suppress_errors: bool = True,
+    ) -> None:
+        """Tell the manager the WebDriver session has ended.
+
+        Idempotent on the backend — repeated calls are a no-op once the
+        Session row is marked ended.
+        """
+        try:
+            resp = httpx.post(
+                f"{self.base_url}/sessions/{session_id}/finished",
+                timeout=5,
+                auth=self._auth,
+            )
+            resp.raise_for_status()
+        except (httpx.HTTPError, TypeError, ValueError) as exc:
+            _raise_or_warn("notify session finished", suppress_errors, exc)
+
     def update_session_status(
         self,
         session_id: str,
@@ -629,7 +482,12 @@ class GridFleetClient:
         run_id: str | None = None,
         suppress_errors: bool = True,
     ) -> dict[str, Any] | None:
-        """Extract session metadata from an Appium driver and register it."""
+        """Extract session metadata from an Appium driver and register it.
+
+        Also wraps ``driver.quit`` so that the first call after a successful
+        registration fires :meth:`notify_session_finished` automatically.
+        Errors from notify are suppressed — they must never break the caller.
+        """
         capabilities = getattr(driver, "capabilities", {})
         if not isinstance(capabilities, dict):
             capabilities = {}
@@ -638,7 +496,7 @@ class GridFleetClient:
             raise RuntimeError("Created Appium driver did not expose a session ID")
         device_id = capabilities.get("appium:gridfleet:deviceId") or capabilities.get("gridfleet:deviceId")
         connection_target = capabilities.get("appium:udid") or capabilities.get("appium:deviceName")
-        return self.register_session(
+        result = self.register_session(
             session_id=session_id,
             test_name=test_name,
             device_id=device_id if isinstance(device_id, str) and device_id else None,
@@ -647,6 +505,31 @@ class GridFleetClient:
             run_id=run_id,
             suppress_errors=suppress_errors,
         )
+        self._wrap_quit_for_notify(driver, session_id)
+        return result
+
+    def _wrap_quit_for_notify(self, driver: Any, session_id: str) -> None:
+        """Replace ``driver.quit`` with a wrapper that also notifies the manager.
+
+        The notify fires at most once per registration: after the first quit
+        succeeds, subsequent quit() calls run the underlying quit but do
+        NOT post to /finished again. The underlying quit still runs every
+        call.
+
+        Raises AttributeError if the driver lacks a quit method.
+        """
+        original_quit = driver.quit
+        notified: dict[str, bool] = {"done": False}
+
+        def wrapped_quit(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return original_quit(*args, **kwargs)
+            finally:
+                if not notified["done"]:
+                    notified["done"] = True
+                    self.notify_session_finished(session_id, suppress_errors=True)
+
+        driver.quit = wrapped_quit
 
     def complete_run(self, run_id: str) -> dict[str, Any]:
         resp = httpx.post(

{gridfleet_testkit-0.5.0 → gridfleet_testkit-0.7.0}/gridfleet_testkit/pytest_plugin.py

@@ -13,7 +13,7 @@ from .appium import (
     get_device_test_data_for_driver,
 )
 from .client import GridFleetClient, _default_grid_url
-from .sessions import build_error_session_payload
+from .sessions import build_error_session_payload, resolve_device_handle_from_driver
 
 if TYPE_CHECKING:
     from collections.abc import Generator
@@ -147,6 +147,16 @@ def device_test_data(appium_driver: Any, gridfleet_client: GridFleetClient) -> d
         raise RuntimeError("unreachable: pytest.skip did not raise") from exc
 
 
+@pytest.fixture
+def device_handle(appium_driver: Any, gridfleet_client: GridFleetClient) -> dict[str, Any]:
+    """Fetch the canonical manager device row after Grid assigns a runtime target."""
+    try:
+        return resolve_device_handle_from_driver(appium_driver, client=gridfleet_client)
+    except RuntimeError as exc:
+        pytest.skip(str(exc))
+        raise RuntimeError("unreachable: pytest.skip did not raise") from exc
+
+
 def _gridfleet_worker_id(request: pytest.FixtureRequest) -> str:
     """Return pytest-xdist worker id, or controller for non-worker processes."""
     workerinput = getattr(request.config, "workerinput", None)

{gridfleet_testkit-0.5.0 → gridfleet_testkit-0.7.0}/gridfleet_testkit/sessions.py

@@ -2,9 +2,12 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-__all__ = ["build_error_session_payload"]
+if TYPE_CHECKING:
+    from .client import GridFleetClient
+
+__all__ = ["build_error_session_payload", "resolve_device_handle_from_driver"]
 
 _KNOWN_DEVICE_TYPES = {"real_device", "emulator", "simulator"}
 _KNOWN_CONNECTION_TYPES = {"usb", "network", "virtual"}
@@ -74,3 +77,14 @@ def build_error_session_payload(
         "error_type": type(exc).__name__,
         "error_message": str(exc),
     }
+
+
+def resolve_device_handle_from_driver(driver: Any, *, client: GridFleetClient) -> dict[str, Any]:
+    """Resolve a canonical device handle from a running WebDriver session."""
+    caps = getattr(driver, "capabilities", None) or {}
+    if not isinstance(caps, dict):
+        raise RuntimeError("driver capabilities missing appium:udid; cannot resolve device handle")
+    target = caps.get("appium:udid") or caps.get("appium:deviceName")
+    if not target:
+        raise RuntimeError("driver capabilities missing appium:udid; cannot resolve device handle")
+    return client.get_device_by_connection_target(str(target))

{gridfleet_testkit-0.5.0 → gridfleet_testkit-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gridfleet-testkit"
-version = "0.5.0"
+version = "0.7.0"
 description = "Supported pytest and run-orchestration helpers for GridFleet integrations"
 readme = "README.md"
 license = "Apache-2.0"