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

gridfleet_testkit-0.5.0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog — GridFleet Testkit
+
+All notable changes to the GridFleet testkit (`gridfleet-testkit` on PyPI) are documented here.
+
+## [0.5.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.4.0...gridfleet-testkit-v0.5.0) (2026-05-08)
+
+
+### ⚠ BREAKING CHANGES
+
+* remove device_config secret masking ([#104](https://github.com/quidow/gridfleet/issues/104))
+
+### Features
+
+* **backend:** escalate device to maintenance after N cooldowns in same run ([#121](https://github.com/quidow/gridfleet/issues/121)) ([7fe01f7](https://github.com/quidow/gridfleet/commit/7fe01f768ff70cd3ddb7f26aec1ab7210b49987f))
+* **main:** split device test_data from device_config + modal portal ([b5d0fa0](https://github.com/quidow/gridfleet/commit/b5d0fa09a862af742b3a2462667a86b1d3a867b6))
+* **testkit:** add allocated_device test_data and hydration ([e814e3d](https://github.com/quidow/gridfleet/commit/e814e3d0040b87a547ffc892ee2064305724d576))
+* **testkit:** add device_test_data pytest fixture ([51eeefc](https://github.com/quidow/gridfleet/commit/51eeefc522989e827610f2b1103d2ded0cadda89))
+* **testkit:** add gridfleetclient test_data methods ([b7f1124](https://github.com/quidow/gridfleet/commit/b7f1124e49618a7193ffc61f9db066f847d38522))
+* **testkit:** align public surface, fix run cleanup, lazy env reads ([#128](https://github.com/quidow/gridfleet/issues/128)) ([ee85958](https://github.com/quidow/gridfleet/commit/ee859581f84f77f43c2d0bb627eeeaef1e2a99db))
+
+
+### Dependencies
+
+* **deps:** bump appium-python-client in /testkit ([dc12591](https://github.com/quidow/gridfleet/commit/dc12591f5ebfba2361341132df546f6325750a61))
+
+
+### Documentation
+
+* **docs:** document discriminated-union release-with-cooldown response ([7fe01f7](https://github.com/quidow/gridfleet/commit/7fe01f768ff70cd3ddb7f26aec1ab7210b49987f))
+
+
+### Code Refactoring
+
+* remove device_config secret masking ([#104](https://github.com/quidow/gridfleet/issues/104)) ([7329a31](https://github.com/quidow/gridfleet/commit/7329a3107814f653b81b2753e519e271ec0dd8bd))
+
+## [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)
+
+
+### ⚠ BREAKING CHANGES
+
+* **testkit:** promote public api helpers ([#92](https://github.com/quidow/gridfleet/issues/92))
+
+### Features
+
+* **testkit:** add xdist recipe primitives ([#93](https://github.com/quidow/gridfleet/issues/93)) ([58fd3c3](https://github.com/quidow/gridfleet/commit/58fd3c3402ba7e735aae55e27abbe65a05c8ffe8))
+* **testkit:** promote public api helpers ([#92](https://github.com/quidow/gridfleet/issues/92)) ([80d4483](https://github.com/quidow/gridfleet/commit/80d44832903f532de3da238d020b5dc27eb8b30e))
+
+
+### Bug Fixes
+
+* **agent:** trigger release for port conflict cleanup ([6a561ca](https://github.com/quidow/gridfleet/commit/6a561ca480c62b9abb2d5141fa98fc4e1a7696b6))
+
+## [0.2.1](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.2.0...gridfleet-testkit-v0.2.1) (2026-05-03)
+
+
+### Bug Fixes
+
+* **testkit:** bound supported python metadata ([c5fff86](https://github.com/quidow/gridfleet/commit/c5fff86cbb2a4897ac571c7c5b989f0361e49743))
+
+## [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.3.0 → gridfleet_testkit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridfleet-testkit
-Version: 0.3.0
+Version: 0.5.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
@@ -27,7 +27,7 @@ Requires-Dist: pytest<10,>=9.0.3
 Provides-Extra: appium
 Requires-Dist: appium-python-client<6,>=4.5; extra == 'appium'
 Provides-Extra: dev
-Requires-Dist: mypy<2,>=1.20.2; extra == 'dev'
+Requires-Dist: mypy<3,>=1.20.2; extra == 'dev'
 Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
 Requires-Dist: ruff<1,>=0.15.12; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -40,14 +40,28 @@ Description-Content-Type: text/markdown
 
 - Stable import root: `gridfleet_testkit`
 - Supported pytest plugin: `gridfleet_testkit.pytest_plugin`
-- Supported public helpers:
+- Supported pytest fixtures: `appium_driver`, `gridfleet_client`, `device_config`, `device_test_data`, `gridfleet_worker_id`
+- Supported public Appium helpers:
   - `build_appium_options`
   - `create_appium_driver`
   - `get_connection_target_from_driver`
   - `get_device_config_for_driver`
+  - `get_device_test_data_for_driver`
+- Supported public client helpers:
   - `GridFleetClient`
   - `HeartbeatThread`
   - `register_run_cleanup`
+- Supported public allocation/session helpers:
+  - `AllocatedDevice`
+  - `UnavailableInclude`
+  - `CooldownResult`
+  - `build_error_session_payload`
+  - `hydrate_allocated_device`
+  - `hydrate_allocated_device_from_driver`
+- Supported public exceptions:
+  - `NoClaimableDevicesError`
+  - `UnknownIncludeError`
+  - `ReserveCapabilitiesUnsupportedError`
 - Manual hardware examples under `testkit/examples/`
 
 ## What It Does Not Own
@@ -134,8 +148,12 @@ If you need raw Appium control instead, omit `pack_id` and `platform_id`, then p
 - 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
+- Exposes `device_test_data` for post-session operator-attached test data using the runtime connection target
+- Exposes `gridfleet_worker_id` which returns the pytest-xdist worker id, or `"controller"` for non-worker processes
 - Relies on manager-owned runtime isolation for Appium driver sub-ports and XCUITest build paths
 
+If Appium driver creation fails before a Grid session exists, the pytest fixture registers a device-less terminal error session with an `error-<uuid>` session id, attempted capabilities, requested pack/platform metadata when available, and exception details, then re-raises the original exception. These rows make setup failures visible in the GridFleet Sessions view.
+
 ## Direct Appium Usage
 
 If you need to create a driver outside pytest, use the public Appium helpers:
@@ -162,15 +180,20 @@ finally:
 
 | Helper | Purpose |
 | --- | --- |
-| `GridFleetClient.list_devices(filters)` | List devices using backend filters such as `status`, `pack_id`, `platform_id`, `host_id`, `connection_target`, and `tags.*` |
+| `GridFleetClient.list_devices(*, pack_id=None, status=None, host_id=None, ...)` | List devices using backend keyword filters (pack_id, platform_id, status, host_id, connection_target, tags, ...) |
 | `GridFleetClient.get_device(device_id)` | Fetch one full device detail row by backend device id |
-| `GridFleetClient.get_device_config(connection_target, reveal=True)` | Look up a device by runtime connection target and fetch its config |
+| `GridFleetClient.get_device_config(connection_target)` | Look up a device by runtime connection target and fetch its config |
+| `GridFleetClient.get_device_capabilities(device_id)` | Fetch current Appium capability metadata for a device |
+| `GridFleetClient.get_device_test_data(device_id)` | Fetch operator-attached free-form test_data for a device |
+| `GridFleetClient.replace_device_test_data(device_id, body)` | Replace test_data with the supplied object |
+| `GridFleetClient.merge_device_test_data(device_id, body)` | Deep-merge into device test_data |
+| `GridFleetClient.resolve_device_id_by_connection_target(connection_target)` | Resolve the backend device id for a runtime connection target |
 | `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_safe(run_id, device_id=..., worker_id=...)` | Release a worker claim and tolerate 404/409 when cleanup races with run finalization or a prior release |
+| `GridFleetClient.release_device_safe(run_id, device_id=..., worker_id=...)` | Return `True` when release is accepted, `False` when the run is gone or the claim is already unclaimed, and raise on wrong-worker conflicts or unsafe errors |
 | `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` |
@@ -185,7 +208,8 @@ finally:
 | `build_error_session_payload(fields)` | Build a `/api/sessions` payload for driver-creation failures without importing pytest |
 | `hydrate_allocated_device(claim_response, run_id, client)` | Combine a claim response with optional device config and live capabilities |
 | `hydrate_allocated_device_from_driver(allocated, driver, client)` | Return a new allocated-device object with capabilities from a running driver |
-| `register_run_cleanup(client, run_id, heartbeat_thread=None)` | Register `atexit` and signal cleanup that completes or cancels a run |
+| `get_device_test_data_for_driver(driver, gridfleet_client=None)` | Fetch test_data for a live Appium driver |
+| `register_run_cleanup(client, run_id, heartbeat_thread=None)` | Register `atexit` cleanup callable and return it; stops the heartbeat thread on exit but does not complete or cancel the run by default |
 
 ### Worker Identity
 
@@ -216,7 +240,9 @@ run = client.reserve_devices(
 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)
+cleanup = register_run_cleanup(client, run_id, heartbeat_thread)
+# cleanup() runs at process exit; call client.complete_run(run_id) on success
+# or client.cancel_run(run_id) on failure to set the run state explicitly.
 
 # If one reserved device fails setup:
 client.report_preparation_failure(
@@ -278,7 +304,60 @@ assert allocated.device_id == claim["device_id"]
 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`.
+The helper fetches static device config by default when `connection_target` is present. It fetches live capabilities only when `fetch_capabilities=True`. Pass `fetch_test_data=True` to also populate `allocated.test_data`. The `test_data` field is also available directly from the claim response when the manager inlines it.
+
+### Run Cleanup Policy
+
+`register_run_cleanup(...)` registers an atexit cleanup callable and returns it. By default it stops the heartbeat thread but does not complete or cancel the run, because process exit alone does not prove test success. Prefer explicit `client.complete_run(run_id)` after successful orchestration and `client.cancel_run(run_id)` for known failures. Pass `on_exit="complete"` or `on_exit="cancel"` only when that policy is correct for your script. Signal handlers are opt-in with `install_signal_handlers=True`; signal cleanup defaults to cancellation.
+
+### Device Test Data
+
+The `device_test_data` fixture returns the operator-attached free-form test_data for the device assigned to the current test:
+
+```python
+def test_uses_operator_data(appium_driver, device_test_data):
+    assert "account" in device_test_data
+```
+
+Outside of pytest, use the client directly:
+
+```python
+test_data = client.get_device_test_data(device_id)
+```
+
+Or use the driver helper:
+
+```python
+from gridfleet_testkit import get_device_test_data_for_driver
+
+test_data = get_device_test_data_for_driver(driver)
+```
+
+### Errors and Result Types
+
+- `NoClaimableDevicesError(RuntimeError)`: raised when the manager reports no run devices are claimable yet. Exposes `run_id`, `retry_after_sec`, and `next_available_at`. The `RuntimeError` base is part of the contract — consumers can rely on it.
+- `UnknownIncludeError(ValueError)`: raised when the backend rejects one or more `?include=` keys. Exposes `values` with the rejected key names. The `ValueError` base is part of the contract.
+- `ReserveCapabilitiesUnsupportedError(ValueError)`: raised when a reserve-time `include` request contains `"capabilities"`, which is not supported at reserve time. The `ValueError` base is part of the contract.
+- `CooldownResult`: union response type from `release_device_with_cooldown`, with `status` equal to `"cooldown_set"` or `"maintenance_escalated"`. `CooldownSetResult` and `CooldownEscalatedResult` are the concrete TypedDict variants.
+
+### Reduced HTTP round-trips on claim
+
+The manager can inline 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
+```
+
+`device_config` and inline `config` payloads are returned verbatim from the manager. The testkit does not perform client-side secret masking or reveal toggles. Protect device config with manager authentication, operator access control, and your lab's secret-handling policy.
+
+`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
 

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

@@ -6,14 +6,28 @@
 
 - Stable import root: `gridfleet_testkit`
 - Supported pytest plugin: `gridfleet_testkit.pytest_plugin`
-- Supported public helpers:
+- Supported pytest fixtures: `appium_driver`, `gridfleet_client`, `device_config`, `device_test_data`, `gridfleet_worker_id`
+- Supported public Appium helpers:
   - `build_appium_options`
   - `create_appium_driver`
   - `get_connection_target_from_driver`
   - `get_device_config_for_driver`
+  - `get_device_test_data_for_driver`
+- Supported public client helpers:
   - `GridFleetClient`
   - `HeartbeatThread`
   - `register_run_cleanup`
+- Supported public allocation/session helpers:
+  - `AllocatedDevice`
+  - `UnavailableInclude`
+  - `CooldownResult`
+  - `build_error_session_payload`
+  - `hydrate_allocated_device`
+  - `hydrate_allocated_device_from_driver`
+- Supported public exceptions:
+  - `NoClaimableDevicesError`
+  - `UnknownIncludeError`
+  - `ReserveCapabilitiesUnsupportedError`
 - Manual hardware examples under `testkit/examples/`
 
 ## What It Does Not Own
@@ -100,8 +114,12 @@ If you need raw Appium control instead, omit `pack_id` and `platform_id`, then p
 - 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
+- Exposes `device_test_data` for post-session operator-attached test data using the runtime connection target
+- Exposes `gridfleet_worker_id` which returns the pytest-xdist worker id, or `"controller"` for non-worker processes
 - Relies on manager-owned runtime isolation for Appium driver sub-ports and XCUITest build paths
 
+If Appium driver creation fails before a Grid session exists, the pytest fixture registers a device-less terminal error session with an `error-<uuid>` session id, attempted capabilities, requested pack/platform metadata when available, and exception details, then re-raises the original exception. These rows make setup failures visible in the GridFleet Sessions view.
+
 ## Direct Appium Usage
 
 If you need to create a driver outside pytest, use the public Appium helpers:
@@ -128,15 +146,20 @@ finally:
 
 | Helper | Purpose |
 | --- | --- |
-| `GridFleetClient.list_devices(filters)` | List devices using backend filters such as `status`, `pack_id`, `platform_id`, `host_id`, `connection_target`, and `tags.*` |
+| `GridFleetClient.list_devices(*, pack_id=None, status=None, host_id=None, ...)` | List devices using backend keyword filters (pack_id, platform_id, status, host_id, connection_target, tags, ...) |
 | `GridFleetClient.get_device(device_id)` | Fetch one full device detail row by backend device id |
-| `GridFleetClient.get_device_config(connection_target, reveal=True)` | Look up a device by runtime connection target and fetch its config |
+| `GridFleetClient.get_device_config(connection_target)` | Look up a device by runtime connection target and fetch its config |
+| `GridFleetClient.get_device_capabilities(device_id)` | Fetch current Appium capability metadata for a device |
+| `GridFleetClient.get_device_test_data(device_id)` | Fetch operator-attached free-form test_data for a device |
+| `GridFleetClient.replace_device_test_data(device_id, body)` | Replace test_data with the supplied object |
+| `GridFleetClient.merge_device_test_data(device_id, body)` | Deep-merge into device test_data |
+| `GridFleetClient.resolve_device_id_by_connection_target(connection_target)` | Resolve the backend device id for a runtime connection target |
 | `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_safe(run_id, device_id=..., worker_id=...)` | Release a worker claim and tolerate 404/409 when cleanup races with run finalization or a prior release |
+| `GridFleetClient.release_device_safe(run_id, device_id=..., worker_id=...)` | Return `True` when release is accepted, `False` when the run is gone or the claim is already unclaimed, and raise on wrong-worker conflicts or unsafe errors |
 | `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` |
@@ -151,7 +174,8 @@ finally:
 | `build_error_session_payload(fields)` | Build a `/api/sessions` payload for driver-creation failures without importing pytest |
 | `hydrate_allocated_device(claim_response, run_id, client)` | Combine a claim response with optional device config and live capabilities |
 | `hydrate_allocated_device_from_driver(allocated, driver, client)` | Return a new allocated-device object with capabilities from a running driver |
-| `register_run_cleanup(client, run_id, heartbeat_thread=None)` | Register `atexit` and signal cleanup that completes or cancels a run |
+| `get_device_test_data_for_driver(driver, gridfleet_client=None)` | Fetch test_data for a live Appium driver |
+| `register_run_cleanup(client, run_id, heartbeat_thread=None)` | Register `atexit` cleanup callable and return it; stops the heartbeat thread on exit but does not complete or cancel the run by default |
 
 ### Worker Identity
 
@@ -182,7 +206,9 @@ run = client.reserve_devices(
 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)
+cleanup = register_run_cleanup(client, run_id, heartbeat_thread)
+# cleanup() runs at process exit; call client.complete_run(run_id) on success
+# or client.cancel_run(run_id) on failure to set the run state explicitly.
 
 # If one reserved device fails setup:
 client.report_preparation_failure(
@@ -244,7 +270,60 @@ assert allocated.device_id == claim["device_id"]
 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`.
+The helper fetches static device config by default when `connection_target` is present. It fetches live capabilities only when `fetch_capabilities=True`. Pass `fetch_test_data=True` to also populate `allocated.test_data`. The `test_data` field is also available directly from the claim response when the manager inlines it.
+
+### Run Cleanup Policy
+
+`register_run_cleanup(...)` registers an atexit cleanup callable and returns it. By default it stops the heartbeat thread but does not complete or cancel the run, because process exit alone does not prove test success. Prefer explicit `client.complete_run(run_id)` after successful orchestration and `client.cancel_run(run_id)` for known failures. Pass `on_exit="complete"` or `on_exit="cancel"` only when that policy is correct for your script. Signal handlers are opt-in with `install_signal_handlers=True`; signal cleanup defaults to cancellation.
+
+### Device Test Data
+
+The `device_test_data` fixture returns the operator-attached free-form test_data for the device assigned to the current test:
+
+```python
+def test_uses_operator_data(appium_driver, device_test_data):
+    assert "account" in device_test_data
+```
+
+Outside of pytest, use the client directly:
+
+```python
+test_data = client.get_device_test_data(device_id)
+```
+
+Or use the driver helper:
+
+```python
+from gridfleet_testkit import get_device_test_data_for_driver
+
+test_data = get_device_test_data_for_driver(driver)
+```
+
+### Errors and Result Types
+
+- `NoClaimableDevicesError(RuntimeError)`: raised when the manager reports no run devices are claimable yet. Exposes `run_id`, `retry_after_sec`, and `next_available_at`. The `RuntimeError` base is part of the contract — consumers can rely on it.
+- `UnknownIncludeError(ValueError)`: raised when the backend rejects one or more `?include=` keys. Exposes `values` with the rejected key names. The `ValueError` base is part of the contract.
+- `ReserveCapabilitiesUnsupportedError(ValueError)`: raised when a reserve-time `include` request contains `"capabilities"`, which is not supported at reserve time. The `ValueError` base is part of the contract.
+- `CooldownResult`: union response type from `release_device_with_cooldown`, with `status` equal to `"cooldown_set"` or `"maintenance_escalated"`. `CooldownSetResult` and `CooldownEscalatedResult` are the concrete TypedDict variants.
+
+### Reduced HTTP round-trips on claim
+
+The manager can inline 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
+```
+
+`device_config` and inline `config` payloads are returned verbatim from the manager. The testkit does not perform client-side secret masking or reveal toggles. Protect device config with manager authentication, operator access control, and your lab's secret-handling policy.
+
+`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
 

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

@@ -1,5 +1,10 @@
 """Supported Python integration helpers for GridFleet.
 
+`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)`.
+
 Environment variables read by the client:
 
 - GRID_URL: Selenium Grid URL used by Appium helper defaults.
@@ -13,19 +18,28 @@ 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,
     get_connection_target_from_driver,
     get_device_config_for_driver,
+    get_device_test_data_for_driver,
 )
 from .client import (
-    GRID_URL,
-    GRIDFLEET_API_URL,
+    CooldownResult,
     GridFleetClient,
     HeartbeatThread,
     NoClaimableDevicesError,
+    ReserveCapabilitiesUnsupportedError,
+    UnknownIncludeError,
+    _default_api_url,
+    _default_grid_url,
     register_run_cleanup,
 )
 from .sessions import build_error_session_payload
@@ -33,22 +47,35 @@ from .sessions import build_error_session_payload
 try:
     __version__ = version("gridfleet-testkit")
 except PackageNotFoundError:
-    __version__ = "0.3.0"
+    __version__ = "0.5.0"
 
 __all__ = [
     "GRIDFLEET_API_URL",
     "GRID_URL",
     "AllocatedDevice",
+    "CooldownResult",
     "GridFleetClient",
     "HeartbeatThread",
     "NoClaimableDevicesError",
+    "ReserveCapabilitiesUnsupportedError",
+    "UnavailableInclude",
+    "UnknownIncludeError",
     "__version__",
     "build_appium_options",
     "build_error_session_payload",
     "create_appium_driver",
     "get_connection_target_from_driver",
     "get_device_config_for_driver",
+    "get_device_test_data_for_driver",
     "hydrate_allocated_device",
     "hydrate_allocated_device_from_driver",
     "register_run_cleanup",
 ]
+
+
+def __getattr__(name: str) -> str:
+    if name == "GRID_URL":
+        return _default_grid_url()
+    if name == "GRIDFLEET_API_URL":
+        return _default_api_url()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{gridfleet_testkit-0.3.0 → gridfleet_testkit-0.5.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
+    test_data: dict[str, Any] | None = None
+    unavailable_includes: tuple[UnavailableInclude, ...] = ()
 
     @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],
     *,
@@ -96,16 +121,47 @@ def hydrate_allocated_device(
     client: GridFleetClient,
     fetch_config: bool = True,
     fetch_capabilities: bool = False,
+    fetch_test_data: 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
+    elif fetch_config and connection_target and "config" not in unavailable_set:
+        config = client.get_device_config(connection_target)
+    else:
+        config = None
+    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
+
+    inline_test_data = payload.get("test_data")
+    if isinstance(inline_test_data, dict):
+        test_data: dict[str, Any] | None = inline_test_data
+    elif fetch_test_data and "test_data" not in unavailable_set:
+        test_data = client.get_device_test_data(device_id)
+    else:
+        test_data = None
 
     return AllocatedDevice(
         run_id=run_id,
@@ -126,6 +182,8 @@ def hydrate_allocated_device(
         claimed_at=_string_value(payload, "claimed_at"),
         config=config,
         live_capabilities=live_capabilities,
+        test_data=test_data,
+        unavailable_includes=unavailable_includes,
     )
 
 

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

@@ -8,15 +8,11 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     from collections.abc import Mapping
 
-    from .client import GridFleetClient
-
-from .client import GRID_URL
+from .client import GridFleetClient, _default_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()
@@ -97,7 +93,9 @@ def build_appium_options(
     catalog_client: Any | None = None,
 ) -> Any:
     """Build Appium options from driver-pack catalog platform metadata."""
-    from appium.options.common import AppiumOptions
+    # appium is an optional dep (extra "appium"); imported lazily so consumers
+    # without the extra can still use the rest of testkit.
+    from appium.options.common import AppiumOptions  # noqa: PLC0415
 
     params = dict(capabilities or {})
     explicit_platform_name = params.get("platformName")
@@ -129,11 +127,13 @@ def create_appium_driver(
     platform_id: str | None = None,
     capabilities: Mapping[str, Any] | None = None,
     test_name: str | None = None,
-    grid_url: str = GRID_URL,
+    grid_url: str | None = None,
     catalog_client: Any | None = None,
 ) -> Any:
     """Create an Appium remote driver through Selenium Grid."""
-    from appium import webdriver
+    # appium is an optional dep (extra "appium"); imported lazily so consumers
+    # without the extra can still use the rest of testkit.
+    from appium import webdriver  # noqa: PLC0415
 
     options = build_appium_options(
         pack_id=pack_id,
@@ -142,7 +142,7 @@ def create_appium_driver(
         test_name=test_name,
         catalog_client=catalog_client,
     )
-    return webdriver.Remote(grid_url, options=options)
+    return webdriver.Remote(grid_url or _default_grid_url(), options=options)
 
 
 def get_connection_target_from_driver(driver: Any) -> str:
@@ -158,10 +158,19 @@ 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))
+
 
+def get_device_test_data_for_driver(
+    driver: Any,
+    *,
+    gridfleet_client: GridFleetClient | None = None,
+) -> dict[str, Any]:
+    """Fetch operator-attached test_data for a live Appium driver session."""
     client = gridfleet_client or GridFleetClient()
-    return client.get_device_config(get_connection_target_from_driver(driver), reveal=reveal)
+    connection_target = get_connection_target_from_driver(driver)
+    device_id = client.resolve_device_id_by_connection_target(connection_target)
+    return client.get_device_test_data(device_id)