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

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

@@ -2,6 +2,37 @@
 
 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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridfleet-testkit
-Version: 0.4.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,11 +304,45 @@ 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
 
-`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.
+The manager can inline device config and live capabilities into the claim/reserve response, eliminating per-worker follow-up GETs.
 
 ```python
 client = GridFleetClient()
@@ -291,7 +351,7 @@ 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.
+`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.
 

{gridfleet_testkit-0.4.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,11 +270,45 @@ 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
 
-`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.
+The manager can inline device config and live capabilities into the claim/reserve response, eliminating per-worker follow-up GETs.
 
 ```python
 client = GridFleetClient()
@@ -257,7 +317,7 @@ 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.
+`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.
 

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

@@ -1,11 +1,9 @@
 """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.
+`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:
 
@@ -31,15 +29,17 @@ from .appium import (
     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
@@ -47,12 +47,13 @@ from .sessions import build_error_session_payload
 try:
     __version__ = version("gridfleet-testkit")
 except PackageNotFoundError:
-    __version__ = "0.4.0"
+    __version__ = "0.5.0"
 
 __all__ = [
     "GRIDFLEET_API_URL",
     "GRID_URL",
     "AllocatedDevice",
+    "CooldownResult",
     "GridFleetClient",
     "HeartbeatThread",
     "NoClaimableDevicesError",
@@ -65,7 +66,16 @@ __all__ = [
     "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.4.0 → gridfleet_testkit-0.5.0}/gridfleet_testkit/allocation.py

@@ -39,8 +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, ...] = ()
-    config_is_masked: bool = False
 
     @property
     def is_real_device(self) -> bool:
@@ -121,6 +121,7 @@ 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.
 
@@ -142,13 +143,10 @@ def hydrate_allocated_device(
     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
@@ -157,6 +155,14 @@ def hydrate_allocated_device(
     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,
         device_id=device_id,
@@ -175,8 +181,8 @@ 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,
+        test_data=test_data,
         unavailable_includes=unavailable_includes,
     )
 

{gridfleet_testkit-0.4.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)