kensho-pytest 0.1.1__tar.gz

kensho_pytest-0.1.1/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: kensho-pytest
+Version: 0.1.1
+Summary: Kensho reporter for pytest — writes kensho-results/ so the Kensho CLI can generate a rich HTML report.
+Author: KaizenReport
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/kaizenreport/kensho
+Project-URL: Source, https://github.com/kaizenreport/kensho
+Keywords: pytest,kensho,kaizenreport,test-report,reporter
+Classifier: Framework :: Pytest
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pytest>=7.0
+
+# kensho-pytest
+
+A pytest plugin that emits the canonical [Kensho v1](../schema) JSON format.
+Run your tests, then point the `kensho` CLI at `kensho-results/` to get a
+self-contained static HTML report.
+
+## Install
+
+```bash
+pip install kensho-pytest
+# or, in this monorepo:
+pip install -e packages/pytest
+```
+
+The plugin auto-registers via the `pytest11` entry point — no `conftest.py`
+edits required.
+
+## Run
+
+```bash
+pytest
+# => kensho-results/run.json + kensho-results/cases/*.json
+
+# Generate the HTML report (uses the JS CLI from the same monorepo):
+npx kensho generate
+npx kensho open
+```
+
+## CLI flags
+
+```
+--kensho-output PATH                Output dir (default: ./kensho-results)
+--kensho-project-name STR           Project name in run.json
+--kensho-project-slug STR           Project slug (lowercase, alnum + dash/underscore)
+--kensho-run-id STR                 Override the auto-generated run id
+--kensho-no-severity-from-marks     Don't promote @pytest.mark.<severity> to case.severity
+```
+
+`pytest.ini` / `pyproject.toml` `[tool.pytest.ini_options]` keys are also
+respected: `kensho_output`, `kensho_project_name`, `kensho_project_slug`.
+
+## What it produces
+
+- `kensho-results/run.json` — run manifest (project, env, totals, timing).
+- `kensho-results/cases/<stableId>.json` — one file per test case.
+- `kensho-results/attachments/<caseId>/...` — files registered via
+  `kensho_pytest.attach`.
+
+Each case gets a **stable id** (`tc_<16 hex>`) hashed from its `nodeid` +
+file path, so test history correlates across runs and across adapters
+(the JS adapters use the same FNV-1a-based hash).
+
+## Markers we read
+
+| Marker                                          | Effect                                                    |
+| ----------------------------------------------- | --------------------------------------------------------- |
+| `@pytest.mark.severity('critical')`             | Sets `case.severity`. Allowed values: `blocker`, `critical`, `normal`, `minor`, `trivial`. |
+| `@pytest.mark.blocker` / `critical` / `normal` / `minor` / `trivial` | Shorthand alias for the above.    |
+| `@pytest.mark.feature('Cart')`                  | Sets `case.behavior.feature`.                             |
+| `@pytest.mark.epic('Checkout')`                 | Sets `case.behavior.epic`.                                |
+| `@pytest.mark.story('Empty cart shows CTA')`    | Sets `case.behavior.scenario`.                            |
+| `@pytest.mark.description('Long-form...')`      | Sets `case.description`.                                  |
+| `@pytest.mark.owner('alice')`                   | Sets `case.owner`.                                        |
+| `@pytest.mark.kensho_label(team='cart')`        | Adds free-form `key=value` to `case.labels` (string only). |
+| `@pytest.mark.kensho_link(kind='jira', url='https://…', label='PROJ-123')` | Adds an entry to `case.links`. |
+| `@pytest.mark.parametrize(...)`                 | Each parametrized case gets `case.parameters[]`.          |
+
+Inline `@tag` syntax in test names (`def test_foo_at_smoke()` or
+`pytest.param(..., id="x@smoke")`) is also picked up as a tag, mirroring
+the JS adapters.
+
+## Helper API
+
+Import the helpers from `kensho_pytest`. All four are no-ops outside a
+running test, so it's safe to call them from shared utility code.
+
+```python
+import kensho_pytest as kensho
+
+def test_login(page):
+    with kensho.step("open the login page"):
+        page.goto("/login")
+
+    with kensho.step("submit credentials"):
+        page.fill("#user", "demo")
+        page.click("text=Sign in")
+        # nesting works — child steps roll up under the parent
+        with kensho.step("verify redirect"):
+            assert page.url.endswith("/home")
+
+    kensho.label("team", "growth")
+    kensho.link("https://jira.example.com/browse/PROJ-123",
+                kind="jira", label_text="PROJ-123")
+
+    page.screenshot(path="/tmp/login.png")
+    kensho.attach("/tmp/login.png", kind="screenshot")
+```
+
+| Helper                                    | What it does                                            |
+| ----------------------------------------- | ------------------------------------------------------- |
+| `with kensho.step(title, action=None):`   | Opens a Kensho step. Nests automatically. On exception the step is marked `fail` and the exception re-raises. |
+| `kensho.attach(path, kind=None, name=None, mime_type=None)` | Copies the file into `kensho-results/attachments/<caseId>/` and registers it on the current case (or current step, if one is open). |
+| `kensho.label(key, value)`                | Adds a string label to the case.                        |
+| `kensho.link(url, kind=None, label_text=None)` | Adds a hyperlink to the case.                       |
+| `kensho.current_case_id()`                | Returns the stable case id of the running test, or `None`. |
+
+## Captured output → logs
+
+Pytest's captured stdout / stderr / `caplog` for each phase (setup, call,
+teardown) is converted to entries in `case.logs[]`. The `t` field is the
+millisecond offset from the test start.
+
+## Errors
+
+`call` failures map to `status: 'fail'`; `setup` / `teardown` failures map
+to `status: 'broken'` (these are infrastructure, not real assertion
+failures). Skips at any phase map to `status: 'skip'`. The full
+`longrepr` is preserved in `case.errors[].stack`; the first line becomes
+`case.errors[].message`.
+
+## Environment auto-detected
+
+GitHub Actions, CircleCI, GitLab CI, Jenkins, Buildkite, Azure DevOps —
+CI provider, branch, commit, run URL, OS, architecture, Python version.
+
+Pass `KR_AUTHOR`, `KR_COMMIT_MSG`, `KR_STAGE`, `KR_BASE_URL`,
+`KR_APP_VERSION`, `KR_BUILD_NUMBER`, `KR_RELEASE`, `KR_REGION`,
+`KR_LOCALE`, `KR_TRIGGER`, or `KR_FEATURE` as env vars to populate the
+matching fields on `run.env`.
+
+## Design notes
+
+* Zero runtime dependencies beyond `pytest` itself. The schema lives in
+  the JS workspace; we vendor the minimum (id-hashing, status mapping,
+  env capture) inline so the adapter installs in seconds.
+* The reporter never raises out of a hook — a broken adapter must not
+  break a test run. All errors come out as `warnings.warn`.
+* IDs are stable across adapters: the FNV-1a hash matches the JS
+  `stableCaseId` byte-for-byte, so `pytest` and `playwright` runs of
+  the same suite roll up to the same history on the platform.
+
+## License
+
+Apache-2.0.

kensho_pytest-0.1.1/README.md

@@ -0,0 +1,144 @@
+# kensho-pytest
+
+A pytest plugin that emits the canonical [Kensho v1](../schema) JSON format.
+Run your tests, then point the `kensho` CLI at `kensho-results/` to get a
+self-contained static HTML report.
+
+## Install
+
+```bash
+pip install kensho-pytest
+# or, in this monorepo:
+pip install -e packages/pytest
+```
+
+The plugin auto-registers via the `pytest11` entry point — no `conftest.py`
+edits required.
+
+## Run
+
+```bash
+pytest
+# => kensho-results/run.json + kensho-results/cases/*.json
+
+# Generate the HTML report (uses the JS CLI from the same monorepo):
+npx kensho generate
+npx kensho open
+```
+
+## CLI flags
+
+```
+--kensho-output PATH                Output dir (default: ./kensho-results)
+--kensho-project-name STR           Project name in run.json
+--kensho-project-slug STR           Project slug (lowercase, alnum + dash/underscore)
+--kensho-run-id STR                 Override the auto-generated run id
+--kensho-no-severity-from-marks     Don't promote @pytest.mark.<severity> to case.severity
+```
+
+`pytest.ini` / `pyproject.toml` `[tool.pytest.ini_options]` keys are also
+respected: `kensho_output`, `kensho_project_name`, `kensho_project_slug`.
+
+## What it produces
+
+- `kensho-results/run.json` — run manifest (project, env, totals, timing).
+- `kensho-results/cases/<stableId>.json` — one file per test case.
+- `kensho-results/attachments/<caseId>/...` — files registered via
+  `kensho_pytest.attach`.
+
+Each case gets a **stable id** (`tc_<16 hex>`) hashed from its `nodeid` +
+file path, so test history correlates across runs and across adapters
+(the JS adapters use the same FNV-1a-based hash).
+
+## Markers we read
+
+| Marker                                          | Effect                                                    |
+| ----------------------------------------------- | --------------------------------------------------------- |
+| `@pytest.mark.severity('critical')`             | Sets `case.severity`. Allowed values: `blocker`, `critical`, `normal`, `minor`, `trivial`. |
+| `@pytest.mark.blocker` / `critical` / `normal` / `minor` / `trivial` | Shorthand alias for the above.    |
+| `@pytest.mark.feature('Cart')`                  | Sets `case.behavior.feature`.                             |
+| `@pytest.mark.epic('Checkout')`                 | Sets `case.behavior.epic`.                                |
+| `@pytest.mark.story('Empty cart shows CTA')`    | Sets `case.behavior.scenario`.                            |
+| `@pytest.mark.description('Long-form...')`      | Sets `case.description`.                                  |
+| `@pytest.mark.owner('alice')`                   | Sets `case.owner`.                                        |
+| `@pytest.mark.kensho_label(team='cart')`        | Adds free-form `key=value` to `case.labels` (string only). |
+| `@pytest.mark.kensho_link(kind='jira', url='https://…', label='PROJ-123')` | Adds an entry to `case.links`. |
+| `@pytest.mark.parametrize(...)`                 | Each parametrized case gets `case.parameters[]`.          |
+
+Inline `@tag` syntax in test names (`def test_foo_at_smoke()` or
+`pytest.param(..., id="x@smoke")`) is also picked up as a tag, mirroring
+the JS adapters.
+
+## Helper API
+
+Import the helpers from `kensho_pytest`. All four are no-ops outside a
+running test, so it's safe to call them from shared utility code.
+
+```python
+import kensho_pytest as kensho
+
+def test_login(page):
+    with kensho.step("open the login page"):
+        page.goto("/login")
+
+    with kensho.step("submit credentials"):
+        page.fill("#user", "demo")
+        page.click("text=Sign in")
+        # nesting works — child steps roll up under the parent
+        with kensho.step("verify redirect"):
+            assert page.url.endswith("/home")
+
+    kensho.label("team", "growth")
+    kensho.link("https://jira.example.com/browse/PROJ-123",
+                kind="jira", label_text="PROJ-123")
+
+    page.screenshot(path="/tmp/login.png")
+    kensho.attach("/tmp/login.png", kind="screenshot")
+```
+
+| Helper                                    | What it does                                            |
+| ----------------------------------------- | ------------------------------------------------------- |
+| `with kensho.step(title, action=None):`   | Opens a Kensho step. Nests automatically. On exception the step is marked `fail` and the exception re-raises. |
+| `kensho.attach(path, kind=None, name=None, mime_type=None)` | Copies the file into `kensho-results/attachments/<caseId>/` and registers it on the current case (or current step, if one is open). |
+| `kensho.label(key, value)`                | Adds a string label to the case.                        |
+| `kensho.link(url, kind=None, label_text=None)` | Adds a hyperlink to the case.                       |
+| `kensho.current_case_id()`                | Returns the stable case id of the running test, or `None`. |
+
+## Captured output → logs
+
+Pytest's captured stdout / stderr / `caplog` for each phase (setup, call,
+teardown) is converted to entries in `case.logs[]`. The `t` field is the
+millisecond offset from the test start.
+
+## Errors
+
+`call` failures map to `status: 'fail'`; `setup` / `teardown` failures map
+to `status: 'broken'` (these are infrastructure, not real assertion
+failures). Skips at any phase map to `status: 'skip'`. The full
+`longrepr` is preserved in `case.errors[].stack`; the first line becomes
+`case.errors[].message`.
+
+## Environment auto-detected
+
+GitHub Actions, CircleCI, GitLab CI, Jenkins, Buildkite, Azure DevOps —
+CI provider, branch, commit, run URL, OS, architecture, Python version.
+
+Pass `KR_AUTHOR`, `KR_COMMIT_MSG`, `KR_STAGE`, `KR_BASE_URL`,
+`KR_APP_VERSION`, `KR_BUILD_NUMBER`, `KR_RELEASE`, `KR_REGION`,
+`KR_LOCALE`, `KR_TRIGGER`, or `KR_FEATURE` as env vars to populate the
+matching fields on `run.env`.
+
+## Design notes
+
+* Zero runtime dependencies beyond `pytest` itself. The schema lives in
+  the JS workspace; we vendor the minimum (id-hashing, status mapping,
+  env capture) inline so the adapter installs in seconds.
+* The reporter never raises out of a hook — a broken adapter must not
+  break a test run. All errors come out as `warnings.warn`.
+* IDs are stable across adapters: the FNV-1a hash matches the JS
+  `stableCaseId` byte-for-byte, so `pytest` and `playwright` runs of
+  the same suite roll up to the same history on the platform.
+
+## License
+
+Apache-2.0.

kensho_pytest-0.1.1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kensho-pytest"
+version = "0.1.1"
+description = "Kensho reporter for pytest — writes kensho-results/ so the Kensho CLI can generate a rich HTML report."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "KaizenReport" }]
+keywords = ["pytest", "kensho", "kaizenreport", "test-report", "reporter"]
+classifiers = [
+  "Framework :: Pytest",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = [
+  "pytest>=7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/kaizenreport/kensho"
+Source = "https://github.com/kaizenreport/kensho"
+
+# Pytest plugin entry point — pytest auto-discovers this on install.
+[project.entry-points.pytest11]
+kensho = "kensho_pytest.plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kensho_pytest = ["py.typed"]

kensho_pytest-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kensho_pytest-0.1.1/src/kensho_pytest/__init__.py

@@ -0,0 +1,223 @@
+"""Public API for ``kensho-pytest``.
+
+Most of the time you don't import anything — installing the package is
+enough; pytest discovers the plugin via the ``pytest11`` entry point and
+the reporter writes ``kensho-results/`` automatically.
+
+The helpers exported here are for tests that want to add structured
+metadata at runtime:
+
+* :func:`step`   — context manager, opens a Kensho step.
+* :func:`attach` — register a file (screenshot, log, JSON dump, …).
+* :func:`label`  — attach an arbitrary string ``key=value`` to the case.
+* :func:`link`   — attach a hyperlink (Jira ticket, runbook, PR, …).
+
+All four helpers are no-ops when called outside a running test (e.g.
+during collection or in a non-pytest script), so it's safe to call them
+from helper modules used from both prod and test code.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Dict, Iterator, Optional, Union
+
+from . import _state
+
+__all__ = ["step", "attach", "label", "link", "current_case_id"]
+
+__version__ = "0.1.0"
+
+
+@contextmanager
+def step(title: str, *, action: Optional[str] = None) -> Iterator[Dict[str, Any]]:
+    """Context manager that opens a Kensho step.
+
+    Steps can nest — the innermost ``with kensho.step(...)`` becomes the
+    parent of any further steps opened inside it. If the ``with`` block
+    raises, the step is marked ``fail`` and re-raised.
+
+    Example::
+
+        from kensho_pytest import step
+
+        def test_login(page):
+            with step("open the login page"):
+                page.goto("/login")
+            with step("submit credentials"):
+                page.fill("#user", "demo")
+                page.fill("#pwd", "demo")
+                page.click("text=Sign in")
+
+    Outside a pytest run the call is a no-op — the test code remains
+    safe to run as a plain script.
+    """
+    scratch = _state.get_current()
+    if scratch is None:
+        # No active test — yield a dummy dict so callers can still write
+        # to it without surprising errors.
+        yield {}
+        return
+
+    started_perf = time.time()
+    started_iso = _iso_now()
+    step_obj: Dict[str, Any] = {
+        "id": "step_" + uuid.uuid4().hex[:10],
+        "title": str(title),
+        "status": "pass",
+        "startedAt": started_iso,
+        "duration": 0,
+        "_startedPerf": started_perf,
+    }
+    if action:
+        step_obj["action"] = str(action)
+
+    parent = scratch.step_stack[-1] if scratch.step_stack else None
+    if parent is not None:
+        parent.setdefault("children", []).append(step_obj)
+    else:
+        scratch.steps.append(step_obj)
+    scratch.step_stack.append(step_obj)
+
+    try:
+        yield step_obj
+    except Exception:
+        step_obj["status"] = "fail"
+        _close_step(step_obj)
+        # pop and re-raise — the test framework decides what to do.
+        if scratch.step_stack and scratch.step_stack[-1] is step_obj:
+            scratch.step_stack.pop()
+        raise
+    else:
+        _close_step(step_obj)
+        if scratch.step_stack and scratch.step_stack[-1] is step_obj:
+            scratch.step_stack.pop()
+
+
+def attach(
+    path: Union[str, Path],
+    *,
+    kind: Optional[str] = None,
+    name: Optional[str] = None,
+    mime_type: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Copy a file into ``kensho-results/attachments/<caseId>/`` and register it.
+
+    Parameters
+    ----------
+    path:
+        Local path to the file to attach. Must exist; missing files are
+        skipped with a warning so a flaky screenshot can't break the run.
+    kind:
+        Optional override for ``attachment.kind``. One of ``screenshot``,
+        ``video``, ``trace``, ``har``, ``text``, ``json``, ``html``,
+        ``dom-snapshot``, ``log``. Inferred from the file extension when
+        omitted.
+    name:
+        Optional rename for the destination file. Defaults to the source
+        basename, prefixed with a short id to dodge collisions.
+    mime_type:
+        Optional MIME type override. Inferred from the file extension
+        when omitted.
+
+    Returns the registered attachment dict, or ``None`` if no test is
+    currently active (e.g. when called outside a pytest run).
+    """
+    scratch = _state.get_current()
+    if scratch is None:
+        return None
+    plugin = _resolve_plugin()
+    if plugin is None:
+        return None
+    record = plugin.register_attachment(
+        scratch,
+        Path(str(path)),
+        kind=kind,
+        name=name,
+        mime_type=mime_type,
+    )
+    if record is None:
+        return None
+    # Anchor it on the innermost step if one is open, otherwise on the case.
+    if scratch.step_stack:
+        scratch.step_stack[-1].setdefault("attachments", []).append(record)
+    else:
+        scratch.attachments.append(record)
+    return record
+
+
+def label(key: str, value: str) -> None:
+    """Set ``case.labels[key] = value`` for the currently-running test.
+
+    Useful for free-form metadata (``service``, ``team``, ``env``) that
+    doesn't fit the typed fields. No-op outside a test."""
+    scratch = _state.get_current()
+    if scratch is None or not key:
+        return
+    scratch.labels[str(key)] = str(value)
+
+
+def link(
+    url: str,
+    *,
+    kind: Optional[str] = None,
+    label_text: Optional[str] = None,
+) -> None:
+    """Attach a link to the currently-running case.
+
+    ``kind`` is free-form by convention (``jira``, ``github``, ``runbook``…).
+    ``label_text`` becomes ``link.label`` — the human-readable text. The
+    parameter is named ``label_text`` rather than ``label`` to avoid
+    shadowing the :func:`label` helper.
+    """
+    scratch = _state.get_current()
+    if scratch is None or not url:
+        return
+    entry: Dict[str, str] = {"url": str(url)}
+    if kind:
+        entry["kind"] = str(kind)
+    if label_text:
+        entry["label"] = str(label_text)
+    scratch.links.append(entry)
+
+
+def current_case_id() -> Optional[str]:
+    """Return the stable id of the test currently being run, if any."""
+    scratch = _state.get_current()
+    return scratch.case_id if scratch is not None else None
+
+
+# --------------------------------------------------------------------------- #
+# Internals
+# --------------------------------------------------------------------------- #
+
+
+def _close_step(step_obj: Dict[str, Any]) -> None:
+    started_perf = step_obj.pop("_startedPerf", None)
+    if started_perf is None:
+        step_obj.setdefault("duration", 0)
+        return
+    step_obj["duration"] = max(0, int(round((time.time() - started_perf) * 1000)))
+
+
+def _iso_now() -> str:
+    import datetime as _dt
+
+    return (
+        _dt.datetime.now(tz=_dt.timezone.utc)
+        .isoformat(timespec="milliseconds")
+        .replace("+00:00", "Z")
+    )
+
+
+def _resolve_plugin() -> Any:
+    """Return the active ``KenshoPlugin`` instance, or ``None`` if there is none.
+
+    The plugin publishes itself into ``_state.PLUGIN`` during
+    ``pytest_configure`` so helper APIs can find it without importing
+    the heavy plugin module at startup time.
+    """
+    return getattr(_state, "PLUGIN", None)