gridfleet-testkit 0.1.0__tar.gz → 0.2.0__tar.gz

gridfleet_testkit-0.2.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog — GridFleet Testkit
+
+All notable changes to the GridFleet testkit (`gridfleet-testkit` on PyPI) are documented here.
+
+## [0.2.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.1.0...gridfleet-testkit-v0.2.0) (2026-05-03)
+
+
+### Features
+
+* **testkit:** add run-scoped device cooldowns ([#54](https://github.com/quidow/gridfleet/issues/54)) ([6163dc9](https://github.com/quidow/gridfleet/commit/6163dc959334e933b43c20a99ad4edcbdae6c98b))
+
+
+### Bug Fixes
+
+* idempotent device release after lifecycle cleanup ([#12](https://github.com/quidow/gridfleet/issues/12)) ([7a98a5d](https://github.com/quidow/gridfleet/commit/7a98a5d18330150aab0a852f6b894d1d53de257c))
+
+## 0.1.0 — Initial Public Preview
+
+- Initial public preview of the GridFleet testkit.
+- Python pytest/Appium helper package with device reservation, capability injection, and session lifecycle fixtures.

{gridfleet_testkit-0.1.0 → gridfleet_testkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridfleet-testkit
-Version: 0.1.0
+Version: 0.2.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
@@ -165,6 +165,10 @@ finally:
 | `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.claim_device(run_id, worker_id=...)` | Claim one reserved device for a worker |
+| `GridFleetClient.claim_device_with_retry(run_id, worker_id=..., max_wait_sec=300)` | Claim one reserved device, sleeping according to server `Retry-After` responses |
+| `GridFleetClient.release_device(run_id, device_id=..., worker_id=...)` | Release a worker claim without cooldown |
+| `GridFleetClient.release_device_with_cooldown(run_id, device_id=..., worker_id=..., reason=..., ttl_seconds=...)` | Release a worker claim and keep that run from reclaiming the device until cooldown expires |
 | `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 |
@@ -215,6 +219,34 @@ 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"])`.
 
+### Worker Claim With Cooldown
+
+```python
+from gridfleet_testkit import GridFleetClient
+
+client = GridFleetClient("http://manager-ip:8000/api")
+
+claim = client.claim_device_with_retry(run_id, worker_id="gw0", max_wait_sec=300)
+device_id = claim["device_id"]
+
+try:
+    # Create the Appium session and run test setup for this worker.
+    ...
+except RuntimeError as exc:
+    client.release_device_with_cooldown(
+        run_id,
+        device_id=device_id,
+        worker_id="gw0",
+        reason=str(exc),
+        ttl_seconds=60,
+    )
+    raise
+else:
+    client.release_device(run_id, device_id=device_id, worker_id="gw0")
+```
+
+Cooldowns are scoped to the active run. They prevent the same run from reclaiming the device until `ttl_seconds` expires, but completing or cancelling the run releases the physical device normally.
+
 ## Examples
 
 Baseline screenshot examples:

{gridfleet_testkit-0.1.0 → gridfleet_testkit-0.2.0}/README.md

@@ -131,6 +131,10 @@ finally:
 | `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.claim_device(run_id, worker_id=...)` | Claim one reserved device for a worker |
+| `GridFleetClient.claim_device_with_retry(run_id, worker_id=..., max_wait_sec=300)` | Claim one reserved device, sleeping according to server `Retry-After` responses |
+| `GridFleetClient.release_device(run_id, device_id=..., worker_id=...)` | Release a worker claim without cooldown |
+| `GridFleetClient.release_device_with_cooldown(run_id, device_id=..., worker_id=..., reason=..., ttl_seconds=...)` | Release a worker claim and keep that run from reclaiming the device until cooldown expires |
 | `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 |
@@ -181,6 +185,34 @@ 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"])`.
 
+### Worker Claim With Cooldown
+
+```python
+from gridfleet_testkit import GridFleetClient
+
+client = GridFleetClient("http://manager-ip:8000/api")
+
+claim = client.claim_device_with_retry(run_id, worker_id="gw0", max_wait_sec=300)
+device_id = claim["device_id"]
+
+try:
+    # Create the Appium session and run test setup for this worker.
+    ...
+except RuntimeError as exc:
+    client.release_device_with_cooldown(
+        run_id,
+        device_id=device_id,
+        worker_id="gw0",
+        reason=str(exc),
+        ttl_seconds=60,
+    )
+    raise
+else:
+    client.release_device(run_id, device_id=device_id, worker_id="gw0")
+```
+
+Cooldowns are scoped to the active run. They prevent the same run from reclaiming the device until `ttl_seconds` expires, but completing or cancelling the run releases the physical device normally.
+
 ## Examples
 
 Baseline screenshot examples:

{gridfleet_testkit-0.1.0 → gridfleet_testkit-0.2.0}/gridfleet_testkit/__init__.py

@@ -8,18 +8,26 @@ from .appium import (
     get_connection_target_from_driver,
     get_device_config_for_driver,
 )
-from .client import GRID_URL, GRIDFLEET_API_URL, GridFleetClient, HeartbeatThread, register_run_cleanup
+from .client import (
+    GRID_URL,
+    GRIDFLEET_API_URL,
+    GridFleetClient,
+    HeartbeatThread,
+    NoClaimableDevicesError,
+    register_run_cleanup,
+)
 
 try:
     __version__ = version("gridfleet-testkit")
 except PackageNotFoundError:
-    __version__ = "0.0.0"
+    __version__ = "0.2.0"
 
 __all__ = [
     "GRIDFLEET_API_URL",
     "GRID_URL",
     "GridFleetClient",
     "HeartbeatThread",
+    "NoClaimableDevicesError",
     "__version__",
     "build_appium_options",
     "create_appium_driver",

{gridfleet_testkit-0.1.0 → gridfleet_testkit-0.2.0}/gridfleet_testkit/client.py

@@ -8,6 +8,7 @@ import logging
 import os
 import signal
 import threading
+import time
 from typing import Any, cast
 
 import httpx
@@ -29,6 +30,43 @@ 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,
+        next_available_at: str | None = None,
+    ) -> None:
+        self.retry_after_sec = retry_after_sec
+        self.next_available_at = next_available_at
+        super().__init__(message)
+
+
+def _raise_for_status(resp: Any) -> 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"),
+                    retry_after_sec=retry_after,
+                    next_available_at=next_available_at if isinstance(next_available_at, str) else None,
+                )
+    resp.raise_for_status()
+
+
 class HeartbeatThread(threading.Thread):
     """Background thread that sends periodic heartbeat pings for an active test run."""
 
@@ -173,7 +211,7 @@ class GridFleetClient:
             timeout=10,
             auth=self._auth,
         )
-        resp.raise_for_status()
+        _raise_for_status(resp)
         return cast("dict[str, Any]", resp.json())
 
     def release_device(self, run_id: str, *, device_id: str, worker_id: str) -> None:
@@ -185,6 +223,41 @@ class GridFleetClient:
         )
         resp.raise_for_status()
 
+    def release_device_with_cooldown(
+        self,
+        run_id: str,
+        *,
+        device_id: str,
+        worker_id: str,
+        reason: str,
+        ttl_seconds: int,
+    ) -> dict[str, Any]:
+        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("dict[str, Any]", resp.json())
+
+    def claim_device_with_retry(
+        self,
+        run_id: str,
+        *,
+        worker_id: str,
+        max_wait_sec: int = 300,
+    ) -> dict[str, Any]:
+        deadline = time.monotonic() + max_wait_sec
+        while True:
+            try:
+                return self.claim_device(run_id, worker_id=worker_id)
+            except NoClaimableDevicesError as exc:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise
+                time.sleep(min(exc.retry_after_sec, max(1, int(remaining))))
+
     def report_preparation_failure(
         self,
         run_id: str,

{gridfleet_testkit-0.1.0 → gridfleet_testkit-0.2.0}/pyproject.toml

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

{gridfleet_testkit-0.1.0 → gridfleet_testkit-0.2.0}/tests/test_client.py

@@ -9,6 +9,7 @@ import pytest
 from gridfleet_testkit.client import (
     GridFleetClient,
     HeartbeatThread,
+    NoClaimableDevicesError,
     _default_auth,
     register_run_cleanup,
 )
@@ -256,6 +257,84 @@ def test_claim_device_calls_api(monkeypatch):
     }
 
 
+def test_claim_device_raises_no_claimable_devices_with_retry_metadata(monkeypatch):
+    def fake_post(
+        url: str,
+        *,
+        json: dict[str, Any],
+        timeout: int,
+        auth: Any = None,
+    ) -> DummyResponse:
+        return DummyResponse(
+            {
+                "error": {
+                    "code": "CONFLICT",
+                    "message": "No unclaimed devices available in this run",
+                    "request_id": "req-1",
+                    "details": {
+                        "error": "no_claimable_devices",
+                        "retry_after_sec": 7,
+                        "next_available_at": "2026-05-03T20:00:00Z",
+                    },
+                }
+            },
+            status_code=409,
+        )
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+
+    client = GridFleetClient("http://manager/api")
+    with pytest.raises(NoClaimableDevicesError) as exc_info:
+        client.claim_device("run-123", worker_id="gw0")
+
+    assert exc_info.value.retry_after_sec == 7
+    assert exc_info.value.next_available_at == "2026-05-03T20:00:00Z"
+
+
+def test_claim_device_with_retry_sleeps_and_retries(monkeypatch):
+    calls: list[str] = []
+    sleeps: list[int] = []
+    responses = iter(
+        [
+            DummyResponse(
+                {
+                    "error": {
+                        "code": "CONFLICT",
+                        "message": "No unclaimed devices available in this run",
+                        "request_id": "req-1",
+                        "details": {"error": "no_claimable_devices", "retry_after_sec": 2, "next_available_at": None},
+                    }
+                },
+                status_code=409,
+            ),
+            DummyResponse({"device_id": "dev-1", "claimed_by": "gw0", "claimed_at": "2026-05-03T20:00:00Z"}),
+        ]
+    )
+
+    def fake_post(
+        url: str,
+        *,
+        json: dict[str, Any],
+        timeout: int,
+        auth: Any = None,
+    ) -> DummyResponse:
+        calls.append(url)
+        return next(responses)
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+    monkeypatch.setattr("gridfleet_testkit.client.time.sleep", lambda seconds: sleeps.append(seconds))
+
+    client = GridFleetClient("http://manager/api")
+    result = client.claim_device_with_retry("run-123", worker_id="gw0", max_wait_sec=5)
+
+    assert result["device_id"] == "dev-1"
+    assert sleeps == [2]
+    assert calls == [
+        "http://manager/api/runs/run-123/claim",
+        "http://manager/api/runs/run-123/claim",
+    ]
+
+
 def test_release_device_calls_api(monkeypatch):
     recorded: dict[str, Any] = {}
 
@@ -283,6 +362,40 @@ def test_release_device_calls_api(monkeypatch):
     }
 
 
+def test_release_device_with_cooldown_calls_api(monkeypatch):
+    recorded: dict[str, Any] = {}
+
+    def fake_post(
+        url: str,
+        *,
+        json: dict[str, Any],
+        timeout: int,
+        auth: Any = None,
+    ) -> DummyResponse:
+        recorded["url"] = url
+        recorded["json"] = json
+        recorded["timeout"] = timeout
+        return DummyResponse({"status": "cooldown_set", "excluded_until": "2026-05-03T20:00:00Z"})
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+
+    client = GridFleetClient("http://manager/api")
+    result = client.release_device_with_cooldown(
+        "run-123",
+        device_id="dev-1",
+        worker_id="gw0",
+        reason="appium launch timeout",
+        ttl_seconds=60,
+    )
+
+    assert result["status"] == "cooldown_set"
+    assert recorded == {
+        "url": "http://manager/api/runs/run-123/devices/dev-1/release-with-cooldown",
+        "json": {"worker_id": "gw0", "reason": "appium launch timeout", "ttl_seconds": 60},
+        "timeout": 10,
+    }
+
+
 def test_release_device_raises_for_conflict(monkeypatch):
     def fake_post(
         url: str,

{gridfleet_testkit-0.1.0 → gridfleet_testkit-0.2.0}/uv.lock

@@ -102,7 +102,7 @@ wheels = [
 
 [[package]]
 name = "gridfleet-testkit"
-version = "0.1.0"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },