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

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

@@ -2,6 +2,20 @@
 
 All notable changes to the GridFleet testkit (`gridfleet-testkit` on PyPI) are documented here.
 
+## [0.9.2](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.9.1...gridfleet-testkit-v0.9.2) (2026-05-16)
+
+
+### Bug Fixes
+
+* **testkit:** remove pytest_plugins shim and stale --extra appium docs ([#270](https://github.com/quidow/gridfleet/issues/270)) ([1165fc1](https://github.com/quidow/gridfleet/commit/1165fc1e7326853e7467500c41d8b1c197e7046f))
+
+## [0.9.1](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.9.0...gridfleet-testkit-v0.9.1) (2026-05-13)
+
+
+### Bug Fixes
+
+* **testkit:** align release policy with commitlint ([5dd8220](https://github.com/quidow/gridfleet/commit/5dd822010460e994f2e3c5b6676a69bed05678ed))
+
 ## [0.9.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.8.0...gridfleet-testkit-v0.9.0) (2026-05-12)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridfleet-testkit
-Version: 0.9.0
+Version: 0.9.2
 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
@@ -22,10 +22,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.10
+Requires-Dist: appium-python-client<6,>=4.5
 Requires-Dist: httpx<1,>=0.27
 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<3,>=1.20.2; extra == 'dev'
 Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
@@ -81,19 +80,19 @@ The supported contract is the installable package and documented import pattern.
 From PyPI:
 
 ```bash
-pip install "gridfleet-testkit[appium]"
+pip install "gridfleet-testkit"
 ```
 
 From a local checkout:
 
 ```bash
-uv pip install -e ./testkit[appium]
+uv pip install -e ./testkit
 ```
 
 From a copied `testkit/` directory inside another repository:
 
 ```bash
-uv pip install -e ./testkit[appium]
+uv pip install -e ./testkit
 ```
 
 From a Git checkout or VCS URL that contains this package:
@@ -103,6 +102,7 @@ uv pip install "git+https://github.com/<org>/<repo>.git#subdirectory=testkit"
 ```
 
 The package supports Python 3.10 and newer.
+`Appium-Python-Client` is installed as a runtime dependency because the pytest fixtures create real Appium sessions.
 
 ## Environment
 

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

@@ -47,19 +47,19 @@ The supported contract is the installable package and documented import pattern.
 From PyPI:
 
 ```bash
-pip install "gridfleet-testkit[appium]"
+pip install "gridfleet-testkit"
 ```
 
 From a local checkout:
 
 ```bash
-uv pip install -e ./testkit[appium]
+uv pip install -e ./testkit
 ```
 
 From a copied `testkit/` directory inside another repository:
 
 ```bash
-uv pip install -e ./testkit[appium]
+uv pip install -e ./testkit
 ```
 
 From a Git checkout or VCS URL that contains this package:
@@ -69,6 +69,7 @@ uv pip install "git+https://github.com/<org>/<repo>.git#subdirectory=testkit"
 ```
 
 The package supports Python 3.10 and newer.
+`Appium-Python-Client` is installed as a runtime dependency because the pytest fixtures create real Appium sessions.
 
 ## Environment
 

{gridfleet_testkit-0.9.0 → gridfleet_testkit-0.9.2}/examples/_example_helpers.py

@@ -3,13 +3,18 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from appium.webdriver.webdriver import WebDriver
 
 SCREENSHOT_DIR = Path(__file__).parent / "screenshots"
 ROKU_HELLO_WORLD_APP = Path(__file__).parent / "assets" / "hello-world.zip"
 
 
-def _resolved_connection_target(capabilities: dict[str, Any]) -> str:
+def _resolved_connection_target(capabilities: Mapping[str, object]) -> str:
     value = capabilities.get("appium:udid")
     if isinstance(value, str) and value:
         return value
@@ -19,7 +24,7 @@ def _resolved_connection_target(capabilities: dict[str, Any]) -> str:
     return "session"
 
 
-def print_connection_context(driver: Any) -> str:
+def print_connection_context(driver: WebDriver) -> str:
     """Print the resolved session context and return the connection target string."""
     caps = driver.capabilities
     connection_target = _resolved_connection_target(caps)
@@ -35,7 +40,7 @@ def print_connection_context(driver: Any) -> str:
     return connection_target
 
 
-def save_and_assert_screenshot(driver: Any, example_name: str) -> Path:
+def save_and_assert_screenshot(driver: WebDriver, example_name: str) -> Path:
     """Save a screenshot and assert that the written file is non-empty."""
     caps = driver.capabilities
     connection_target = _resolved_connection_target(caps).replace(":", "_")
@@ -51,7 +56,7 @@ def save_and_assert_screenshot(driver: Any, example_name: str) -> Path:
     return screenshot_path
 
 
-def install_and_activate_roku_dev_app(driver: Any) -> None:
+def install_and_activate_roku_dev_app(driver: WebDriver) -> None:
     """Install and activate the bundled Roku dev app used by screenshot examples."""
     assert ROKU_HELLO_WORLD_APP.exists(), f"App package not found: {ROKU_HELLO_WORLD_APP}"
     driver.install_app(str(ROKU_HELLO_WORLD_APP.resolve()))

{gridfleet_testkit-0.9.0 → gridfleet_testkit-0.9.2}/examples/test_android_mobile_screenshot.py

@@ -5,20 +5,17 @@ Requires:
     - Selenium Grid hub running on localhost:4444
     - An Android mobile device registered and its Appium node running
     - The supported GridFleet testkit installed
-    - Appium-Python-Client installed (`uv pip install -e ./testkit[appium]`)
+    - Appium-Python-Client installed (`uv pip install -e ./testkit`)
 
 Run:
     cd testkit && python -m pytest examples/test_android_mobile_screenshot.py -v -s
 """
 
-from typing import Any
-
 import pytest
+from appium.webdriver.webdriver import WebDriver
 
 from examples._example_helpers import print_connection_context, save_and_assert_screenshot
 
-pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
-
 
 @pytest.mark.parametrize(
     "appium_driver",
@@ -30,7 +27,7 @@ pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
     ],
     indirect=True,
 )
-def test_android_mobile_take_screenshot(appium_driver: Any) -> None:
+def test_android_mobile_take_screenshot(appium_driver: WebDriver) -> None:
     """Connect to an Android mobile device through the Grid and take a screenshot."""
     driver = appium_driver
 

{gridfleet_testkit-0.9.0 → gridfleet_testkit-0.9.2}/examples/test_android_tv_screenshot.py

@@ -5,20 +5,17 @@ Requires:
     - Selenium Grid hub running on localhost:4444
     - An Android TV device registered and its Appium node running
     - The supported GridFleet testkit installed
-    - Appium-Python-Client installed (`uv pip install -e ./testkit[appium]`)
+    - Appium-Python-Client installed (`uv pip install -e ./testkit`)
 
 Run:
     cd testkit && python -m pytest examples/test_android_tv_screenshot.py -v -s
 """
 
-from typing import Any
-
 import pytest
+from appium.webdriver.webdriver import WebDriver
 
 from examples._example_helpers import print_connection_context, save_and_assert_screenshot
 
-pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
-
 
 @pytest.mark.parametrize(
     "appium_driver",
@@ -30,7 +27,7 @@ pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
     ],
     indirect=True,
 )
-def test_android_tv_take_screenshot(appium_driver: Any) -> None:
+def test_android_tv_take_screenshot(appium_driver: WebDriver) -> None:
     """Connect to an Android TV device through the Grid and take a screenshot."""
     driver = appium_driver
 

{gridfleet_testkit-0.9.0 → gridfleet_testkit-0.9.2}/examples/test_firetv_screenshot.py

@@ -5,20 +5,17 @@ Requires:
     - Selenium Grid hub running on localhost:4444
     - A Fire TV device registered and its Appium node running
     - The supported GridFleet testkit installed
-    - Appium-Python-Client installed (`uv pip install -e ./testkit[appium]`)
+    - Appium-Python-Client installed (`uv pip install -e ./testkit`)
 
 Run:
     cd testkit && python -m pytest examples/test_firetv_screenshot.py -v -s
 """
 
-from typing import Any
-
 import pytest
+from appium.webdriver.webdriver import WebDriver
 
 from examples._example_helpers import print_connection_context, save_and_assert_screenshot
 
-pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
-
 
 @pytest.mark.parametrize(
     "appium_driver",
@@ -32,7 +29,7 @@ pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
     ],
     indirect=True,
 )
-def test_firetv_take_screenshot(appium_driver: Any) -> None:
+def test_firetv_take_screenshot(appium_driver: WebDriver) -> None:
     """Connect to a Fire TV device through the Grid and take a screenshot."""
     driver = appium_driver
 

{gridfleet_testkit-0.9.0 → gridfleet_testkit-0.9.2}/examples/test_ios_simulator_screenshot.py

@@ -6,20 +6,17 @@ Requires:
     - An iOS simulator registered and its Appium node running
     - The supported GridFleet testkit installed
     - Appium with the XCUITest driver installed (`appium driver install xcuitest`)
-    - Appium-Python-Client installed (`uv pip install -e ./testkit[appium]`)
+    - Appium-Python-Client installed (`uv pip install -e ./testkit`)
 
 Run:
     cd testkit && python -m pytest examples/test_ios_simulator_screenshot.py -v -s
 """
 
-from typing import Any
-
 import pytest
+from appium.webdriver.webdriver import WebDriver
 
 from examples._example_helpers import print_connection_context, save_and_assert_screenshot
 
-pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
-
 
 @pytest.mark.parametrize(
     "appium_driver",
@@ -32,7 +29,7 @@ pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
     ],
     indirect=True,
 )
-def test_ios_take_screenshot(appium_driver: Any) -> None:
+def test_ios_take_screenshot(appium_driver: WebDriver) -> None:
     """Connect to an iOS simulator through the Grid and take a screenshot."""
     driver = appium_driver
 

{gridfleet_testkit-0.9.0 → gridfleet_testkit-0.9.2}/examples/test_roku_screenshot.py

@@ -6,15 +6,14 @@ Requires:
     - A Roku device registered with Roku dev credentials in device config
     - Appium with the Roku driver installed (`appium driver install roku`)
     - The supported GridFleet testkit installed
-    - Appium-Python-Client installed (`uv pip install -e ./testkit[appium]`)
+    - Appium-Python-Client installed (`uv pip install -e ./testkit`)
 
 Run:
     cd testkit && python -m pytest examples/test_roku_screenshot.py -v -s
 """
 
-from typing import Any
-
 import pytest
+from appium.webdriver.webdriver import WebDriver
 
 from examples._example_helpers import (
     install_and_activate_roku_dev_app,
@@ -22,8 +21,6 @@ from examples._example_helpers import (
     save_and_assert_screenshot,
 )
 
-pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
-
 
 @pytest.mark.parametrize(
     "appium_driver",
@@ -35,7 +32,7 @@ pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
     ],
     indirect=True,
 )
-def test_roku_take_screenshot(appium_driver: Any) -> None:
+def test_roku_take_screenshot(appium_driver: WebDriver) -> None:
     """Connect to a Roku device through the Grid and take a screenshot."""
     driver = appium_driver
 

{gridfleet_testkit-0.9.0 → gridfleet_testkit-0.9.2}/examples/test_roku_sideload_screenshot.py

@@ -6,15 +6,14 @@ Requires:
     - A Roku device registered with Roku dev credentials in device config
     - Appium with the Roku driver installed (`appium driver install roku`)
     - The supported GridFleet testkit installed
-    - Appium-Python-Client installed (`uv pip install -e ./testkit[appium]`)
+    - Appium-Python-Client installed (`uv pip install -e ./testkit`)
 
 Run:
     cd testkit && python -m pytest examples/test_roku_sideload_screenshot.py -v -s
 """
 
-from typing import Any
-
 import pytest
+from appium.webdriver.webdriver import WebDriver
 
 from examples._example_helpers import (
     ROKU_HELLO_WORLD_APP,
@@ -23,8 +22,6 @@ from examples._example_helpers import (
     save_and_assert_screenshot,
 )
 
-pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
-
 
 @pytest.mark.parametrize(
     "appium_driver",
@@ -36,7 +33,7 @@ pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
     ],
     indirect=True,
 )
-def test_roku_install_app_and_take_screenshot(appium_driver: Any) -> None:
+def test_roku_install_app_and_take_screenshot(appium_driver: WebDriver) -> None:
     """Connect to a Roku device, sideload an app, and take a screenshot."""
     driver = appium_driver
 

{gridfleet_testkit-0.9.0 → gridfleet_testkit-0.9.2}/examples/test_tvos_screenshot.py

@@ -7,20 +7,17 @@ Requires:
     - The supported GridFleet testkit installed
     - Appium with the XCUITest driver installed (`appium driver install xcuitest`)
     - tvOS real-device prerequisites already configured on the host, including WebDriverAgent/XCUITest setup
-    - Appium-Python-Client installed (`uv pip install -e ./testkit[appium]`)
+    - Appium-Python-Client installed (`uv pip install -e ./testkit`)
 
 Run:
     cd testkit && python -m pytest examples/test_tvos_screenshot.py -v -s
 """
 
-from typing import Any
-
 import pytest
+from appium.webdriver.webdriver import WebDriver
 
 from examples._example_helpers import print_connection_context, save_and_assert_screenshot
 
-pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
-
 
 @pytest.mark.parametrize(
     "appium_driver",
@@ -32,7 +29,7 @@ pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
     ],
     indirect=True,
 )
-def test_tvos_take_screenshot(appium_driver: Any) -> None:
+def test_tvos_take_screenshot(appium_driver: WebDriver) -> None:
     """Connect to a tvOS real device through the Grid and take a screenshot."""
     driver = appium_driver
 

{gridfleet_testkit-0.9.0 → gridfleet_testkit-0.9.2}/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.9.0"
+    __version__ = "0.9.2"
 
 __all__ = [
     "GRIDFLEET_API_URL",

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

@@ -3,10 +3,13 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, replace
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
+    from appium.webdriver.webdriver import WebDriver
+
     from .client import GridFleetClient
+    from .types import JsonObject
 
 
 @dataclass(frozen=True)
@@ -35,9 +38,9 @@ class AllocatedDevice:
     connection_type: str
     manufacturer: str | None
     model: str | None
-    config: dict[str, Any] | None
-    live_capabilities: dict[str, Any] | None
-    test_data: dict[str, Any] | None = None
+    config: JsonObject | None
+    live_capabilities: JsonObject | None
+    test_data: JsonObject | None = None
     unavailable_includes: tuple[UnavailableInclude, ...] = ()
     tags: dict[str, str] | None = None
 
@@ -72,23 +75,23 @@ class AllocatedDevice:
         return self.platform_label or self.platform_id
 
 
-def _string_value(payload: dict[str, Any], key: str, *, default: str | None = None) -> str:
+def _string_value(payload: JsonObject, key: str, *, default: str | None = None) -> str:
     value = payload.get(key, default)
     if isinstance(value, str) and value:
         return value
     raise ValueError(f"Allocated device payload is missing {key}")
 
 
-def _optional_string_value(payload: dict[str, Any], key: str) -> str | None:
+def _optional_string_value(payload: JsonObject, key: str) -> str | None:
     value = payload.get(key)
     return value if isinstance(value, str) and value else None
 
 
-def _needs_device_detail(payload: dict[str, Any]) -> bool:
+def _needs_device_detail(payload: JsonObject) -> bool:
     return any(payload.get(key) is None for key in ("name", "device_type", "connection_type", "manufacturer", "model"))
 
 
-def _merge_device_detail(payload: dict[str, Any], detail: dict[str, Any]) -> dict[str, Any]:
+def _merge_device_detail(payload: JsonObject, detail: JsonObject) -> JsonObject:
     merged = dict(payload)
     for key in ("name", "device_type", "connection_type", "manufacturer", "model"):
         if merged.get(key) is None and detail.get(key) is not None:
@@ -98,7 +101,7 @@ 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, ...]:
+def _parse_unavailable_includes(payload: JsonObject) -> tuple[UnavailableInclude, ...]:
     raw = payload.get("unavailable_includes")
     if not isinstance(raw, list):
         return ()
@@ -114,7 +117,7 @@ def _parse_unavailable_includes(payload: dict[str, Any]) -> tuple[UnavailableInc
 
 
 def hydrate_allocated_device(
-    device_handle: dict[str, Any],
+    device_handle: JsonObject,
     *,
     run_id: str,
     client: GridFleetClient,
@@ -134,14 +137,14 @@ def hydrate_allocated_device(
     connection_target = _optional_string_value(payload, "connection_target")
     inline_config = payload.get("config")
     if isinstance(inline_config, dict):
-        config: dict[str, Any] | None = inline_config
+        config: JsonObject | None = cast("JsonObject", 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
+        live_capabilities: JsonObject | None = cast("JsonObject", inline_capabilities)
     elif fetch_capabilities and "capabilities" not in unavailable_set:
         live_capabilities = client.get_device_capabilities(device_id)
     else:
@@ -149,7 +152,7 @@ def hydrate_allocated_device(
 
     inline_test_data = payload.get("test_data")
     if isinstance(inline_test_data, dict):
-        test_data: dict[str, Any] | None = inline_test_data
+        test_data: JsonObject | None = cast("JsonObject", inline_test_data)
     elif fetch_test_data and "test_data" not in unavailable_set:
         test_data = client.get_device_test_data(device_id)
     else:
@@ -185,14 +188,14 @@ def hydrate_allocated_device(
 
 def hydrate_allocated_device_from_driver(
     allocated: AllocatedDevice,
-    driver: Any,
+    driver: WebDriver,
     *,
     client: GridFleetClient,
 ) -> AllocatedDevice:
     """Refresh live capabilities from a running Appium driver session."""
     capabilities = getattr(driver, "capabilities", None)
     if isinstance(capabilities, dict):
-        live_capabilities = dict(capabilities)
+        live_capabilities = cast("JsonObject", dict(capabilities))
     else:
         live_capabilities = client.get_device_capabilities(allocated.device_id)
     return replace(allocated, live_capabilities=live_capabilities)

{gridfleet_testkit-0.9.0 → gridfleet_testkit-0.9.2}/gridfleet_testkit/appium.py

@@ -3,35 +3,43 @@
 from __future__ import annotations
 
 import os
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, cast
 
-if TYPE_CHECKING:
-    from collections.abc import Mapping
+from appium import webdriver
+from appium.options.common import AppiumOptions
 
 from .client import GridFleetClient, _default_grid_url
 
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+    from appium.webdriver.webdriver import WebDriver
+
+    from .types import JsonObject
 
-def _catalog_payload(catalog_client: Any | None) -> dict[str, Any]:
+
+def _catalog_payload(catalog_client: object | None) -> JsonObject:
     if catalog_client is None:
         catalog_client = GridFleetClient()
-    if hasattr(catalog_client, "get_driver_pack_catalog"):
-        payload = catalog_client.get_driver_pack_catalog()
+    catalog_getter = getattr(catalog_client, "get_driver_pack_catalog", None)
+    if callable(catalog_getter):
+        payload = catalog_getter()
     elif callable(catalog_client):
-        payload = catalog_client()
+        payload = cast("Callable[[], object]", catalog_client)()
     else:
         payload = catalog_client
     if isinstance(payload, dict):
-        return payload
+        return cast("JsonObject", payload)
     if isinstance(payload, list):
-        return {"packs": payload}
+        return cast("JsonObject", {"packs": payload})
     raise ValueError("Driver pack catalog client returned an invalid payload")
 
 
-def _enabled_platform_matches(catalog: dict[str, Any], platform_id: str) -> list[tuple[dict[str, Any], dict[str, Any]]]:
+def _enabled_platform_matches(catalog: JsonObject, platform_id: str) -> list[tuple[JsonObject, JsonObject]]:
     packs = catalog.get("packs")
     if not isinstance(packs, list):
         raise ValueError("Driver pack catalog payload must include a packs list")
-    matches: list[tuple[dict[str, Any], dict[str, Any]]] = []
+    matches: list[tuple[JsonObject, JsonObject]] = []
     for pack in packs:
         if not isinstance(pack, dict) or pack.get("state") != "enabled":
             continue
@@ -48,8 +56,8 @@ def _resolve_pack_platform(
     *,
     pack_id: str | None,
     platform_id: str | None,
-    catalog_client: Any | None,
-) -> tuple[str, dict[str, Any]]:
+    catalog_client: object | None,
+) -> tuple[str, JsonObject]:
     resolved_pack_id = pack_id or os.getenv("GRIDFLEET_TESTKIT_PACK_ID")
     resolved_platform_id = platform_id or os.getenv("GRIDFLEET_TESTKIT_PLATFORM_ID")
     if not resolved_platform_id:
@@ -77,7 +85,7 @@ def _resolve_pack_platform(
     raise ValueError(f"Enabled driver pack platform for platform_id {resolved_platform_id!r} was not found")
 
 
-def _required_platform_string(platform: dict[str, Any], key: str) -> str:
+def _required_platform_string(platform: JsonObject, key: str) -> str:
     value = platform.get(key)
     if not isinstance(value, str) or not value:
         raise ValueError(f"Driver pack platform is missing {key}")
@@ -88,15 +96,11 @@ def build_appium_options(
     *,
     pack_id: str | None = None,
     platform_id: str | None = None,
-    capabilities: Mapping[str, Any] | None = None,
+    capabilities: Mapping[str, object] | None = None,
     test_name: str | None = None,
-    catalog_client: Any | None = None,
-) -> Any:
+    catalog_client: object | None = None,
+) -> AppiumOptions:
     """Build Appium options from driver-pack catalog platform metadata."""
-    # 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 {})
     params.setdefault("gridfleet:run_id", os.environ.get("GRIDFLEET_RUN_ID", "free"))
     explicit_platform_name = params.get("platformName")
@@ -126,16 +130,12 @@ def create_appium_driver(
     *,
     pack_id: str | None = None,
     platform_id: str | None = None,
-    capabilities: Mapping[str, Any] | None = None,
+    capabilities: Mapping[str, object] | None = None,
     test_name: str | None = None,
     grid_url: str | None = None,
-    catalog_client: Any | None = None,
-) -> Any:
+    catalog_client: object | None = None,
+) -> WebDriver:
     """Create an Appium remote driver through Selenium Grid."""
-    # 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,
         platform_id=platform_id,
@@ -146,9 +146,9 @@ def create_appium_driver(
     return webdriver.Remote(grid_url or _default_grid_url(), options=options)
 
 
-def get_connection_target_from_driver(driver: Any) -> str:
+def get_connection_target_from_driver(driver: WebDriver) -> str:
     """Return the runtime connection target from a live Appium driver."""
-    capabilities = driver.capabilities
+    capabilities = cast("JsonObject", driver.capabilities) if isinstance(driver.capabilities, dict) else {}
     connection_target = capabilities.get("appium:udid")
     if not isinstance(connection_target, str) or not connection_target:
         raise ValueError("Could not determine device connection target from session capabilities")
@@ -156,20 +156,20 @@ def get_connection_target_from_driver(driver: Any) -> str:
 
 
 def get_device_config_for_driver(
-    driver: Any,
+    driver: WebDriver,
     *,
     gridfleet_client: GridFleetClient | None = None,
-) -> dict[str, Any]:
+) -> JsonObject:
     """Fetch device config for a live Appium driver using its runtime connection target."""
     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,
+    driver: WebDriver,
     *,
     gridfleet_client: GridFleetClient | None = None,
-) -> dict[str, Any]:
+) -> JsonObject:
     """Fetch operator-attached test_data for a live Appium driver session."""
     client = gridfleet_client or GridFleetClient()
     connection_target = get_connection_target_from_driver(driver)