gridfleet-testkit 0.8.0__tar.gz → 0.9.0__tar.gz

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to the GridFleet testkit (`gridfleet-testkit` on PyPI) are documented here.
 
+## [0.9.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.8.0...gridfleet-testkit-v0.9.0) (2026-05-12)
+
+
+### Features
+
+* **testkit:** add run detail client helper ([c80a8cc](https://github.com/quidow/gridfleet/commit/c80a8cc95093c2f46a7e714c96ff0b33018af5ba))
+* **testkit:** expose allocation device tags ([0bf5e2e](https://github.com/quidow/gridfleet/commit/0bf5e2e04b806fadd0afcd3c95073828d0c2414e))
+* **testkit:** support tag-based device targeting ([db0d0e3](https://github.com/quidow/gridfleet/commit/db0d0e3d3d1231828bb22a707d3bdcab6c0ec717))
+
+
+### Documentation
+
+* **testkit:** document tag-based device targeting ([096841b](https://github.com/quidow/gridfleet/commit/096841b737dec71524d0edfa4c538d9cc69e7c2c))
+
 ## [0.8.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.7.0...gridfleet-testkit-v0.8.0) (2026-05-12)
 
 

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridfleet-testkit
-Version: 0.8.0
+Version: 0.9.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
@@ -192,6 +192,7 @@ finally:
 | `GridFleetClient.get_device_by_connection_target(connection_target)` | Fetch one device detail row by runtime connection target |
 | `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.get_run(run_id)` | Fetch one run detail row by backend run id |
 | `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 |
@@ -216,6 +217,38 @@ finally:
 | `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 |
 
+### Targeting Devices by Tag
+
+GridFleet injects device tags into Grid node stereotypes as `appium:gridfleet:tag:<key>` capabilities, so Selenium Grid can route sessions to devices matching specific tags.
+
+```python
+@pytest.mark.parametrize(
+    "appium_driver",
+    [
+        {
+            "pack_id": "appium-uiautomator2",
+            "platform_id": "android_mobile",
+            "appium:gridfleet:tag:screen_type": "4k",
+        }
+    ],
+    indirect=True,
+)
+def test_4k_display(appium_driver):
+    ...
+```
+
+The same capability works for free sessions:
+
+```python
+driver = create_appium_driver(
+    pack_id="appium-uiautomator2",
+    platform_id="android_mobile",
+    capabilities={"appium:gridfleet:tag:screen_type": "4k"},
+)
+```
+
+When an operator edits device tags, GridFleet marks the device for re-verification. The next verification restarts the Appium node and re-registers it with the updated Grid stereotype.
+
 ### Worker Identity
 
 `worker_id` is an arbitrary string used for reservation telemetry and run attribution. For pytest-xdist, pass `request.config.workerinput["workerid"]` from worker processes; values are normally `gw0`, `gw1`, and so on. For controller-only flows, use `"controller"` or a stable hostname. For custom schedulers, use a UUID or job-specific worker name.

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/README.md

@@ -158,6 +158,7 @@ finally:
 | `GridFleetClient.get_device_by_connection_target(connection_target)` | Fetch one device detail row by runtime connection target |
 | `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.get_run(run_id)` | Fetch one run detail row by backend run id |
 | `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 |
@@ -182,6 +183,38 @@ finally:
 | `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 |
 
+### Targeting Devices by Tag
+
+GridFleet injects device tags into Grid node stereotypes as `appium:gridfleet:tag:<key>` capabilities, so Selenium Grid can route sessions to devices matching specific tags.
+
+```python
+@pytest.mark.parametrize(
+    "appium_driver",
+    [
+        {
+            "pack_id": "appium-uiautomator2",
+            "platform_id": "android_mobile",
+            "appium:gridfleet:tag:screen_type": "4k",
+        }
+    ],
+    indirect=True,
+)
+def test_4k_display(appium_driver):
+    ...
+```
+
+The same capability works for free sessions:
+
+```python
+driver = create_appium_driver(
+    pack_id="appium-uiautomator2",
+    platform_id="android_mobile",
+    capabilities={"appium:gridfleet:tag:screen_type": "4k"},
+)
+```
+
+When an operator edits device tags, GridFleet marks the device for re-verification. The next verification restarts the Appium node and re-registers it with the updated Grid stereotype.
+
 ### Worker Identity
 
 `worker_id` is an arbitrary string used for reservation telemetry and run attribution. For pytest-xdist, pass `request.config.workerinput["workerid"]` from worker processes; values are normally `gw0`, `gw1`, and so on. For controller-only flows, use `"controller"` or a stable hostname. For custom schedulers, use a UUID or job-specific worker name.

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/gridfleet_testkit/__init__.py

@@ -47,7 +47,7 @@ from .sessions import build_error_session_payload, resolve_device_handle_from_dr
 try:
     __version__ = version("gridfleet-testkit")
 except PackageNotFoundError:
-    __version__ = "0.8.0"
+    __version__ = "0.9.0"
 
 __all__ = [
     "GRIDFLEET_API_URL",

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/gridfleet_testkit/allocation.py

@@ -39,6 +39,7 @@ class AllocatedDevice:
     live_capabilities: dict[str, Any] | None
     test_data: dict[str, Any] | None = None
     unavailable_includes: tuple[UnavailableInclude, ...] = ()
+    tags: dict[str, str] | None = None
 
     @property
     def is_real_device(self) -> bool:
@@ -153,6 +154,11 @@ def hydrate_allocated_device(
         test_data = client.get_device_test_data(device_id)
     else:
         test_data = None
+    inline_tags = payload.get("tags")
+    if isinstance(inline_tags, dict):
+        tags: dict[str, str] | None = inline_tags
+    else:
+        tags = None
 
     return AllocatedDevice(
         run_id=run_id,
@@ -173,6 +179,7 @@ def hydrate_allocated_device(
         live_capabilities=live_capabilities,
         test_data=test_data,
         unavailable_includes=unavailable_includes,
+        tags=tags,
     )
 
 

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/gridfleet_testkit/client.py

@@ -290,6 +290,16 @@ class GridFleetClient:
         resp.raise_for_status()
         return cast("dict[str, Any]", resp.json())
 
+    def get_run(self, run_id: str) -> dict[str, Any]:
+        """Fetch one run detail row by backend run id."""
+        resp = httpx.get(
+            f"{self.base_url}/runs/{run_id}",
+            timeout=10,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+        return cast("dict[str, Any]", resp.json())
+
     def replace_device_test_data(self, device_id: str, body: dict[str, Any]) -> dict[str, Any]:
         """Replace device test_data with the supplied object."""
         resp = httpx.put(

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/pyproject.toml

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

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/tests/test_allocation.py

@@ -328,6 +328,17 @@ def test_hydrate_uses_inline_test_data() -> None:
     assert client.test_data_calls == []
 
 
+def test_hydrate_allocated_device_populates_inline_tags() -> None:
+    client = FakeClient()
+    allocated = hydrate_allocated_device(
+        device_handle(tags={"screen_type": "4k"}),
+        run_id="run-1",
+        client=client,
+        fetch_config=False,
+    )
+    assert allocated.tags == {"screen_type": "4k"}
+
+
 def test_hydrate_defaults_test_data_to_none_when_absent() -> None:
     client = FakeClient()
     allocated = hydrate_allocated_device(

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/tests/test_client.py

@@ -187,6 +187,27 @@ def test_get_device_fetches_device_detail_by_id(monkeypatch):
     assert calls == [("http://manager/api/devices/dev-1", 10)]
 
 
+def test_get_run_fetches_run_endpoint(monkeypatch):
+    calls: list[tuple[str, int | None]] = []
+
+    def fake_get(
+        url: str,
+        *,
+        timeout: int | None = None,
+        auth: Any = None,
+    ) -> DummyResponse:
+        calls.append((url, timeout))
+        return DummyResponse({"id": "run-1", "name": "smoke"})
+
+    monkeypatch.setattr("gridfleet_testkit.client.httpx.get", fake_get)
+
+    client = GridFleetClient("http://manager/api")
+    run = client.get_run("run-1")
+
+    assert run == {"id": "run-1", "name": "smoke"}
+    assert calls == [("http://manager/api/runs/run-1", 10)]
+
+
 def test_get_driver_pack_catalog_fetches_catalog_endpoint(monkeypatch):
     calls: list[tuple[str, str, dict[str, Any] | None, int | None]] = []
 

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/tests/test_pytest_plugin.py

@@ -188,6 +188,33 @@ def test_appium_driver_builds_capabilities_and_reports_status(monkeypatch, repor
     assert gridfleet_client.reported_statuses == [("sess-1", expected_status, True)]
 
 
+def test_appium_driver_passes_tag_capabilities_through(monkeypatch):
+    created_drivers = []
+    install_fake_appium(monkeypatch, created_drivers)
+    RecordingClient.instances.clear()
+    gridfleet_client = RecordingClient()
+
+    request = FakeRequest(
+        {
+            "pack_id": "appium-uiautomator2",
+            "platform_id": "android_mobile",
+            "appium:gridfleet:tag:screen_type": "4k",
+        },
+        test_name="test_tag_cap",
+    )
+
+    fixture_fn = pytest_plugin.appium_driver.__wrapped__
+    generator = fixture_fn(request, gridfleet_client)
+    driver = next(generator)
+
+    assert created_drivers[0][1]["appium:gridfleet:tag:screen_type"] == "4k"
+    assert created_drivers[0][1]["gridfleet:testName"] == "test_tag_cap"
+
+    driver.quit()
+    with pytest.raises(StopIteration):
+        next(generator)
+
+
 def test_device_config_uses_runtime_connection_target():
     gridfleet_client = types.SimpleNamespace(get_device_config=lambda target: {"target": target})
     driver = types.SimpleNamespace(capabilities={"appium:udid": "SERIAL123"})

{gridfleet_testkit-0.8.0 → gridfleet_testkit-0.9.0}/uv.lock

@@ -136,7 +136,7 @@ wheels = [
 
 [[package]]
 name = "gridfleet-testkit"
-version = "0.8.0"
+version = "0.9.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },