gridfleet-testkit 0.3.0__tar.gz → 0.4.0__tar.gz

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.4.0}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to the GridFleet testkit (`gridfleet-testkit` on PyPI) are documented here.
 
+## [0.4.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.3.0...gridfleet-testkit-v0.4.0) (2026-05-06)
+
+
+### Features
+
+* **testkit:** wire ?include=config,capabilities through claim/reserve and hydrate inline ([#95](https://github.com/quidow/gridfleet/issues/95)) ([20ed20d](https://github.com/quidow/gridfleet/commit/20ed20d9ee362890923146e771ad8805b45e5bfa))
+
 ## [0.3.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.2.1...gridfleet-testkit-v0.3.0) (2026-05-05)
 
 

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridfleet-testkit
-Version: 0.3.0
+Version: 0.4.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
@@ -280,6 +280,25 @@ assert allocated.platform_name in {"Android", "iOS", "tvOS", "Roku"}
 
 The helper fetches static device config by default when `connection_target` is present. It fetches live capabilities only when `fetch_capabilities=True`.
 
+### Reduced HTTP round-trips on claim
+
+`gridfleet-testkit` 0.4.0 lets the manager inline the device config and live capabilities into the claim/reserve response, eliminating per-worker follow-up GETs.
+
+```python
+client = GridFleetClient()
+claim = client.claim_device(run_id, worker_id="w0", include=("config", "capabilities"))
+allocated = hydrate_allocated_device(claim, run_id=run_id, client=client)
+# zero follow-up GETs; allocated.config / allocated.live_capabilities populated inline
+```
+
+**Masking change**: inline `config` is always masked — sensitive values are replaced with `"********"`. Use `client.get_device_config(connection_target, reveal=True)` if you need raw secrets after the driver session is up. `allocated.config_is_masked` is `True` whenever the inline path was taken.
+
+`reserve_devices` accepts `include=("config",)` only — `include=("capabilities",)` raises `ReserveCapabilitiesUnsupportedError` client-side because reserve-time capabilities are not yet device-bound. Pass `include=` on the per-worker `claim_device` call instead.
+
+`include=` must be a sequence of strings (tuple or list) — order is preserved in the emitted query parameter. Passing a bare string like `include="config"` raises `TypeError` to avoid silently splitting the value into characters.
+
+`hydrate_allocated_device` accepts claim responses only. For multi-device reservations, iterate `reserve_response["devices"]`, call `claim_device` per worker, and hydrate each claim response.
+
 ## Examples
 
 Baseline screenshot examples:

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.4.0}/README.md

@@ -246,6 +246,25 @@ assert allocated.platform_name in {"Android", "iOS", "tvOS", "Roku"}
 
 The helper fetches static device config by default when `connection_target` is present. It fetches live capabilities only when `fetch_capabilities=True`.
 
+### Reduced HTTP round-trips on claim
+
+`gridfleet-testkit` 0.4.0 lets the manager inline the device config and live capabilities into the claim/reserve response, eliminating per-worker follow-up GETs.
+
+```python
+client = GridFleetClient()
+claim = client.claim_device(run_id, worker_id="w0", include=("config", "capabilities"))
+allocated = hydrate_allocated_device(claim, run_id=run_id, client=client)
+# zero follow-up GETs; allocated.config / allocated.live_capabilities populated inline
+```
+
+**Masking change**: inline `config` is always masked — sensitive values are replaced with `"********"`. Use `client.get_device_config(connection_target, reveal=True)` if you need raw secrets after the driver session is up. `allocated.config_is_masked` is `True` whenever the inline path was taken.
+
+`reserve_devices` accepts `include=("config",)` only — `include=("capabilities",)` raises `ReserveCapabilitiesUnsupportedError` client-side because reserve-time capabilities are not yet device-bound. Pass `include=` on the per-worker `claim_device` call instead.
+
+`include=` must be a sequence of strings (tuple or list) — order is preserved in the emitted query parameter. Passing a bare string like `include="config"` raises `TypeError` to avoid silently splitting the value into characters.
+
+`hydrate_allocated_device` accepts claim responses only. For multi-device reservations, iterate `reserve_response["devices"]`, call `claim_device` per worker, and hydrate each claim response.
+
 ## Examples
 
 Baseline screenshot examples:

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.4.0}/gridfleet_testkit/__init__.py

@@ -1,5 +1,12 @@
 """Supported Python integration helpers for GridFleet.
 
+**0.4.0 masking change**: when callers opt in to inline `config` via
+`claim_device(include=("config",))`, the inline `config` payload is **always
+masked** (sensitive values are replaced with `"********"`). Code that needs raw
+secrets must continue to call `client.get_device_config(connection_target,
+reveal=True)` explicitly. `AllocatedDevice.config_is_masked` is `True` whenever
+the inline path was taken.
+
 Environment variables read by the client:
 
 - GRID_URL: Selenium Grid URL used by Appium helper defaults.
@@ -13,7 +20,12 @@ this package because run-state sharing is consumer policy.
 
 from importlib.metadata import PackageNotFoundError, version
 
-from .allocation import AllocatedDevice, hydrate_allocated_device, hydrate_allocated_device_from_driver
+from .allocation import (
+    AllocatedDevice,
+    UnavailableInclude,
+    hydrate_allocated_device,
+    hydrate_allocated_device_from_driver,
+)
 from .appium import (
     build_appium_options,
     create_appium_driver,
@@ -26,6 +38,8 @@ from .client import (
     GridFleetClient,
     HeartbeatThread,
     NoClaimableDevicesError,
+    ReserveCapabilitiesUnsupportedError,
+    UnknownIncludeError,
     register_run_cleanup,
 )
 from .sessions import build_error_session_payload
@@ -33,7 +47,7 @@ from .sessions import build_error_session_payload
 try:
     __version__ = version("gridfleet-testkit")
 except PackageNotFoundError:
-    __version__ = "0.3.0"
+    __version__ = "0.4.0"
 
 __all__ = [
     "GRIDFLEET_API_URL",
@@ -42,6 +56,9 @@ __all__ = [
     "GridFleetClient",
     "HeartbeatThread",
     "NoClaimableDevicesError",
+    "ReserveCapabilitiesUnsupportedError",
+    "UnavailableInclude",
+    "UnknownIncludeError",
     "__version__",
     "build_appium_options",
     "build_error_session_payload",

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.4.0}/gridfleet_testkit/allocation.py

@@ -9,6 +9,14 @@ if TYPE_CHECKING:
     from .client import GridFleetClient
 
 
+@dataclass(frozen=True)
+class UnavailableInclude:
+    """One include key the backend could not satisfy on this allocation."""
+
+    include: str
+    reason: str
+
+
 @dataclass(frozen=True)
 class AllocatedDevice:
     """Combined view of a claimed device, ready for driver creation."""
@@ -31,6 +39,8 @@ class AllocatedDevice:
     claimed_at: str
     config: dict[str, Any] | None
     live_capabilities: dict[str, Any] | None
+    unavailable_includes: tuple[UnavailableInclude, ...] = ()
+    config_is_masked: bool = False
 
     @property
     def is_real_device(self) -> bool:
@@ -89,6 +99,21 @@ def _merge_device_detail(payload: dict[str, Any], detail: dict[str, Any]) -> dic
     return merged
 
 
+def _parse_unavailable_includes(payload: dict[str, Any]) -> tuple[UnavailableInclude, ...]:
+    raw = payload.get("unavailable_includes")
+    if not isinstance(raw, list):
+        return ()
+    parsed: list[UnavailableInclude] = []
+    for entry in raw:
+        if not isinstance(entry, dict):
+            continue
+        include = entry.get("include")
+        reason = entry.get("reason")
+        if isinstance(include, str) and include and isinstance(reason, str) and reason:
+            parsed.append(UnavailableInclude(include=include, reason=reason))
+    return tuple(parsed)
+
+
 def hydrate_allocated_device(
     claim_response: dict[str, Any],
     *,
@@ -97,15 +122,40 @@ def hydrate_allocated_device(
     fetch_config: bool = True,
     fetch_capabilities: bool = False,
 ) -> AllocatedDevice:
-    """Combine a claim response with optional static config and live capabilities."""
+    """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)
     device_id = _string_value(payload, "device_id")
     if _needs_device_detail(payload):
         payload = _merge_device_detail(payload, client.get_device(device_id))
 
+    unavailable_includes = _parse_unavailable_includes(payload)
+    unavailable_set = {entry.include for entry in unavailable_includes}
+
     connection_target = _optional_string_value(payload, "connection_target")
-    config = client.get_device_config(connection_target) if fetch_config and connection_target else None
-    live_capabilities = client.get_device_capabilities(device_id) if fetch_capabilities else None
+    inline_config = payload.get("config")
+    if isinstance(inline_config, dict):
+        config: dict[str, Any] | None = inline_config
+        config_is_masked = True
+    elif fetch_config and connection_target and "config" not in unavailable_set:
+        config = client.get_device_config(connection_target)
+        config_is_masked = False
+    else:
+        config = None
+        config_is_masked = False
+    inline_capabilities = payload.get("live_capabilities")
+    if isinstance(inline_capabilities, dict):
+        live_capabilities: dict[str, Any] | None = inline_capabilities
+    elif fetch_capabilities and "capabilities" not in unavailable_set:
+        live_capabilities = client.get_device_capabilities(device_id)
+    else:
+        live_capabilities = None
 
     return AllocatedDevice(
         run_id=run_id,
@@ -125,7 +175,9 @@ def hydrate_allocated_device(
         claimed_by=_string_value(payload, "claimed_by"),
         claimed_at=_string_value(payload, "claimed_at"),
         config=config,
+        config_is_masked=config_is_masked,
         live_capabilities=live_capabilities,
+        unavailable_includes=unavailable_includes,
     )
 
 

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.4.0}/gridfleet_testkit/client.py

@@ -9,7 +9,10 @@ import os
 import signal
 import threading
 import time
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
 
 import httpx
 
@@ -47,6 +50,21 @@ class NoClaimableDevicesError(RuntimeError):
         super().__init__(message)
 
 
+class UnknownIncludeError(ValueError):
+    """Backend rejected one or more `?include=` keys."""
+
+    def __init__(self, values: list[str]) -> None:
+        super().__init__(f"Backend rejected unknown include values: {values}")
+        self.values = values
+
+
+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")
+
+
 def _raise_for_status(resp: Any, *, run_id: str) -> None:
     if resp.status_code == 409:
         try:
@@ -67,6 +85,21 @@ def _raise_for_status(resp: Any, *, run_id: str) -> None:
                     retry_after_sec=retry_after,
                     next_available_at=next_available_at if isinstance(next_available_at, str) else None,
                 )
+    if resp.status_code == 422:
+        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):
+                code = details.get("code")
+                if code == "unknown_include":
+                    values = details.get("values")
+                    raise UnknownIncludeError(values if isinstance(values, list) else [])
+                if code == "reserve_capabilities_unsupported":
+                    raise ReserveCapabilitiesUnsupportedError(str(error.get("message") or ""))
     resp.raise_for_status()
 
 
@@ -91,6 +124,26 @@ def _query_params(values: dict[str, Any]) -> list[tuple[str, str | int | float |
     return params
 
 
+def _normalize_include(include: Sequence[str] | None) -> tuple[str, ...] | None:
+    if include is None:
+        return None
+    if isinstance(include, (str, bytes)):
+        raise TypeError(
+            "include must be a sequence of strings, not a string itself "
+            "(e.g. include=('config',), not include='config')"
+        )
+    return tuple(include)
+
+
+def _include_param(include: tuple[str, ...] | None) -> list[tuple[str, str | int | float | bool | None]] | None:
+    if include is None:
+        return None
+    values = [v for v in include if v]
+    if not values:
+        return None
+    return [("include", ",".join(values))]
+
+
 def _raise_or_warn(operation: str, suppress_errors: bool, exc: Exception) -> None:
     if not suppress_errors:
         raise exc
@@ -254,8 +307,15 @@ class GridFleetClient:
         ttl_minutes: int = 60,
         heartbeat_timeout_sec: int = 120,
         created_by: str | None = None,
+        *,
+        include: Sequence[str] | None = None,
     ) -> dict[str, Any]:
         """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"
+            )
         resp = httpx.post(
             f"{self.base_url}/runs",
             json={
@@ -265,10 +325,11 @@ class GridFleetClient:
                 "heartbeat_timeout_sec": heartbeat_timeout_sec,
                 "created_by": created_by,
             },
+            params=_include_param(include_tuple),
             timeout=30,
             auth=self._auth,
         )
-        resp.raise_for_status()
+        _raise_for_status(resp, run_id="")
         return cast("dict[str, Any]", resp.json())
 
     def signal_ready(self, run_id: str) -> None:
@@ -294,10 +355,18 @@ class GridFleetClient:
         resp.raise_for_status()
         return cast("dict[str, Any]", resp.json())
 
-    def claim_device(self, run_id: str, *, worker_id: str) -> dict[str, Any]:
+    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,
         )
@@ -355,11 +424,13 @@ class GridFleetClient:
         *,
         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)
+                return self.claim_device(run_id, worker_id=worker_id, include=include_tuple)
             except NoClaimableDevicesError as exc:
                 remaining = deadline - time.monotonic()
                 if remaining <= 0:

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.4.0}/pyproject.toml

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

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.4.0}/tests/test_allocation.py

@@ -6,6 +6,7 @@ import pytest
 
 from gridfleet_testkit.allocation import (
     AllocatedDevice,
+    UnavailableInclude,
     hydrate_allocated_device,
     hydrate_allocated_device_from_driver,
 )
@@ -163,6 +164,160 @@ def test_allocated_device_properties_prefer_stable_sources() -> None:
     assert allocated.platform_name == "Android"
 
 
+def test_allocated_device_defaults_unavailable_includes_and_config_is_masked() -> None:
+    allocated = AllocatedDevice(
+        run_id="run-1",
+        device_id="dev-1",
+        identity_value="SERIAL123",
+        name="Pixel 6",
+        pack_id="appium-uiautomator2",
+        platform_id="android_mobile",
+        platform_label="Android",
+        os_version="14",
+        connection_target="SERIAL123",
+        host_ip="192.168.1.10",
+        device_type="real_device",
+        connection_type="usb",
+        manufacturer="Google",
+        model="Pixel 6",
+        claimed_by="gw0",
+        claimed_at="2026-05-05T10:00:00Z",
+        config=None,
+        live_capabilities=None,
+    )
+
+    assert allocated.unavailable_includes == ()
+    assert isinstance(allocated.unavailable_includes, tuple)
+    assert all(isinstance(u, UnavailableInclude) for u in allocated.unavailable_includes)
+    assert allocated.config_is_masked is False
+
+
+def test_hydrate_allocated_device_uses_inline_config_and_skips_get() -> None:
+    client = FakeClient()
+    payload = claim_payload(config={"ip": "10.0.0.8", "username": "operator", "password": "********"})
+
+    allocated = hydrate_allocated_device(payload, run_id="run-1", client=client)
+
+    assert allocated.config == {"ip": "10.0.0.8", "username": "operator", "password": "********"}
+    assert allocated.config_is_masked is True
+    assert client.config_calls == []
+    assert client.device_calls == []
+
+
+def test_hydrate_allocated_device_falls_back_to_get_device_config_when_inline_absent() -> None:
+    client = FakeClient()
+
+    allocated = hydrate_allocated_device(claim_payload(), run_id="run-1", client=client)
+
+    assert allocated.config == {"ip": "10.0.0.8", "username": "operator"}
+    assert allocated.config_is_masked is False
+    assert client.config_calls == [("SERIAL123", True)]
+
+
+def test_hydrate_allocated_device_uses_inline_live_capabilities_and_skips_get() -> None:
+    client = FakeClient()
+    payload = claim_payload(live_capabilities={"appium:udid": "INLINE-CAP", "appium:deviceIP": "10.0.0.99"})
+
+    allocated = hydrate_allocated_device(payload, run_id="run-1", client=client, fetch_config=False)
+
+    assert allocated.live_capabilities == {"appium:udid": "INLINE-CAP", "appium:deviceIP": "10.0.0.99"}
+    assert client.capability_calls == []
+
+
+def test_hydrate_allocated_device_uses_inline_live_capabilities_even_when_fetch_capabilities_false() -> None:
+    client = FakeClient()
+    payload = claim_payload(live_capabilities={"appium:udid": "INLINE-CAP"})
+
+    allocated = hydrate_allocated_device(
+        payload,
+        run_id="run-1",
+        client=client,
+        fetch_config=False,
+        fetch_capabilities=False,
+    )
+
+    assert allocated.live_capabilities == {"appium:udid": "INLINE-CAP"}
+    assert client.capability_calls == []
+
+
+def test_hydrate_allocated_device_surfaces_unavailable_includes() -> None:
+    client = FakeClient()
+    payload = claim_payload(
+        unavailable_includes=[{"include": "capabilities", "reason": "device_offline"}],
+    )
+
+    allocated = hydrate_allocated_device(payload, run_id="run-1", client=client, fetch_config=False)
+
+    assert allocated.unavailable_includes == (UnavailableInclude(include="capabilities", reason="device_offline"),)
+
+
+def test_hydrate_allocated_device_unavailable_includes_defaults_to_empty_tuple() -> None:
+    client = FakeClient()
+
+    allocated = hydrate_allocated_device(claim_payload(), run_id="run-1", client=client, fetch_config=False)
+
+    assert allocated.unavailable_includes == ()
+
+
+def test_hydrate_allocated_device_skips_malformed_unavailable_include_entries() -> None:
+    client = FakeClient()
+    payload = claim_payload(
+        unavailable_includes=[
+            {"include": "capabilities", "reason": "device_offline"},
+            {"include": "config"},
+            "not-a-dict",
+            {"reason": "missing_include_key"},
+        ],
+    )
+
+    allocated = hydrate_allocated_device(payload, run_id="run-1", client=client, fetch_config=False)
+
+    assert allocated.unavailable_includes == (UnavailableInclude(include="capabilities", reason="device_offline"),)
+
+
+def test_hydrate_allocated_device_skips_config_fetch_when_marked_unavailable() -> None:
+    client = FakeClient()
+    payload = claim_payload(
+        unavailable_includes=[{"include": "config", "reason": "device_offline"}],
+    )
+
+    allocated = hydrate_allocated_device(payload, run_id="run-1", client=client)
+
+    assert allocated.config is None
+    assert allocated.config_is_masked is False
+    assert client.config_calls == []
+    assert allocated.unavailable_includes == (UnavailableInclude(include="config", reason="device_offline"),)
+
+
+def test_hydrate_allocated_device_skips_capabilities_fetch_when_marked_unavailable() -> None:
+    client = FakeClient()
+    payload = claim_payload(
+        unavailable_includes=[{"include": "capabilities", "reason": "device_offline"}],
+    )
+
+    allocated = hydrate_allocated_device(
+        payload,
+        run_id="run-1",
+        client=client,
+        fetch_config=False,
+        fetch_capabilities=True,
+    )
+
+    assert allocated.live_capabilities is None
+    assert client.capability_calls == []
+    assert allocated.unavailable_includes == (UnavailableInclude(include="capabilities", reason="device_offline"),)
+
+
+def test_hydrate_allocated_device_rejects_reserve_shaped_payload_without_claim_metadata() -> None:
+    client = FakeClient()
+    reserve_shaped = claim_payload()
+    del reserve_shaped["claimed_by"]
+    del reserve_shaped["claimed_at"]
+
+    with pytest.raises(ValueError, match="missing claimed_by"):
+        hydrate_allocated_device(reserve_shaped, run_id="run-1", client=client, fetch_config=False)
+
+
 def test_hydrate_allocated_device_from_driver_returns_new_frozen_instance() -> None:
     client = FakeClient()
     allocated = hydrate_allocated_device(claim_payload(), run_id="run-1", client=client, fetch_config=False)

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.4.0}/tests/test_client.py

@@ -10,7 +10,10 @@ from gridfleet_testkit.client import (
     GridFleetClient,
     HeartbeatThread,
     NoClaimableDevicesError,
+    ReserveCapabilitiesUnsupportedError,
+    UnknownIncludeError,
     _default_auth,
+    _raise_for_status,
     register_run_cleanup,
 )
 
@@ -211,6 +214,7 @@ def test_reserve_devices_posts_expected_payload(monkeypatch):
         *,
         json: dict[str, Any],
         timeout: int,
+        params: list[tuple[str, str]] | None = None,
         auth: Any = None,
     ) -> DummyResponse:
         recorded["url"] = url
@@ -251,6 +255,7 @@ def test_reserve_devices_all_available_payload(monkeypatch):
         *,
         json: dict[str, Any],
         timeout: int,
+        params: list[tuple[str, str]] | None = None,
         auth: Any = None,
     ) -> DummyResponse:
         recorded["url"] = url
@@ -332,6 +337,7 @@ def test_claim_device_calls_api(monkeypatch):
         *,
         json: dict[str, Any],
         timeout: int,
+        params: list[tuple[str, str]] | None = None,
         auth: Any = None,
     ) -> DummyResponse:
         recorded["url"] = url
@@ -359,6 +365,7 @@ def test_claim_device_raises_no_claimable_devices_with_retry_metadata(monkeypatc
         *,
         json: dict[str, Any],
         timeout: int,
+        params: list[tuple[str, str]] | None = None,
         auth: Any = None,
     ) -> DummyResponse:
         return DummyResponse(
@@ -420,6 +427,7 @@ def test_claim_device_with_retry_sleeps_and_retries(monkeypatch):
         *,
         json: dict[str, Any],
         timeout: int,
+        params: list[tuple[str, str]] | None = None,
         auth: Any = None,
     ) -> DummyResponse:
         calls.append(url)
@@ -908,6 +916,7 @@ def test_client_threads_default_auth_into_requests(monkeypatch):
         *,
         json: dict[str, Any],
         timeout: int,
+        params: list[tuple[str, str]] | None = None,
         auth: Any = None,
     ) -> DummyResponse:
         captured["auth"] = auth
@@ -932,6 +941,7 @@ def test_client_explicit_auth_overrides_env_default(monkeypatch):
         *,
         json: dict[str, Any],
         timeout: int,
+        params: list[tuple[str, str]] | None = None,
         auth: Any = None,
     ) -> DummyResponse:
         captured["auth"] = auth
@@ -969,3 +979,277 @@ def test_heartbeat_thread_passes_auth(monkeypatch):
 
     assert captured["url"] == "http://manager/api/runs/run-x/heartbeat"
     assert captured["auth"] is explicit
+
+
+def test_raise_for_status_maps_unknown_include_422_to_typed_exception():
+    resp = DummyResponse(
+        {
+            "error": {
+                "code": "INVALID_INCLUDE",
+                "message": "Unknown include values",
+                "details": {"code": "unknown_include", "values": ["garbage"]},
+            }
+        },
+        status_code=422,
+    )
+
+    with pytest.raises(UnknownIncludeError) as exc_info:
+        _raise_for_status(resp, run_id="run-1")
+
+    assert exc_info.value.values == ["garbage"]
+
+
+def test_raise_for_status_maps_reserve_capabilities_unsupported_422_to_typed_exception():
+    resp = DummyResponse(
+        {
+            "error": {
+                "code": "INVALID_INCLUDE",
+                "message": "include=capabilities not supported on reserve",
+                "details": {"code": "reserve_capabilities_unsupported"},
+            }
+        },
+        status_code=422,
+    )
+
+    with pytest.raises(ReserveCapabilitiesUnsupportedError):
+        _raise_for_status(resp, run_id="")
+
+
+def test_raise_for_status_passes_through_unrelated_422():
+    resp = DummyResponse({"detail": "validation"}, status_code=422)
+
+    with pytest.raises(httpx.HTTPStatusError):
+        _raise_for_status(resp, run_id="")
+
+
+def test_claim_device_threads_include_query_param(monkeypatch):
+    captured: dict[str, Any] = {}
+
+    def fake_post(
+        url: str,
+        *,
+        json: dict[str, Any],
+        timeout: int,
+        params: list[tuple[str, str]] | None = None,
+        auth: Any = None,
+    ) -> DummyResponse:
+        captured["url"] = url
+        captured["params"] = params
+        return DummyResponse({"device_id": "dev-1", "claimed_by": "gw0", "claimed_at": "2026-05-05T00:00:00Z"})
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+
+    client = GridFleetClient("http://manager/api")
+    client.claim_device("run-1", worker_id="gw0", include=("config", "capabilities"))
+
+    assert captured["params"] == [("include", "config,capabilities")]
+
+
+def test_claim_device_omits_include_param_when_unset(monkeypatch):
+    captured: dict[str, Any] = {}
+
+    def fake_post(
+        url: str,
+        *,
+        json: dict[str, Any],
+        timeout: int,
+        params: list[tuple[str, str]] | None = None,
+        auth: Any = None,
+    ) -> DummyResponse:
+        captured["params"] = params
+        return DummyResponse({"device_id": "dev-1", "claimed_by": "gw0", "claimed_at": "2026-05-05T00:00:00Z"})
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+
+    client = GridFleetClient("http://manager/api")
+    client.claim_device("run-1", worker_id="gw0")
+
+    assert captured["params"] is None or captured["params"] == []
+
+
+def test_claim_device_accepts_arbitrary_iterable_for_include(monkeypatch):
+    captured: dict[str, Any] = {}
+
+    def fake_post(
+        url: str,
+        *,
+        json: dict[str, Any],
+        timeout: int,
+        params: list[tuple[str, str]] | None = None,
+        auth: Any = None,
+    ) -> DummyResponse:
+        captured["params"] = params
+        return DummyResponse({"device_id": "dev-1", "claimed_by": "gw0", "claimed_at": "2026-05-05T00:00:00Z"})
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+
+    client = GridFleetClient("http://manager/api")
+    client.claim_device("run-1", worker_id="gw0", include=["config"])
+
+    assert captured["params"] == [("include", "config")]
+
+
+def test_claim_device_rejects_string_include_to_avoid_character_split():
+    client = GridFleetClient("http://manager/api")
+    with pytest.raises(TypeError, match="must be a sequence of strings"):
+        client.claim_device("run-1", worker_id="gw0", include="config")
+
+
+def test_claim_device_rejects_bytes_include():
+    client = GridFleetClient("http://manager/api")
+    with pytest.raises(TypeError, match="must be a sequence of strings"):
+        client.claim_device("run-1", worker_id="gw0", include=b"config")
+
+
+def test_claim_device_raises_unknown_include_on_422(monkeypatch):
+    def fake_post(
+        url: str,
+        *,
+        json: dict[str, Any],
+        timeout: int,
+        params: list[tuple[str, str]] | None = None,
+        auth: Any = None,
+    ) -> DummyResponse:
+        return DummyResponse(
+            {
+                "error": {
+                    "code": "INVALID_INCLUDE",
+                    "message": "Unknown include values",
+                    "details": {"code": "unknown_include", "values": ["garbage"]},
+                }
+            },
+            status_code=422,
+        )
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+
+    client = GridFleetClient("http://manager/api")
+    with pytest.raises(UnknownIncludeError) as exc_info:
+        client.claim_device("run-1", worker_id="gw0", include=("garbage",))
+
+    assert exc_info.value.values == ["garbage"]
+
+
+def test_claim_device_with_retry_forwards_include_on_every_attempt(monkeypatch):
+    seen: list[list[tuple[str, str]] | None] = []
+    responses = iter(
+        [
+            DummyResponse(
+                {
+                    "error": {
+                        "code": "CONFLICT",
+                        "message": "No unclaimed devices available in this run",
+                        "details": {"error": "no_claimable_devices", "retry_after_sec": 1, "next_available_at": None},
+                    }
+                },
+                status_code=409,
+            ),
+            DummyResponse({"device_id": "dev-1", "claimed_by": "gw0", "claimed_at": "2026-05-05T00:00:00Z"}),
+        ]
+    )
+
+    def fake_post(
+        url: str,
+        *,
+        json: dict[str, Any],
+        timeout: int,
+        params: list[tuple[str, str]] | None = None,
+        auth: Any = None,
+    ) -> DummyResponse:
+        seen.append(params)
+        return next(responses)
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+    monkeypatch.setattr("gridfleet_testkit.client.time.sleep", lambda _seconds: None)
+
+    client = GridFleetClient("http://manager/api")
+    client.claim_device_with_retry("run-1", worker_id="gw0", max_wait_sec=5, include=("config",))
+
+    assert seen == [
+        [("include", "config")],
+        [("include", "config")],
+    ]
+
+
+def test_reserve_devices_threads_include_query_param(monkeypatch):
+    captured: dict[str, Any] = {}
+
+    def fake_post(
+        url: str,
+        *,
+        json: dict[str, Any],
+        timeout: int,
+        params: list[tuple[str, str]] | None = None,
+        auth: Any = None,
+    ) -> DummyResponse:
+        captured["url"] = url
+        captured["params"] = params
+        return DummyResponse({"id": "run-1", "devices": []})
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+
+    client = GridFleetClient("http://manager/api")
+    client.reserve_devices(name="r", requirements=[], include=("config",))
+
+    assert captured["params"] == [("include", "config")]
+
+
+def test_reserve_devices_rejects_capabilities_include_before_http_call(monkeypatch):
+    called: list[str] = []
+
+    def fake_post(*args: Any, **kwargs: Any) -> DummyResponse:
+        called.append("post")
+        return DummyResponse({})
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+
+    client = GridFleetClient("http://manager/api")
+    with pytest.raises(ReserveCapabilitiesUnsupportedError):
+        client.reserve_devices(name="r", requirements=[], include=("config", "capabilities"))
+
+    assert called == []
+
+
+def test_reserve_devices_rejects_string_include_before_http_call(monkeypatch):
+    called: list[str] = []
+
+    def fake_post(*args: Any, **kwargs: Any) -> DummyResponse:
+        called.append("post")
+        return DummyResponse({})
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+
+    client = GridFleetClient("http://manager/api")
+    with pytest.raises(TypeError, match="must be a sequence of strings"):
+        client.reserve_devices(name="r", requirements=[], include="capabilities")
+
+    assert called == []
+
+
+def test_reserve_devices_raises_reserve_capabilities_unsupported_on_422(monkeypatch):
+    def fake_post(
+        url: str,
+        *,
+        json: dict[str, Any],
+        timeout: int,
+        params: list[tuple[str, str]] | None = None,
+        auth: Any = None,
+    ) -> DummyResponse:
+        return DummyResponse(
+            {
+                "error": {
+                    "code": "INVALID_INCLUDE",
+                    "message": "include=capabilities not supported on reserve",
+                    "details": {"code": "reserve_capabilities_unsupported"},
+                }
+            },
+            status_code=422,
+        )
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.post", fake_post)
+
+    client = GridFleetClient("http://manager/api")
+    # Use include=("config",) so the client-side guard does not fire.
+    # The 422 then exercises the defense-in-depth path through _raise_for_status.
+    with pytest.raises(ReserveCapabilitiesUnsupportedError):
+        client.reserve_devices(name="r", requirements=[], include=("config",))

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.4.0}/uv.lock

@@ -98,7 +98,7 @@ wheels = [
 
 [[package]]
 name = "gridfleet-testkit"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },