gridfleet-testkit 0.1.0__tar.gz

gridfleet_testkit-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.venv/
+venv/
+*.egg-info/
+*.egg
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Frontend
+frontend/node_modules/
+frontend/dist/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Playwright
+.playwright-mcp/
+
+
+# Build output
+dist/
+
+# Misc
+*.log
+.idea
+testing/screenshots
+frontend/test-results
+
+# Worktrees
+.worktrees/
+
+# Superpowers working docs
+.superpowers/

gridfleet_testkit-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: gridfleet-testkit
+Version: 0.1.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
+Project-URL: Documentation, https://github.com/quidow/gridfleet/tree/main/docs/reference/testkit.md
+Project-URL: Issues, https://github.com/quidow/gridfleet/issues
+Project-URL: Security, https://github.com/quidow/gridfleet/security/advisories/new
+Author: GridFleet contributors
+License-Expression: Apache-2.0
+Keywords: appium,gridfleet,pytest,selenium,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pytest>=9.0.3
+Provides-Extra: appium
+Requires-Dist: appium-python-client>=4.5; extra == 'appium'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.20.2; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.15.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# GridFleet Testkit
+
+`testkit/` is the supported Python integration surface for external pytest/Appium suites that run through GridFleet.
+
+## What This Package Owns
+
+- Stable import root: `gridfleet_testkit`
+- Supported pytest plugin: `gridfleet_testkit.pytest_plugin`
+- Supported public helpers:
+  - `build_appium_options`
+  - `create_appium_driver`
+  - `get_connection_target_from_driver`
+  - `get_device_config_for_driver`
+  - `GridFleetClient`
+  - `HeartbeatThread`
+  - `register_run_cleanup`
+- Manual hardware examples under `testkit/examples/`
+
+## What It Does Not Own
+
+- Appium server installation or host-level driver setup
+- Selenium Grid lifecycle
+- Device registration, verification, or readiness setup
+- CI orchestration beyond the documented client helpers
+
+The supported contract is the installable package and documented import pattern. The example scripts are onboarding aids, not CI-backed conformance tests.
+
+## Install
+
+From PyPI:
+
+```bash
+pip install "gridfleet-testkit[appium]"
+```
+
+From a local checkout:
+
+```bash
+uv pip install -e ./testkit[appium]
+```
+
+From a copied `testkit/` directory inside another repository:
+
+```bash
+uv pip install -e ./testkit[appium]
+```
+
+From a Git checkout or VCS URL that contains this package:
+
+```bash
+uv pip install "git+https://github.com/<org>/<repo>.git#subdirectory=testkit"
+```
+
+The package supports Python 3.10 and newer.
+
+## Environment
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `GRID_URL` | `http://localhost:4444` | Selenium Grid hub URL used by the pytest Appium fixture |
+| `GRIDFLEET_API_URL` | `http://localhost:8000/api` | GridFleet API base used for session reporting, config lookup, run helpers, and driver-pack catalog lookup |
+| `GRIDFLEET_TESTKIT_USERNAME` | unset | Machine-auth username sent as HTTP Basic auth on every API call. Required when the manager runs with `GRIDFLEET_AUTH_ENABLED=true`. Use the same value as the manager's `GRIDFLEET_MACHINE_AUTH_USERNAME`. |
+| `GRIDFLEET_TESTKIT_PASSWORD` | unset | Machine-auth password sent as HTTP Basic auth on every API call. Required when the manager runs with `GRIDFLEET_AUTH_ENABLED=true`. Use the same value as the manager's `GRIDFLEET_MACHINE_AUTH_PASSWORD`. |
+| `GRIDFLEET_TESTKIT_PACK_ID` | unset | Optional default driver pack id for Appium option building |
+| `GRIDFLEET_TESTKIT_PLATFORM_ID` | unset | Optional default platform id for Appium option building |
+
+The package assumes a running GridFleet API, a reachable Selenium Grid hub, and platform-specific Appium driver setup on the registered hosts. When auth is disabled on the manager, leave `GRIDFLEET_TESTKIT_USERNAME` / `GRIDFLEET_TESTKIT_PASSWORD` unset and the testkit will send no `Authorization` header.
+
+## Pytest Plugin
+
+Load the supported plugin from your test project:
+
+```python
+pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
+```
+
+Minimal usage:
+
+```python
+import pytest
+
+@pytest.mark.parametrize(
+    "appium_driver",
+    [{"pack_id": "appium-uiautomator2", "platform_id": "android_mobile"}],
+    indirect=True,
+)
+def test_session_starts(appium_driver):
+    assert appium_driver.session_id is not None
+```
+
+The plugin resolves `pack_id` and `platform_id` against the enabled driver-pack catalog, then injects Appium `platformName`, `appium:automationName`, `appium:platform`, and `gridfleet:testName`.
+
+When exactly one enabled pack provides a platform id, `platform_id` alone is accepted. For environment-portable tests, set `GRIDFLEET_TESTKIT_PACK_ID` and `GRIDFLEET_TESTKIT_PLATFORM_ID`, then parametrize with `{}`.
+
+If you need raw Appium control instead, omit `pack_id` and `platform_id`, then pass `platformName` as a normal capability key.
+
+### Plugin Lifecycle
+
+- Creates an Appium session through `GRID_URL`
+- 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
+- Relies on manager-owned runtime isolation for Appium driver sub-ports and XCUITest build paths
+
+## Direct Appium Usage
+
+If you need to create a driver outside pytest, use the public Appium helpers:
+
+```python
+from gridfleet_testkit import create_appium_driver, get_device_config_for_driver
+
+driver = create_appium_driver(
+    pack_id="appium-uiautomator2",
+    platform_id="firetv_real",
+    test_name="manual-smoke",
+)
+
+try:
+    assert driver.session_id is not None
+    device_config = get_device_config_for_driver(driver)
+finally:
+    driver.quit()
+```
+
+`create_appium_driver(...)` reuses the same driver-pack catalog resolver as the pytest fixture. Managed nodes still get their host-scoped runtime allocations from the manager, so callers should not hard-code `systemPort`, `chromedriverPort`, `mjpegServerPort`, `wdaLocalPort`, or `derivedDataPath`. `get_device_config_for_driver(...)` is the non-pytest equivalent of the `device_config` fixture. If you only need the options object, use `build_appium_options(...)`.
+
+## Client Helpers
+
+| Helper | Purpose |
+| --- | --- |
+| `GridFleetClient.get_device_config(connection_target, reveal=True)` | Look up a device by runtime connection target and fetch its config |
+| `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.signal_ready(run_id)` | Move a run to `ready` |
+| `GridFleetClient.signal_active(run_id)` | Move a run to `active` |
+| `GridFleetClient.heartbeat(run_id)` | Send a run heartbeat and read current state |
+| `GridFleetClient.report_preparation_failure(run_id, device_id, message, source="ci_preparation")` | Exclude one reserved device after setup fails |
+| `GridFleetClient.complete_run(run_id)` | Complete a run |
+| `GridFleetClient.cancel_run(run_id)` | Cancel a run |
+| `GridFleetClient.start_heartbeat(run_id, interval=30)` | Start a background heartbeat thread |
+| `register_run_cleanup(client, run_id, heartbeat_thread=None)` | Register `atexit` and signal cleanup that completes or cancels a run |
+
+### Reservation Flow
+
+```python
+from gridfleet_testkit import GridFleetClient, register_run_cleanup
+
+client = GridFleetClient("http://manager-ip:8000/api")
+
+run = client.reserve_devices(
+    name="my-test-run",
+    requirements=[
+        {
+            "pack_id": "appium-uiautomator2",
+            "platform_id": "firetv_real",
+            "os_version": "8",
+            "allocation": "all_available",
+            "min_count": 1,
+        }
+    ],
+    ttl_minutes=45,
+    created_by="local-dev",
+)
+
+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)
+
+# If one reserved device fails setup:
+client.report_preparation_failure(
+    run_id,
+    device_id="device-123",
+    message="Driver bootstrap timed out during CI setup",
+    source="local-dev",
+)
+
+client.signal_ready(run_id)
+client.signal_active(run_id)
+```
+
+Use `count` for exact reservations. Use `allocation: "all_available"` when CI should reserve every currently eligible matching device and size its worker pool from `len(run["devices"])`.
+
+## Examples
+
+Baseline screenshot examples:
+
+- `examples/test_android_mobile_screenshot.py`
+- `examples/test_android_tv_screenshot.py`
+- `examples/test_firetv_screenshot.py`
+- `examples/test_ios_simulator_screenshot.py`
+- `examples/test_tvos_screenshot.py`
+- `examples/test_roku_screenshot.py`
+
+Advanced example:
+
+- `examples/test_roku_sideload_screenshot.py`
+
+The baseline examples share the same flow:
+
+1. Create a session through Selenium Grid
+2. Print the resolved connection context
+3. Save a screenshot
+4. Assert that the screenshot file exists and is non-empty
+
+## Platform Notes
+
+- Android Mobile / Android TV / Fire TV:
+  - require the UiAutomator2 driver
+  - rely on Grid routing hints generated from GridFleet metadata
+- Fire TV:
+  - baseline example supports optional `appium:os_version` filtering when you need a specific Fire OS release
+- iOS simulator:
+  - baseline example intentionally targets the simulator lane with `appium:device_type=simulator`
+- tvOS:
+  - baseline example intentionally targets a real device and assumes the host already satisfies XCUITest and WebDriverAgent prerequisites
+- Roku:
+  - screenshot examples install and activate the bundled sample dev app before capture
+  - both Roku examples depend on Roku dev credentials

gridfleet_testkit-0.1.0/README.md

@@ -0,0 +1,219 @@
+# GridFleet Testkit
+
+`testkit/` is the supported Python integration surface for external pytest/Appium suites that run through GridFleet.
+
+## What This Package Owns
+
+- Stable import root: `gridfleet_testkit`
+- Supported pytest plugin: `gridfleet_testkit.pytest_plugin`
+- Supported public helpers:
+  - `build_appium_options`
+  - `create_appium_driver`
+  - `get_connection_target_from_driver`
+  - `get_device_config_for_driver`
+  - `GridFleetClient`
+  - `HeartbeatThread`
+  - `register_run_cleanup`
+- Manual hardware examples under `testkit/examples/`
+
+## What It Does Not Own
+
+- Appium server installation or host-level driver setup
+- Selenium Grid lifecycle
+- Device registration, verification, or readiness setup
+- CI orchestration beyond the documented client helpers
+
+The supported contract is the installable package and documented import pattern. The example scripts are onboarding aids, not CI-backed conformance tests.
+
+## Install
+
+From PyPI:
+
+```bash
+pip install "gridfleet-testkit[appium]"
+```
+
+From a local checkout:
+
+```bash
+uv pip install -e ./testkit[appium]
+```
+
+From a copied `testkit/` directory inside another repository:
+
+```bash
+uv pip install -e ./testkit[appium]
+```
+
+From a Git checkout or VCS URL that contains this package:
+
+```bash
+uv pip install "git+https://github.com/<org>/<repo>.git#subdirectory=testkit"
+```
+
+The package supports Python 3.10 and newer.
+
+## Environment
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `GRID_URL` | `http://localhost:4444` | Selenium Grid hub URL used by the pytest Appium fixture |
+| `GRIDFLEET_API_URL` | `http://localhost:8000/api` | GridFleet API base used for session reporting, config lookup, run helpers, and driver-pack catalog lookup |
+| `GRIDFLEET_TESTKIT_USERNAME` | unset | Machine-auth username sent as HTTP Basic auth on every API call. Required when the manager runs with `GRIDFLEET_AUTH_ENABLED=true`. Use the same value as the manager's `GRIDFLEET_MACHINE_AUTH_USERNAME`. |
+| `GRIDFLEET_TESTKIT_PASSWORD` | unset | Machine-auth password sent as HTTP Basic auth on every API call. Required when the manager runs with `GRIDFLEET_AUTH_ENABLED=true`. Use the same value as the manager's `GRIDFLEET_MACHINE_AUTH_PASSWORD`. |
+| `GRIDFLEET_TESTKIT_PACK_ID` | unset | Optional default driver pack id for Appium option building |
+| `GRIDFLEET_TESTKIT_PLATFORM_ID` | unset | Optional default platform id for Appium option building |
+
+The package assumes a running GridFleet API, a reachable Selenium Grid hub, and platform-specific Appium driver setup on the registered hosts. When auth is disabled on the manager, leave `GRIDFLEET_TESTKIT_USERNAME` / `GRIDFLEET_TESTKIT_PASSWORD` unset and the testkit will send no `Authorization` header.
+
+## Pytest Plugin
+
+Load the supported plugin from your test project:
+
+```python
+pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
+```
+
+Minimal usage:
+
+```python
+import pytest
+
+@pytest.mark.parametrize(
+    "appium_driver",
+    [{"pack_id": "appium-uiautomator2", "platform_id": "android_mobile"}],
+    indirect=True,
+)
+def test_session_starts(appium_driver):
+    assert appium_driver.session_id is not None
+```
+
+The plugin resolves `pack_id` and `platform_id` against the enabled driver-pack catalog, then injects Appium `platformName`, `appium:automationName`, `appium:platform`, and `gridfleet:testName`.
+
+When exactly one enabled pack provides a platform id, `platform_id` alone is accepted. For environment-portable tests, set `GRIDFLEET_TESTKIT_PACK_ID` and `GRIDFLEET_TESTKIT_PLATFORM_ID`, then parametrize with `{}`.
+
+If you need raw Appium control instead, omit `pack_id` and `platform_id`, then pass `platformName` as a normal capability key.
+
+### Plugin Lifecycle
+
+- Creates an Appium session through `GRID_URL`
+- 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
+- Relies on manager-owned runtime isolation for Appium driver sub-ports and XCUITest build paths
+
+## Direct Appium Usage
+
+If you need to create a driver outside pytest, use the public Appium helpers:
+
+```python
+from gridfleet_testkit import create_appium_driver, get_device_config_for_driver
+
+driver = create_appium_driver(
+    pack_id="appium-uiautomator2",
+    platform_id="firetv_real",
+    test_name="manual-smoke",
+)
+
+try:
+    assert driver.session_id is not None
+    device_config = get_device_config_for_driver(driver)
+finally:
+    driver.quit()
+```
+
+`create_appium_driver(...)` reuses the same driver-pack catalog resolver as the pytest fixture. Managed nodes still get their host-scoped runtime allocations from the manager, so callers should not hard-code `systemPort`, `chromedriverPort`, `mjpegServerPort`, `wdaLocalPort`, or `derivedDataPath`. `get_device_config_for_driver(...)` is the non-pytest equivalent of the `device_config` fixture. If you only need the options object, use `build_appium_options(...)`.
+
+## Client Helpers
+
+| Helper | Purpose |
+| --- | --- |
+| `GridFleetClient.get_device_config(connection_target, reveal=True)` | Look up a device by runtime connection target and fetch its config |
+| `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.signal_ready(run_id)` | Move a run to `ready` |
+| `GridFleetClient.signal_active(run_id)` | Move a run to `active` |
+| `GridFleetClient.heartbeat(run_id)` | Send a run heartbeat and read current state |
+| `GridFleetClient.report_preparation_failure(run_id, device_id, message, source="ci_preparation")` | Exclude one reserved device after setup fails |
+| `GridFleetClient.complete_run(run_id)` | Complete a run |
+| `GridFleetClient.cancel_run(run_id)` | Cancel a run |
+| `GridFleetClient.start_heartbeat(run_id, interval=30)` | Start a background heartbeat thread |
+| `register_run_cleanup(client, run_id, heartbeat_thread=None)` | Register `atexit` and signal cleanup that completes or cancels a run |
+
+### Reservation Flow
+
+```python
+from gridfleet_testkit import GridFleetClient, register_run_cleanup
+
+client = GridFleetClient("http://manager-ip:8000/api")
+
+run = client.reserve_devices(
+    name="my-test-run",
+    requirements=[
+        {
+            "pack_id": "appium-uiautomator2",
+            "platform_id": "firetv_real",
+            "os_version": "8",
+            "allocation": "all_available",
+            "min_count": 1,
+        }
+    ],
+    ttl_minutes=45,
+    created_by="local-dev",
+)
+
+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)
+
+# If one reserved device fails setup:
+client.report_preparation_failure(
+    run_id,
+    device_id="device-123",
+    message="Driver bootstrap timed out during CI setup",
+    source="local-dev",
+)
+
+client.signal_ready(run_id)
+client.signal_active(run_id)
+```
+
+Use `count` for exact reservations. Use `allocation: "all_available"` when CI should reserve every currently eligible matching device and size its worker pool from `len(run["devices"])`.
+
+## Examples
+
+Baseline screenshot examples:
+
+- `examples/test_android_mobile_screenshot.py`
+- `examples/test_android_tv_screenshot.py`
+- `examples/test_firetv_screenshot.py`
+- `examples/test_ios_simulator_screenshot.py`
+- `examples/test_tvos_screenshot.py`
+- `examples/test_roku_screenshot.py`
+
+Advanced example:
+
+- `examples/test_roku_sideload_screenshot.py`
+
+The baseline examples share the same flow:
+
+1. Create a session through Selenium Grid
+2. Print the resolved connection context
+3. Save a screenshot
+4. Assert that the screenshot file exists and is non-empty
+
+## Platform Notes
+
+- Android Mobile / Android TV / Fire TV:
+  - require the UiAutomator2 driver
+  - rely on Grid routing hints generated from GridFleet metadata
+- Fire TV:
+  - baseline example supports optional `appium:os_version` filtering when you need a specific Fire OS release
+- iOS simulator:
+  - baseline example intentionally targets the simulator lane with `appium:device_type=simulator`
+- tvOS:
+  - baseline example intentionally targets a real device and assumes the host already satisfies XCUITest and WebDriverAgent prerequisites
+- Roku:
+  - screenshot examples install and activate the bundled sample dev app before capture
+  - both Roku examples depend on Roku dev credentials

gridfleet_testkit-0.1.0/examples/__init__.py

@@ -0,0 +1 @@
+"""Manual hardware examples for the supported GridFleet testkit."""

gridfleet_testkit-0.1.0/examples/_example_helpers.py

@@ -0,0 +1,58 @@
+"""Shared helpers for copyable manual screenshot examples."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+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:
+    value = capabilities.get("appium:udid")
+    if isinstance(value, str) and value:
+        return value
+    session_id = capabilities.get("sessionId")
+    if isinstance(session_id, str) and session_id:
+        return session_id
+    return "session"
+
+
+def print_connection_context(driver: Any) -> str:
+    """Print the resolved session context and return the connection target string."""
+    caps = driver.capabilities
+    connection_target = _resolved_connection_target(caps)
+    platform_name = caps.get("platformName", "")
+    automation_name = caps.get("appium:automationName") or caps.get("automationName")
+    print(
+        "\nConnected to device: "
+        f"connection_target={connection_target}, "
+        f"platform={platform_name}, "
+        f"automationName={automation_name}"
+    )
+    print(f"Session ID: {driver.session_id}")
+    return connection_target
+
+
+def save_and_assert_screenshot(driver: Any, 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(":", "_")
+    SCREENSHOT_DIR.mkdir(exist_ok=True)
+    screenshot_path = SCREENSHOT_DIR / f"{example_name}_{connection_target}.png"
+    saved = driver.save_screenshot(str(screenshot_path))
+
+    assert saved, "save_screenshot returned False"
+    assert screenshot_path.exists(), f"Screenshot file not found at {screenshot_path}"
+    assert screenshot_path.stat().st_size > 0, "Screenshot file is empty"
+
+    print(f"Screenshot saved: {screenshot_path} ({screenshot_path.stat().st_size} bytes)")
+    return screenshot_path
+
+
+def install_and_activate_roku_dev_app(driver: Any) -> 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()))
+    driver.activate_app("dev")

gridfleet_testkit-0.1.0/examples/test_android_mobile_screenshot.py

@@ -0,0 +1,40 @@
+"""
+Manual baseline example: connect to an Android mobile device through Selenium Grid and take a screenshot.
+
+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]`)
+
+Run:
+    cd testkit && python -m pytest examples/test_android_mobile_screenshot.py -v -s
+"""
+
+from typing import Any
+
+import pytest
+
+from examples._example_helpers import print_connection_context, save_and_assert_screenshot
+
+pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
+
+
+@pytest.mark.parametrize(
+    "appium_driver",
+    [
+        {
+            "pack_id": "appium-uiautomator2",
+            "platform_id": "android_mobile",
+        }
+    ],
+    indirect=True,
+)
+def test_android_mobile_take_screenshot(appium_driver: Any) -> None:
+    """Connect to an Android mobile device through the Grid and take a screenshot."""
+    driver = appium_driver
+
+    assert driver.session_id is not None, "Failed to create Appium session"
+
+    print_connection_context(driver)
+    save_and_assert_screenshot(driver, "android_mobile")

gridfleet_testkit-0.1.0/examples/test_android_tv_screenshot.py

@@ -0,0 +1,40 @@
+"""
+Manual baseline example: connect to an Android TV device through Selenium Grid and take a screenshot.
+
+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]`)
+
+Run:
+    cd testkit && python -m pytest examples/test_android_tv_screenshot.py -v -s
+"""
+
+from typing import Any
+
+import pytest
+
+from examples._example_helpers import print_connection_context, save_and_assert_screenshot
+
+pytest_plugins = ["gridfleet_testkit.pytest_plugin"]
+
+
+@pytest.mark.parametrize(
+    "appium_driver",
+    [
+        {
+            "pack_id": "appium-uiautomator2",
+            "platform_id": "android_tv",
+        }
+    ],
+    indirect=True,
+)
+def test_android_tv_take_screenshot(appium_driver: Any) -> None:
+    """Connect to an Android TV device through the Grid and take a screenshot."""
+    driver = appium_driver
+
+    assert driver.session_id is not None, "Failed to create Appium session"
+
+    print_connection_context(driver)
+    save_and_assert_screenshot(driver, "android_tv")