edgelens-pytest 0.2.1__tar.gz

edgelens_pytest-0.2.1/.gitignore

@@ -0,0 +1,9 @@
+.venv
+__pycache__
+*.egg-info
+dist
+build
+.pytest_cache
+.mypy_cache
+.ruff_cache
+*.pyc

edgelens_pytest-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EdgeLens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edgelens_pytest-0.2.1/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.5
+Name: edgelens-pytest
+Version: 0.2.1
+Summary: pytest plugin for EdgeLens — per-session/per-test camera fixtures, CLI options, JUnit metadata.
+Project-URL: Homepage, https://edgelens.ai
+Project-URL: Repository, https://github.com/edgelens-ai/edgelens-sdk
+Project-URL: Issues, https://github.com/edgelens-ai/edgelens-sdk/issues
+Author-email: EdgeLens <support@edgelens.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: edgelens,pytest,pytest-plugin,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Requires-Dist: edgelens-sdk<0.3,>=0.2.1
+Requires-Dist: pytest>=7.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# edgelens-pytest
+
+pytest plugin for the EdgeLens Edge AI Device Farm — write a test that
+gets a real edge AI camera as a fixture, with auto-allocate, auto-
+release, configurable scope, OS filtering, and JUnit metadata.
+
+Counterpart to [`@edgelens/playwright-plugin`](../playwright) for
+the Python world.
+
+## Install
+
+```sh
+pip install edgelens-pytest
+```
+
+Requires Python 3.9+. Auto-loaded by pytest via the `pytest11` entry
+point — no `conftest.py` glue needed.
+
+## Quickstart
+
+```python
+# tests/test_camera.py
+def test_inference_latency(device):
+    device.deploy(model="./face.cvimodel")
+    device.inference.start()
+    stats = device.inference.run(duration=30)
+    assert stats.fps.avg > 15
+    assert stats.latency_ms.p95 < 100
+```
+
+Run it:
+
+```sh
+export EDGELENS_API_KEY=el_test_xxx
+pytest
+```
+
+`device` is **session-scoped** by default — one camera for the whole
+run. Use `--edgelens-scope=module` or `--edgelens-scope=function` if
+tests mutate device state in ways the next test would inherit broken.
+
+## Fixtures
+
+| Fixture | Scope | What |
+|---|---|---|
+| `device` | session/module/function (CLI) | `edgelens.Device` ready to use |
+| `edgelens_session` | same as `device` | `edgelens.Session`, already past `wait_ready()` |
+| `edgelens_client` | session | `edgelens.EdgeLensClient` |
+| `edgelens_options` | session | `EdgelensOptions` derived from CLI + env |
+
+## CLI options
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--edgelens-key` | — | API key. Prefer `$EDGELENS_API_KEY`: a value on the command line is visible in the process list and shell history. |
+| `--edgelens-base-url` | — | Self-hosted EdgeLens deployments. |
+| `--edgelens-os` | `stock-os` | OS to flash. Alt: `recamagined`. |
+| `--edgelens-device-type` | `recamera-2002` | Device type to allocate. |
+| `--edgelens-scope` | `session` | `session` / `module` / `function`. |
+| `--edgelens-session-timeout` | `3600` | Session duration cap (s). |
+| `--edgelens-skip-allocation` | off | Fixtures yield `None`. For plugin-self-testing. |
+
+`wait_ready` does not need a client-side timeout: the platform
+signals a readiness deadline on the session response and the
+SDK trusts it. `--edgelens-wait-timeout` is a deprecated
+escape hatch; setting it emits a `PytestDeprecationWarning`.
+
+## OS marker
+
+Pin a test to a specific OS via `@pytest.mark.edgelens(os=...)`:
+
+```python
+import pytest
+
+@pytest.mark.edgelens(os="recamagined")
+def test_recamagined_only(device):
+    ...
+
+@pytest.mark.edgelens(os="stock-os")
+def test_stock_only(device):
+    ...
+
+def test_works_on_either(device):
+    ...
+```
+
+Run once per OS:
+
+```sh
+pytest --edgelens-os=stock-os
+pytest --edgelens-os=recamagined
+```
+
+Marker mismatches surface as `pytest.mark.skip` with a clear reason, so
+the report tells you why a test was excluded.
+
+The same pattern works for `device_type`:
+
+```python
+@pytest.mark.edgelens(device_type="some-other-device")
+def test_only_for_other(device):
+    ...
+```
+
+## Multi-OS coverage
+
+The fixture is session-scoped by default — one camera for the run.
+Mixing OS variants under a single scope would require multiple sessions,
+which we deliberately don't support implicitly (allocations cost money
++ wall-clock time).
+
+To cover multiple OS variants in CI, run pytest once per OS:
+
+```yaml
+# .github/workflows/edgelens-matrix.yml
+strategy:
+  matrix:
+    os: [stock, recamagined]
+steps:
+  - uses: actions/checkout@v4
+  - uses: edgelens-ai/edgelens-sdk/ci/github-action@v0.2.1
+    with:
+      api-key: ${{ secrets.EDGELENS_API_KEY }}
+      command: pytest --edgelens-os=${{ matrix.os }} --junit-xml=junit.xml
+```
+
+For fine-grained per-test OS switching inside a single run, drop the
+fixture scope to `function` and add a custom `os_variant` parametrize
+in your own `conftest.py` (see the SDK example projects).
+
+## JUnit metadata
+
+Each test's testcase in the JUnit XML gets these extra `<property>`
+entries:
+
+- `edgelens_session_id`
+- `edgelens_mac`
+- `edgelens_host`
+- `edgelens_os`
+
+So the GitLab MR widget / GitHub Action summary / CI dashboard can show
+*which camera ran which test* without parsing logs.
+
+## Develop
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## See also
+
+Pairs with `@edgelens/playwright-plugin` for JS/TS teams.

edgelens_pytest-0.2.1/README.md

@@ -0,0 +1,154 @@
+# edgelens-pytest
+
+pytest plugin for the EdgeLens Edge AI Device Farm — write a test that
+gets a real edge AI camera as a fixture, with auto-allocate, auto-
+release, configurable scope, OS filtering, and JUnit metadata.
+
+Counterpart to [`@edgelens/playwright-plugin`](../playwright) for
+the Python world.
+
+## Install
+
+```sh
+pip install edgelens-pytest
+```
+
+Requires Python 3.9+. Auto-loaded by pytest via the `pytest11` entry
+point — no `conftest.py` glue needed.
+
+## Quickstart
+
+```python
+# tests/test_camera.py
+def test_inference_latency(device):
+    device.deploy(model="./face.cvimodel")
+    device.inference.start()
+    stats = device.inference.run(duration=30)
+    assert stats.fps.avg > 15
+    assert stats.latency_ms.p95 < 100
+```
+
+Run it:
+
+```sh
+export EDGELENS_API_KEY=el_test_xxx
+pytest
+```
+
+`device` is **session-scoped** by default — one camera for the whole
+run. Use `--edgelens-scope=module` or `--edgelens-scope=function` if
+tests mutate device state in ways the next test would inherit broken.
+
+## Fixtures
+
+| Fixture | Scope | What |
+|---|---|---|
+| `device` | session/module/function (CLI) | `edgelens.Device` ready to use |
+| `edgelens_session` | same as `device` | `edgelens.Session`, already past `wait_ready()` |
+| `edgelens_client` | session | `edgelens.EdgeLensClient` |
+| `edgelens_options` | session | `EdgelensOptions` derived from CLI + env |
+
+## CLI options
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--edgelens-key` | — | API key. Prefer `$EDGELENS_API_KEY`: a value on the command line is visible in the process list and shell history. |
+| `--edgelens-base-url` | — | Self-hosted EdgeLens deployments. |
+| `--edgelens-os` | `stock-os` | OS to flash. Alt: `recamagined`. |
+| `--edgelens-device-type` | `recamera-2002` | Device type to allocate. |
+| `--edgelens-scope` | `session` | `session` / `module` / `function`. |
+| `--edgelens-session-timeout` | `3600` | Session duration cap (s). |
+| `--edgelens-skip-allocation` | off | Fixtures yield `None`. For plugin-self-testing. |
+
+`wait_ready` does not need a client-side timeout: the platform
+signals a readiness deadline on the session response and the
+SDK trusts it. `--edgelens-wait-timeout` is a deprecated
+escape hatch; setting it emits a `PytestDeprecationWarning`.
+
+## OS marker
+
+Pin a test to a specific OS via `@pytest.mark.edgelens(os=...)`:
+
+```python
+import pytest
+
+@pytest.mark.edgelens(os="recamagined")
+def test_recamagined_only(device):
+    ...
+
+@pytest.mark.edgelens(os="stock-os")
+def test_stock_only(device):
+    ...
+
+def test_works_on_either(device):
+    ...
+```
+
+Run once per OS:
+
+```sh
+pytest --edgelens-os=stock-os
+pytest --edgelens-os=recamagined
+```
+
+Marker mismatches surface as `pytest.mark.skip` with a clear reason, so
+the report tells you why a test was excluded.
+
+The same pattern works for `device_type`:
+
+```python
+@pytest.mark.edgelens(device_type="some-other-device")
+def test_only_for_other(device):
+    ...
+```
+
+## Multi-OS coverage
+
+The fixture is session-scoped by default — one camera for the run.
+Mixing OS variants under a single scope would require multiple sessions,
+which we deliberately don't support implicitly (allocations cost money
++ wall-clock time).
+
+To cover multiple OS variants in CI, run pytest once per OS:
+
+```yaml
+# .github/workflows/edgelens-matrix.yml
+strategy:
+  matrix:
+    os: [stock, recamagined]
+steps:
+  - uses: actions/checkout@v4
+  - uses: edgelens-ai/edgelens-sdk/ci/github-action@v0.2.1
+    with:
+      api-key: ${{ secrets.EDGELENS_API_KEY }}
+      command: pytest --edgelens-os=${{ matrix.os }} --junit-xml=junit.xml
+```
+
+For fine-grained per-test OS switching inside a single run, drop the
+fixture scope to `function` and add a custom `os_variant` parametrize
+in your own `conftest.py` (see the SDK example projects).
+
+## JUnit metadata
+
+Each test's testcase in the JUnit XML gets these extra `<property>`
+entries:
+
+- `edgelens_session_id`
+- `edgelens_mac`
+- `edgelens_host`
+- `edgelens_os`
+
+So the GitLab MR widget / GitHub Action summary / CI dashboard can show
+*which camera ran which test* without parsing logs.
+
+## Develop
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## See also
+
+Pairs with `@edgelens/playwright-plugin` for JS/TS teams.

edgelens_pytest-0.2.1/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "edgelens-pytest"
+dynamic = ["version"]
+description = "pytest plugin for EdgeLens — per-session/per-test camera fixtures, CLI options, JUnit metadata."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "EdgeLens", email = "support@edgelens.ai" }]
+requires-python = ">=3.9"
+keywords = ["pytest", "pytest-plugin", "edgelens", "testing"]
+classifiers = [
+    "Framework :: Pytest",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "edgelens-sdk>=0.2.1,<0.3",
+    "pytest>=7.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.1",
+    "mypy>=1.0",
+]
+
+[project.entry-points.pytest11]
+pytest_edgelens = "pytest_edgelens.plugin"
+
+[project.urls]
+Homepage = "https://edgelens.ai"
+Repository = "https://github.com/edgelens-ai/edgelens-sdk"
+Issues = "https://github.com/edgelens-ai/edgelens-sdk/issues"
+
+[tool.hatch.build.targets.sdist]
+include = ["/pytest_edgelens", "/README.md", "/LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["pytest_edgelens"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.mypy]
+strict = true
+python_version = "3.9"
+
+[tool.hatch.version]
+path = "pytest_edgelens/__init__.py"

edgelens_pytest-0.2.1/pytest_edgelens/__init__.py

@@ -0,0 +1,7 @@
+"""pytest plugin for the EdgeLens Edge AI Device Farm.
+
+Auto-loaded by pytest via the ``pytest11`` entry point in
+``pyproject.toml``. No need to add anything to your ``conftest.py``.
+"""
+
+__version__ = "0.2.1"

edgelens_pytest-0.2.1/pytest_edgelens/lifecycle.py

@@ -0,0 +1,135 @@
+"""Fixture lifecycle helpers — the actual session allocation + release
+logic, kept separate from ``plugin.py`` so it can be unit-tested
+without pytester.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import dataclass, field, fields
+from typing import Any, Optional
+
+from edgelens import EdgeLensClient, Session
+
+logger = logging.getLogger(__name__)
+
+
+def _fingerprint(api_key: Optional[str]) -> str:
+    """Render a key so two different keys look different and neither is readable.
+
+    A prefix would do the first but not the second: a prefix of a
+    secret is a piece of the secret, which is why the platform's own
+    truncated key display is not reusable here. Six hex characters of
+    sha256 identify a key to someone who already has it and give
+    nothing to someone who does not.
+    """
+    if api_key is None:
+        return "None"
+    return f"<set sha256:{hashlib.sha256(api_key.encode()).hexdigest()[:6]}>"
+
+
+@dataclass
+class EdgelensOptions:
+    api_key: Optional[str] = field(default=None, repr=False)
+    base_url: Optional[str] = None
+    device_type: str = "recamera-2002"
+    os: str = "stock-os"
+    image_version: Optional[str] = None
+    session_timeout_s: int = 3600
+    # None (default) trusts the server's `deadline` field;
+    # an explicit int is a caller-supplied ceiling override.
+    wait_ready_timeout_s: Optional[int] = None
+    poll_interval_s: float = 2.0
+    skip_allocation: bool = False
+
+    def __repr__(self) -> str:
+        # pytest renders fixture arguments when setup raises, so this
+        # is what reaches a customer's CI log on a failed allocation.
+        shown = [f"api_key={_fingerprint(self.api_key)}"]
+        shown += [
+            f"{f.name}={getattr(self, f.name)!r}" for f in fields(self) if f.repr
+        ]
+        return f"{type(self).__name__}({', '.join(shown)})"
+
+
+def build_client(opts: EdgelensOptions) -> EdgeLensClient:
+    """Construct the underlying EdgeLensClient.
+
+    Reads the API key from the options or falls through to the SDK's
+    own env-var fallback (``EDGELENS_API_KEY``). The SDK raises
+    ``AuthenticationError`` when neither is set; we let it propagate
+    so pytest reports it as a fixture-setup failure with the right
+    pointer.
+    """
+    kwargs: dict[str, Any] = {}
+    if opts.api_key:
+        kwargs["api_key"] = opts.api_key
+    if opts.base_url:
+        kwargs["base_url"] = opts.base_url
+    return EdgeLensClient(**kwargs)
+
+
+def allocate_session(client: EdgeLensClient, opts: EdgelensOptions) -> Session:
+    """Create a session and wait for ready.
+
+    Errors from create_session propagate directly. Anything raised by
+    wait_ready triggers a synchronous ``session.release()`` before
+    re-raising — otherwise the api-side session is orphaned (the
+    fixture teardown only sees the return value, and there is no
+    return value on the exceptional path) and it leaks until the
+    server-side timeout (~1h), blocking the next allocation with
+    ``max_concurrent_sessions`` violations.
+
+    ``BaseException`` and not ``Exception``, because the likeliest way
+    this wait ever ends early is someone pressing Ctrl-C, and
+    ``KeyboardInterrupt`` is not an ``Exception``. The wait prints
+    nothing and can run for half an hour, so an operator watching a
+    silent terminal interrupts it long before it times out. A guard
+    that caught only ``Exception`` would miss the most likely trigger
+    and leak the session.
+
+    A plain ``try``/``finally`` would be wrong here: this returns the
+    live session on the success path, and a ``finally`` would release
+    it the moment it became ready.
+    """
+    session = client.create_session(
+        device_type=opts.device_type,
+        os=opts.os,
+        timeout=opts.session_timeout_s,
+        image_version=opts.image_version,
+    )
+    try:
+        session.wait_ready(
+            timeout=opts.wait_ready_timeout_s,
+            poll_interval=opts.poll_interval_s,
+        )
+    except BaseException:
+        try:
+            session.release()
+        # Deliberately narrower than the guard above. A second
+        # interrupt arriving while the release is in flight belongs to
+        # the operator insisting, and must not be turned into a log
+        # line — there is nothing left to protect by then anyway.
+        except Exception as release_exc:  # noqa: BLE001
+            logger.warning(
+                "edgelens session release failed during allocate_session "
+                "cleanup: %s (primary error follows)", release_exc,
+            )
+        raise
+    return session
+
+
+def release_session(session: Optional[Session]) -> None:
+    """Release a session, swallowing teardown errors.
+
+    A failed release shouldn't mask the actual test failure that
+    happened before it — pytest already records the test outcome by
+    the time fixture teardown runs.
+    """
+    if session is None:
+        return
+    try:
+        session.release()
+    except Exception as e:  # noqa: BLE001
+        logger.warning("edgelens session release failed: %s", e)

edgelens_pytest-0.2.1/pytest_edgelens/plugin.py

@@ -0,0 +1,307 @@
+"""pytest_edgelens plugin module.
+
+Adds CLI options, fixtures, and JUnit metadata for tests that need a
+real EdgeLens camera. Auto-loaded via the ``pytest11`` entry point.
+
+Fixtures
+--------
+- ``edgelens_options`` — CLI/env-derived ``EdgelensOptions`` (session)
+- ``edgelens_client`` — single ``EdgeLensClient`` for the run (session)
+- ``edgelens_session`` — allocated ``Session``, scope per ``--edgelens-scope``
+- ``device`` — the ``Device`` from the session (same scope)
+
+Markers
+-------
+- ``@pytest.mark.edgelens(os="recamagined")`` — skip the test unless
+  the active ``--edgelens-os`` matches the marker. Pairs with running
+  pytest once per OS instead of mixing scopes.
+
+CLI options
+-----------
+- ``--edgelens-key`` (env ``EDGELENS_API_KEY``)
+- ``--edgelens-base-url``
+- ``--edgelens-os`` (default ``stock-os``)
+- ``--edgelens-device-type`` (default ``recamera-2002``)
+- ``--edgelens-image-version`` (default ``None`` — platform picks)
+- ``--edgelens-scope`` (``session``/``module``/``function``, default ``session``)
+- ``--edgelens-session-timeout`` (seconds, default 3600)
+- ``--edgelens-wait-timeout`` (seconds; **DEPRECATED** —
+  wait_ready is now server-driven via the server's ``deadline`` field. The
+  flag remains for one release as an explicit ceiling override, and
+  emits a ``PytestDeprecationWarning`` when set.)
+- ``--edgelens-skip-allocation`` — skip any test that requests
+  ``edgelens_session``/``device`` (no platform call), for testing the
+  plugin itself and collect-only runs.
+
+JUnit metadata
+--------------
+On each test, the session id, device mac, host, os, and device-type are
+recorded as ``<property>`` entries so JUnit consumers (GitLab MR
+widget, GitHub Action summary, etc.) can show which device a test ran
+on without parsing logs.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import pytest
+
+from pytest_edgelens import lifecycle
+from pytest_edgelens.lifecycle import EdgelensOptions
+
+
+SCOPES = ("session", "module", "function")
+DEFAULT_SCOPE = "session"
+
+
+# ---- CLI options + marker registration --------------------------------------
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("edgelens", "EdgeLens device-farm options")
+    group.addoption(
+        "--edgelens-key", default=None,
+        help=(
+            "EdgeLens API key. Prefer EDGELENS_API_KEY: a key on the "
+            "command line is visible in the process list and CI logs."
+        ),
+    )
+    group.addoption(
+        "--edgelens-base-url", default=None,
+        help="Override the platform API base URL.",
+    )
+    group.addoption(
+        "--edgelens-os", default="stock-os",
+        help="OS to flash (default: stock-os; alt: recamagined).",
+    )
+    group.addoption(
+        "--edgelens-device-type", default="recamera-2002",
+        help="Device type to allocate (default: recamera-2002).",
+    )
+    group.addoption(
+        "--edgelens-image-version", default=None,
+        help=(
+            "OS image version to flash. Omit to let the platform pick "
+            "its default for --edgelens-os."
+        ),
+    )
+    group.addoption(
+        "--edgelens-scope", default=DEFAULT_SCOPE, choices=SCOPES,
+        help=(
+            "Fixture scope for `edgelens_session` and `device`. "
+            "Default: session (cheapest — one camera for the whole run). "
+            "Use module/function for fresh-per-module/test when tests mutate "
+            "device state in ways the previous test would leave broken."
+        ),
+    )
+    group.addoption(
+        "--edgelens-session-timeout", default=3600, type=int,
+        help="Max session duration in seconds (default: 3600).",
+    )
+    group.addoption(
+        "--edgelens-wait-timeout", default=None, type=int,
+        help=(
+            "DEPRECATED: wait_ready is now server-driven via "
+            "the server's `deadline` field — the platform commits to a "
+            "readiness deadline and the SDK trusts it. This flag "
+            "remains for one release as an explicit ceiling override "
+            "(shortens the wait; never extends past the server "
+            "deadline). Emits PytestDeprecationWarning when set."
+        ),
+    )
+    group.addoption(
+        "--edgelens-skip-allocation", action="store_true", default=False,
+        help=(
+            "Skip session allocation. Tests that request "
+            "`edgelens_session`/`device` are skipped (not passed a None "
+            "device). Useful for testing the plugin itself or collect-only "
+            "runs."
+        ),
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line(
+        "markers",
+        "edgelens(os=None, device_type=None): "
+        "constrain a test to a specific (os, device_type). The test is "
+        "skipped when --edgelens-os/--edgelens-device-type don't match.",
+    )
+
+
+# ---- Options + client + session fixtures -----------------------------------
+
+
+@pytest.fixture(scope="session")
+def edgelens_options(request: pytest.FixtureRequest) -> EdgelensOptions:
+    cfg = request.config
+    api_key = cfg.getoption("--edgelens-key") or os.environ.get("EDGELENS_API_KEY")
+    wait_ready_timeout_s = cfg.getoption("--edgelens-wait-timeout")
+    if wait_ready_timeout_s is not None:
+        # warn when the deprecated flag is actually set. Absent
+        # (default None) means the SDK trusts the server-signaled
+        # deadline; no warning noise.
+        import warnings
+        warnings.warn(
+            "--edgelens-wait-timeout is deprecated — wait_ready "
+            "is now server-driven via the server's `deadline` field. Remove the "
+            "flag unless you specifically need to shorten the wait for "
+            "abort-early / testing.",
+            pytest.PytestDeprecationWarning,
+            stacklevel=2,
+        )
+    return EdgelensOptions(
+        api_key=api_key,
+        base_url=cfg.getoption("--edgelens-base-url"),
+        device_type=cfg.getoption("--edgelens-device-type"),
+        os=cfg.getoption("--edgelens-os"),
+        image_version=cfg.getoption("--edgelens-image-version"),
+        session_timeout_s=cfg.getoption("--edgelens-session-timeout"),
+        wait_ready_timeout_s=wait_ready_timeout_s,
+        skip_allocation=cfg.getoption("--edgelens-skip-allocation"),
+    )
+
+
+@pytest.fixture(scope="session")
+def edgelens_client(edgelens_options: EdgelensOptions):  # type: ignore[no-untyped-def]
+    if edgelens_options.skip_allocation:
+        yield None
+        return
+    client = lifecycle.build_client(edgelens_options)
+    try:
+        yield client
+    finally:
+        client.close()
+
+
+def _dynamic_scope(*, fixture_name: str, config: pytest.Config) -> str:
+    del fixture_name  # unused
+    return str(config.getoption("--edgelens-scope") or DEFAULT_SCOPE)
+
+
+@pytest.fixture(scope=_dynamic_scope)  # type: ignore[arg-type]
+def edgelens_session(
+    edgelens_client, edgelens_options: EdgelensOptions
+):  # type: ignore[no-untyped-def]
+    if edgelens_options.skip_allocation or edgelens_client is None:
+        # Skip — don't hand back a None session that the test would
+        # then dereference into an AttributeError.
+        pytest.skip("edgelens allocation disabled (--edgelens-skip-allocation)")
+    session = lifecycle.allocate_session(edgelens_client, edgelens_options)
+    try:
+        yield session
+    finally:
+        lifecycle.release_session(session)
+
+
+@pytest.fixture(scope=_dynamic_scope)  # type: ignore[arg-type]
+def device(edgelens_session):  # type: ignore[no-untyped-def]
+    # edgelens_session skips under --edgelens-skip-allocation, so a test
+    # reaching here always has a real session.
+    return edgelens_session.device
+
+
+# ---- Marker handling: skip mismatched (os, device_type) --------------------
+
+
+def pytest_collection_modifyitems(
+    config: pytest.Config, items: list[pytest.Item]
+) -> None:
+    active_os = config.getoption("--edgelens-os")
+    active_device = config.getoption("--edgelens-device-type")
+    for item in items:
+        marker = item.get_closest_marker("edgelens")
+        if marker is None:
+            continue
+        required_os = marker.kwargs.get("os")
+        required_device = marker.kwargs.get("device_type")
+        if required_os is not None and required_os != active_os:
+            item.add_marker(
+                pytest.mark.skip(
+                    reason=(
+                        f"requires --edgelens-os={required_os}, "
+                        f"got {active_os}"
+                    )
+                )
+            )
+        if required_device is not None and required_device != active_device:
+            item.add_marker(
+                pytest.mark.skip(
+                    reason=(
+                        f"requires --edgelens-device-type={required_device}, "
+                        f"got {active_device}"
+                    )
+                )
+            )
+
+
+# ---- JUnit metadata: stamp device + session info on each testcase -----------
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(
+    item: pytest.Item, call: pytest.CallInfo  # type: ignore[type-arg]
+):  # type: ignore[no-untyped-def]
+    outcome = yield
+    if call.when != "call":
+        return
+    # Look up the session fixture without forcing it (avoid triggering
+    # allocation for tests that didn't ask for it).
+    request: Optional[pytest.FixtureRequest] = getattr(item, "_request", None)
+    if request is None:
+        return
+    cache = getattr(request, "_fixture_defs", None) or {}
+    fixturedef = cache.get("edgelens_session")
+    if fixturedef is None or fixturedef.cached_result is None:
+        return
+    session = fixturedef.cached_result[0]
+    if session is None:
+        return
+
+    # Stash the live session on the terminal reporter so
+    # pytest_terminal_summary can print it without forcing a new
+    # allocation. Set here (only when a test actually used the session)
+    # rather than via an autouse fixture that would allocate on every run.
+    reporter = item.config.pluginmanager.getplugin("terminalreporter")
+    if reporter is not None:
+        reporter._edgelens_session = session  # type: ignore[attr-defined]
+
+    report = outcome.get_result()
+    user_props = list(getattr(report, "user_properties", []) or [])
+    user_props.append(("edgelens_session_id", session.id))
+    conn = getattr(session, "_connection", None)
+    if conn is not None:
+        user_props.extend(
+            [
+                ("edgelens_mac", conn.mac),
+                ("edgelens_host", conn.host),
+                ("edgelens_os", conn.os.value),
+            ]
+        )
+    report.user_properties = user_props
+
+
+# ---- Terminal summary line -------------------------------------------------
+
+
+# The session shown here is stashed on the
+# terminal reporter by pytest_runtest_makereport — only when a test
+# actually used `edgelens_session`. No autouse fixture, so a
+# --collect-only / plugin-only / no-device run never forces a PAID
+# allocation just to print a summary.
+def pytest_terminal_summary(terminalreporter, exitstatus, config):  # type: ignore[no-untyped-def]
+    if config.getoption("--collect-only", default=False):
+        return
+    if config.getoption("--edgelens-skip-allocation", default=False):
+        return
+    # Only read the session captured during the run; never allocate here.
+    session = getattr(terminalreporter, "_edgelens_session", None)
+    if session is None:
+        return
+    terminalreporter.write_sep("-", "edgelens", bold=True)
+    terminalreporter.write_line(
+        f"session {session.id} ({config.getoption('--edgelens-device-type')} / "
+        f"{config.getoption('--edgelens-os')})"
+    )