hookhappens 0.1.0__py3-none-any.whl

hookhappens/__init__.py

@@ -0,0 +1,3 @@
+"""HookHappens: the Python client and pytest plugin. The service lives at hookhappens.com."""
+
+__version__ = "0.1.0"

hookhappens/client.py

@@ -0,0 +1,441 @@
+"""Drive HookHappens from tests: a namespace of your own, scenarios and rules, and assertions on
+the calls your system made.
+
+    from hookhappens.client import HookHappens, gt
+
+    with HookHappens("https://hookhappens.com") as hh, hh.new_namespace("checkout") as ns:
+        ns.scenario("bank-down")                       # change the answers for this test
+        with ns.expect_call("authorize-payment", where={"body.amount": gt(0)}) as got:
+            shop.checkout(payments_url=ns.url, amount=50)   # your system, pointed at ns.url
+        assert got.call.status == 503
+
+When the expected call doesn't come, the failure says which calls came closest and what was
+different about each (``CallNotReceived``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterator, Mapping, Sequence
+from contextlib import contextmanager, suppress
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Any
+
+import httpx2
+
+__all__ = [
+    "Call", "CallNotReceived", "Expectation", "HookHappens", "HookHappensError", "Namespace",
+    "Op", "UnexpectedCall", "contains", "exists", "gt", "gte", "lt", "lte", "matches",
+    "missing", "none_of", "not_equal", "one_of",
+]
+
+Where = Mapping[str, Any] | Sequence[Mapping[str, Any]] | None
+
+
+# ── conditions: {"body.amount": gt(100)} reads as "body.amount > 100" ──
+
+@dataclass(frozen=True)
+class Op:
+    """A comparison for a ``where`` value other than "equals"."""
+
+    op: str
+    value: Any
+
+
+def gt(v: Any) -> Op:
+    return Op("gt", v)
+
+
+def gte(v: Any) -> Op:
+    return Op("gte", v)
+
+
+def lt(v: Any) -> Op:
+    return Op("lt", v)
+
+
+def lte(v: Any) -> Op:
+    return Op("lte", v)
+
+
+def not_equal(v: Any) -> Op:
+    return Op("not_equals", v)
+
+
+def one_of(*values: Any) -> Op:
+    return Op("in", list(values))
+
+
+def none_of(*values: Any) -> Op:
+    return Op("not_in", list(values))
+
+
+def contains(v: Any) -> Op:
+    return Op("contains", v)
+
+
+def matches(pattern: str) -> Op:
+    return Op("matches", pattern)
+
+
+def exists() -> Op:
+    return Op("exists", True)
+
+
+def missing() -> Op:
+    return Op("exists", False)
+
+
+def conditions(where: Where) -> list[dict[str, Any]]:
+    """``{"body.amount": 50, "body.currency": one_of("EUR", "USD")}`` or the catalog's own
+    form ``[{"field": "body.amount", "gt": 100}]`` → the catalog's form."""
+    if where is None:
+        return []
+    if isinstance(where, Mapping):
+        return [{"field": f, v.op: v.value} if isinstance(v, Op) else {"field": f, "equals": v}
+                for f, v in where.items()]
+    return [dict(c) for c in where]
+
+
+_SYMBOLS = {"equals": "=", "not_equals": "!=", "gt": ">", "gte": ">=", "lt": "<", "lte": "<=",
+            "in": "in", "not_in": "not in", "contains": "contains", "matches": "matches"}
+
+
+def _show(v: Any) -> str:
+    return json.dumps(v, ensure_ascii=False) if not isinstance(v, str) else repr(v)
+
+
+def describe_condition(c: Mapping[str, Any]) -> str:
+    op = next((k for k in c if k != "field"), "equals")
+    if op == "exists":
+        return f"{c['field']} {'exists' if c[op] else 'is missing'}"
+    return f"{c['field']} {_SYMBOLS.get(op, op)} {_show(c[op])}"
+
+
+# ── calls ──
+
+@dataclass(frozen=True)
+class Call:
+    """One call your system made to HookHappens, and what it got back."""
+
+    id: int
+    received_at: str
+    method: str
+    path: str
+    endpoint: str | None
+    response_name: str | None
+    status: int
+    duration_ms: int
+    request: dict[str, Any]
+    sent: dict[str, Any]
+    issues: list[dict[str, Any]]
+
+    @classmethod
+    def from_api(cls, d: Mapping[str, Any]) -> Call:
+        return cls(d["id"], d["receivedAt"], d["method"], d["path"], d.get("endpoint"),
+                   d.get("response"), d["status"], d.get("durationMs", 0),
+                   d.get("request") or {}, d.get("sent") or {}, d.get("issues") or [])
+
+    @property
+    def body(self) -> Any:
+        """The request body your system sent."""
+        return self.request.get("body")
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return dict(self.request.get("headers") or {})
+
+    @property
+    def query(self) -> dict[str, Any]:
+        return dict(self.request.get("query") or {})
+
+    @property
+    def params(self) -> dict[str, str]:
+        return dict(self.request.get("params") or {})
+
+    @property
+    def response_body(self) -> Any:
+        """What HookHappens answered (after any rules)."""
+        return self.sent.get("body")
+
+    def __str__(self) -> str:
+        where = f" ({self.endpoint})" if self.endpoint else ""
+        return f"#{self.id} {self.method} {self.path} -> {self.status}{where}"
+
+
+class HookHappensError(Exception):
+    """The server refused a request, or could not be reached."""
+
+
+class CallNotReceived(AssertionError):
+    """The call a test waited for didn't come. The message lists the closest calls."""
+
+    def __init__(self, message: str, result: Mapping[str, Any]) -> None:
+        super().__init__(message)
+        self.result = dict(result)
+
+
+class UnexpectedCall(AssertionError):
+    """A call came that the test said must not."""
+
+    def __init__(self, message: str, calls: list[Call]) -> None:
+        super().__init__(message)
+        self.calls = calls
+
+
+def _what(endpoint: str | None, method: str | None, path: str | None,
+          conds: list[dict[str, Any]]) -> str:
+    target = (f"call to {endpoint}" if endpoint
+              else f"{method or ''} {path}".strip() + " call" if path or method else "call")
+    return target + (" where " + " and ".join(map(describe_condition, conds)) if conds else "")
+
+
+def _check_line(c: Mapping[str, Any]) -> str:
+    mark = "+" if c["ok"] else "x"
+    if "op" not in c:  # endpoint / method / path
+        return (f"{mark} {c['check']} = {c['expected']}" if c["ok"]
+                else f"{mark} {c['check']}: expected {c['expected']}, got {c['actual']}")
+    text = describe_condition({"field": c["check"], c["op"]: c["expected"]})
+    if c["ok"]:
+        return f"{mark} {text}"
+    return f"{mark} {text}: got {_show(c['actual']) if c.get('found') else 'nothing'}"
+
+
+def explain_miss(what: str, timeout: float, namespace: str, result: Mapping[str, Any]) -> str:
+    """The failure message: what was expected, and the calls that came closest."""
+    seen = result.get("seen", 0)
+    lines = [f"No {what} arrived within {timeout:g} s "
+             f"(namespace {namespace}; {seen} call{'s' if seen != 1 else ''} seen)."]
+    misses = result.get("nearMisses") or []
+    if not misses:
+        lines.append("No calls at all came in: is your system pointed at "
+                     f"/h/{namespace}/ ?" if not seen else "")
+    else:
+        lines.append("Closest:")
+        for m in misses:
+            c = m["call"]
+            checks = m["checks"]
+            passed = sum(x["ok"] for x in checks)
+            where = f" ({c['endpoint']})" if c.get("endpoint") else ""
+            lines.append(f"  #{c['id']} {c['method']} {c['path']} -> {c['status']}{where}"
+                         f"  {passed} of {len(checks)} checks")
+            lines += [f"      {_check_line(x)}" for x in checks]
+    return "\n".join(line for line in lines if line)
+
+
+# ── the client ──
+
+class HookHappens:
+    """HookHappens, for tests. Use ``new_namespace`` for a namespace of your own per test.
+
+    ``api_key`` is your workspace's API key (default: the ``HOOKHAPPENS_API_KEY`` environment
+    variable); every call sends it as ``Authorization: Bearer …``."""
+
+    def __init__(self, url: str = "https://hookhappens.com", *, api_key: str | None = None,
+                 timeout: float = 30.0, http: httpx2.Client | None = None) -> None:
+        self.url = url.rstrip("/")
+        key = api_key or os.environ.get("HOOKHAPPENS_API_KEY")
+        headers = {"Authorization": f"Bearer {key}"} if key else {}
+        self._http = http or httpx2.Client(base_url=self.url, timeout=timeout, headers=headers)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> HookHappens:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def request(self, method: str, path: str, body: Any = None,
+                params: Mapping[str, Any] | None = None) -> Any:
+        try:
+            r = self._http.request(method, path, json=body, params=params)
+        except httpx2.HTTPError as exc:
+            raise HookHappensError(
+                f"HookHappens is not reachable at {self.url} ({exc}). Check the address "
+                "(HOOKHAPPENS_URL) and the network.") from exc
+        if r.status_code >= 400:
+            try:
+                data = r.json()
+                problems = "".join(f"\n  {p['location']}: {p['message']}"
+                                   for p in data.get("problems", []))
+                message = f"{data.get('message', r.text)}{problems}"
+            except ValueError:
+                message = r.text
+            raise HookHappensError(f"{method} {path} -> {r.status_code}: {message}")
+        return r.json() if r.content else None
+
+    def health(self) -> dict[str, Any]:
+        out: dict[str, Any] = self.request("GET", "/health")
+        return out
+
+    def namespace(self, namespace: str) -> Namespace:
+        """An existing namespace (e.g. the project's own). Left as it is on close."""
+        return Namespace(self, namespace, owned=False)
+
+    def new_namespace(self, project: str, *, id: str | None = None,
+                      ttl: int | None = 3600) -> Namespace:
+        """A fresh namespace of ``project``: its own URL, rules and call log. Deleted on close
+        (or ``ttl`` seconds after the last keep-alive, if the test never gets there)."""
+        data = self.request("POST", f"/api/v1/projects/{project}/namespaces",
+                            {"id": id, "ttl_seconds": ttl})
+        return Namespace(self, data["id"], project=project, owned=True)
+
+
+@dataclass
+class Expectation:
+    """Filled when the ``with ns.expect_call(...)`` block ends: the call that came."""
+
+    call: Call = field(init=False)
+
+
+class Namespace:
+    """One namespace: where your system sends its calls (``url``), and what the test controls."""
+
+    def __init__(self, hh: HookHappens, namespace: str, *, project: str | None = None,
+                 owned: bool = False) -> None:
+        self.hh = hh
+        self.id = namespace
+        self.project = project
+        self.owned = owned
+
+    @property
+    def url(self) -> str:
+        """The base URL to give your system: the namespace's address, …/h/checkout-3fa2c1"""
+        return f"{self.hh.url}/h/{self.id}"
+
+    def __repr__(self) -> str:
+        return f"Namespace({self.id!r})"
+
+    def __enter__(self) -> Namespace:
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None,
+                 tb: TracebackType | None) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Delete it, if this client made it."""
+        if self.owned:
+            with suppress(HookHappensError):  # already gone (expired) is fine
+                self.hh.request("DELETE", f"/api/v1/namespaces/{self.id}")
+            self.owned = False
+
+    def keep_alive(self, ttl: int = 3600) -> None:
+        self.hh.request("POST", f"/api/v1/namespaces/{self.id}/keep-alive", {"ttl_seconds": ttl})
+
+    # ── what it answers ──
+
+    def scenario(self, scenario_id: str, **settings: Any) -> None:
+        """This scenario of the catalog, and nothing else: other scenarios and the rules armed
+        here are switched off. Keyword arguments set its settings, e.g.
+        ``ns.scenario("skip-steps", stepTypes=["table"])``."""
+        if settings:
+            self.scenario_settings(scenario_id, **settings)
+        self.hh.request("PUT", f"/api/v1/namespaces/{self.id}/active-scenario", {"id": scenario_id})
+
+    def scenario_on(self, scenario_id: str, **settings: Any) -> None:
+        """Switch a scenario on as well (any number can be on), with these settings."""
+        self._switch(scenario_id, {"active": True, **({"settings": settings} if settings else {})})
+
+    def scenario_off(self, scenario_id: str) -> None:
+        self._switch(scenario_id, {"active": False})
+
+    def scenario_settings(self, scenario_id: str, **settings: Any) -> None:
+        """Set a scenario's settings here (``None`` puts one back to its default)."""
+        self._switch(scenario_id, {"settings": settings})
+
+    def _switch(self, scenario_id: str, body: dict[str, Any]) -> None:
+        self.hh.request("PUT", f"/api/v1/namespaces/{self.id}/scenarios/{scenario_id}", body)
+
+    def clear_rules(self) -> None:
+        """Back to the catalog's own answers (no scenario, no rules)."""
+        self.hh.request("DELETE", f"/api/v1/namespaces/{self.id}/active-scenario")
+
+    def rule(self, endpoint: str | None = None, *, then: Sequence[Mapping[str, Any]],
+             when: Where = None, skip: int = 0, times: int | None = None,
+             description: str | None = None) -> str:
+        """Add one rule (see the scenario rules docs for ``then`` actions). Returns its id."""
+        body: dict[str, Any] = {"endpoint": endpoint, "then": [dict(a) for a in then],
+                                "when": conditions(when), "skip": skip, "times": times,
+                                "description": description}
+        out = self.hh.request("POST", f"/api/v1/namespaces/{self.id}/rules",
+                              {k: v for k, v in body.items() if v not in (None, [])})
+        return str(out["id"])
+
+    # ── what it received ──
+
+    def calls(self, endpoint: str | None = None, *, limit: int = 200) -> list[Call]:
+        """The calls in the log, oldest first."""
+        data = self.hh.request("GET", f"/api/v1/namespaces/{self.id}/calls",
+                               params={"limit": limit})
+        calls = [Call.from_api(c) for c in reversed(data["calls"])]
+        return [c for c in calls if endpoint is None or c.endpoint == endpoint]
+
+    def mark(self) -> int:
+        """The newest call's id now (0 if none): pass it as ``after`` to wait only for later
+        calls."""
+        data = self.hh.request("GET", f"/api/v1/namespaces/{self.id}/calls", params={"limit": 1})
+        return int(data["calls"][0]["id"]) if data["calls"] else 0
+
+    def _wait(self, endpoint: str | None, where: Where, method: str | None, path: str | None,
+              after: int | None, timeout: float, count: int) -> tuple[dict[str, Any], str]:
+        conds = conditions(where)
+        result: dict[str, Any] = self.hh.request(
+            "POST", f"/api/v1/namespaces/{self.id}/calls/wait",
+            {"endpoint": endpoint, "where": conds, "method": method, "path": path,
+             "after": after, "count": count, "timeout_ms": int(timeout * 1000)})
+        return result, _what(endpoint, method, path, conds)
+
+    def wait_for(self, endpoint: str | None = None, *, where: Where = None,
+                 method: str | None = None, path: str | None = None, after: int | None = None,
+                 timeout: float = 5.0) -> Call:
+        """The first call that fits (already in the log, or arriving within ``timeout``).
+        Raises ``CallNotReceived``, listing the closest calls, when none does."""
+        __tracebackhide__ = True  # pytest shows the test's line, not these helpers
+        return self.wait_for_all(1, endpoint, where=where, method=method, path=path,
+                                 after=after, timeout=timeout)[0]
+
+    def wait_for_all(self, count: int, endpoint: str | None = None, *, where: Where = None,
+                     method: str | None = None, path: str | None = None,
+                     after: int | None = None, timeout: float = 5.0) -> list[Call]:
+        """``count`` calls that fit, oldest first."""
+        __tracebackhide__ = True
+        result, what = self._wait(endpoint, where, method, path, after, timeout, count)
+        if not result["matched"]:
+            found = len(result["calls"])
+            label = what if count == 1 else f"{count} x {what} (only {found} came)"
+            raise CallNotReceived(explain_miss(label, timeout, self.id, result), result)
+        return [Call.from_api(c) for c in result["calls"]]
+
+    @contextmanager
+    def expect_call(self, endpoint: str | None = None, *, where: Where = None,
+                    method: str | None = None, path: str | None = None,
+                    timeout: float = 5.0) -> Iterator[Expectation]:
+        """The block must make your system send this call (only calls made inside count)."""
+        __tracebackhide__ = True
+        after = self.mark()
+        got = Expectation()
+        yield got
+        got.call = self.wait_for(endpoint, where=where, method=method, path=path, after=after,
+                                 timeout=timeout)
+
+    def expect_no_call(self, endpoint: str | None = None, *, where: Where = None,
+                       method: str | None = None, path: str | None = None,
+                       after: int | None = None, within: float = 1.0) -> None:
+        """No such call (in the log after ``after``, or arriving within ``within`` seconds)."""
+        __tracebackhide__ = True
+        result, what = self._wait(endpoint, where, method, path, after, within, 1)
+        if result["matched"]:
+            calls = [Call.from_api(c) for c in result["calls"]]
+            raise UnexpectedCall(f"Expected no {what}, but got {calls[0]} (namespace {self.id}).",
+                                 calls)
+
+    def evidence(self) -> dict[str, Any]:
+        """Everything about this namespace's calls, for a test report."""
+        data = self.hh.request("GET", f"/api/v1/namespaces/{self.id}/calls", params={"limit": 500})
+        return {"namespace": self.id, "project": self.project, "url": self.url,
+                "calls": list(reversed(data["calls"]))}

hookhappens/pytest_plugin.py

@@ -0,0 +1,195 @@
+"""pytest plugin: each test gets a fresh HookHappens namespace, and a failing test shows the
+calls its system made.
+
+    # pytest.ini (or --hookhappens-url / --hookhappens-project, or HOOKHAPPENS_URL)
+    [pytest]
+    hookhappens_url = https://hookhappens.com
+    hookhappens_project = checkout
+
+    def test_paid(hh):                      # hh: a namespace of its own, deleted afterwards
+        assert shop.checkout(hh.url, amount=50) == "paid"
+        hh.wait_for("authorize-payment", where={"body.amount": 50})
+
+    @pytest.mark.hookhappens(scenario="bank-down")
+    def test_bank_down(hh): ...
+
+With ``--hookhappens-evidence DIR``, every test's calls are written to DIR as JSON, with an
+``index.html`` to browse them.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+import os
+import re
+from collections.abc import Generator, Iterator
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from hookhappens.client import HookHappens, HookHappensError, Namespace
+
+NAMESPACE = pytest.StashKey[Namespace]()
+MARKER = "hookhappens"
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("hookhappens", "HookHappens")
+    group.addoption("--hookhappens-url", default=None, metavar="URL",
+                    help="the HookHappens server (default: $HOOKHAPPENS_URL, the "
+                         "hookhappens_url ini value, or https://hookhappens.com)")
+    group.addoption("--hookhappens-project", default=None, metavar="ID",
+                    help="the project tests get namespaces of (or the hookhappens_project "
+                         "ini value, or @pytest.mark.hookhappens(project=...))")
+    group.addoption("--hookhappens-evidence", default=None, metavar="DIR",
+                    help="write each test's calls to DIR (JSON per test + index.html)")
+    parser.addini("hookhappens_url", "the HookHappens server", default="")
+    parser.addini("hookhappens_project", "the project tests get namespaces of", default="")
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line(
+        "markers", f"{MARKER}(project=None, scenario=None, ttl=3600): the HookHappens "
+                   "namespace the `hh` fixture makes for this test")
+
+
+def _setting(config: pytest.Config, name: str, env: str | None = None) -> str | None:
+    value = config.getoption(f"--hookhappens-{name}")
+    if value:
+        return str(value)
+    if env and os.environ.get(env):
+        return os.environ[env]
+    ini = config.getini(f"hookhappens_{name}")
+    return str(ini) if ini else None
+
+
+@pytest.fixture(scope="session")
+def hookhappens(pytestconfig: pytest.Config) -> Iterator[HookHappens]:
+    """The HookHappens server (a client for it), checked to be up."""
+    url = _setting(pytestconfig, "url", "HOOKHAPPENS_URL") or "https://hookhappens.com"
+    client = HookHappens(url)
+    try:
+        client.health()
+    except HookHappensError as exc:
+        client.close()
+        pytest.fail(str(exc), pytrace=False)
+    yield client
+    client.close()
+
+
+@pytest.fixture
+def hh(request: pytest.FixtureRequest, hookhappens: HookHappens) -> Iterator[Namespace]:
+    """A fresh namespace of the project for this test: its own URL (``hh.url``), rules and
+    call log. Deleted after the test."""
+    marker = request.node.get_closest_marker(MARKER)
+    options: dict[str, Any] = dict(marker.kwargs) if marker else {}
+    project = options.get("project") or _setting(request.config, "project")
+    if not project:
+        pytest.fail("Which HookHappens project? Set hookhappens_project in pytest.ini, pass "
+                    "--hookhappens-project, or mark the test "
+                    "@pytest.mark.hookhappens(project=...)", pytrace=False)
+    ns = hookhappens.new_namespace(project, ttl=options.get("ttl", 3600))
+    request.node.stash[NAMESPACE] = ns
+    try:
+        if options.get("scenario"):
+            ns.scenario(options["scenario"])
+        yield ns
+    finally:
+        ns.close()
+
+
+@pytest.hookimpl(wrapper=True)
+def pytest_runtest_makereport(
+    item: pytest.Item, call: pytest.CallInfo[None],
+) -> Generator[None, pytest.TestReport, pytest.TestReport]:
+    report = yield
+    ns = item.stash.get(NAMESPACE, None)
+    if ns is None or report.when != "call":
+        return report
+    evidence_dir = item.config.getoption("--hookhappens-evidence")
+    if not (report.failed or evidence_dir):
+        return report
+    try:
+        evidence = ns.evidence()  # before the fixture deletes the namespace
+    except HookHappensError as exc:
+        report.sections.append(("HookHappens calls", f"(could not read them: {exc})"))
+        return report
+    if report.failed:
+        report.sections.append((f"HookHappens calls (namespace {ns.id})", _calls_text(evidence)))
+    if evidence_dir:
+        _write_evidence(Path(evidence_dir), item.nodeid, report.outcome, evidence)
+    return report
+
+
+def _calls_text(evidence: dict[str, Any]) -> str:
+    calls = evidence["calls"]
+    if not calls:
+        return f"No calls came in. Was your system pointed at {evidence['url']} ?"
+    lines = []
+    for c in calls:
+        where = f" ({c['endpoint']})" if c.get("endpoint") else ""
+        lines.append(f"#{c['id']} {c['method']} {c['path']} -> {c['status']}{where}")
+        body = (c.get("request") or {}).get("body")
+        if body is not None:
+            lines.append(f"    sent:     {json.dumps(body, ensure_ascii=False)[:300]}")
+        answer = (c.get("sent") or {}).get("body")
+        if answer is not None:
+            lines.append(f"    answered: {json.dumps(answer, ensure_ascii=False)[:300]}")
+        rules = (c.get("sent") or {}).get("rules")
+        if rules:
+            lines.append(f"    rules:    {', '.join(rules)}")
+        for issue in c.get("issues") or []:
+            lines.append(f"    ! {issue['location']}: {issue['message']}")
+    return "\n".join(lines)
+
+
+def _file_name(nodeid: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_.-]+", "_", nodeid).strip("_")[:150] + ".json"
+
+
+def _write_evidence(folder: Path, nodeid: str, outcome: str, evidence: dict[str, Any]) -> None:
+    folder.mkdir(parents=True, exist_ok=True)
+    (folder / _file_name(nodeid)).write_text(
+        json.dumps({"test": nodeid, "outcome": outcome, **evidence}, indent=2,
+                   ensure_ascii=False), encoding="utf-8")
+
+
+def pytest_sessionfinish(session: pytest.Session) -> None:
+    folder = session.config.getoption("--hookhappens-evidence")
+    if not folder or hasattr(session.config, "workerinput"):  # once, not per xdist worker
+        return
+    path = Path(folder)
+    if path.is_dir():
+        (path / "index.html").write_text(evidence_index(path), encoding="utf-8")
+
+
+_PAGE_STYLE = (
+    "body{font:14px system-ui;margin:24px}details{margin:6px 0;padding:6px 10px;"
+    "border-radius:8px;background:#f4f2fb}details.failed{background:#fde8e8}"
+    "pre{background:#fff;padding:6px;border-radius:6px;max-height:240px;overflow:auto}")
+
+
+def _call_item(c: dict[str, Any]) -> str:
+    e = html.escape
+    sent = json.dumps((c.get("request") or {}).get("body"), indent=2, ensure_ascii=False)
+    return (f"<li><code>{e(c['method'])} {e(c['path'])}</code> → {c['status']} "
+            f"{e(c.get('endpoint') or '')}<pre>{e(sent)}</pre></li>")
+
+
+def _test_block(data: dict[str, Any], file_name: str) -> str:
+    e = html.escape
+    calls = "".join(_call_item(c) for c in data["calls"]) or "<li>no calls</li>"
+    return (f"<details class='{e(data['outcome'])}'><summary><b>{e(data['outcome'])}</b> "
+            f"{e(data['test'])} <small>({len(data['calls'])} calls, namespace "
+            f"{e(data['namespace'])}) · <a href='{e(file_name)}'>JSON</a></small></summary>"
+            f"<ul>{calls}</ul></details>")
+
+
+def evidence_index(folder: Path) -> str:
+    """One page listing every test's calls (from the JSON files the run wrote)."""
+    blocks = [_test_block(json.loads(f.read_text(encoding="utf-8")), f.name)
+              for f in sorted(folder.glob("*.json"))]
+    return ("<!doctype html><meta charset='utf-8'><title>HookHappens evidence</title>"
+            f"<style>{_PAGE_STYLE}</style><h1>HookHappens evidence</h1>" + "".join(blocks))

hookhappens-0.1.0.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: hookhappens
+Version: 0.1.0
+Summary: The Python client and pytest plugin for HookHappens, the webhook and API mock for testing at hookhappens.com.
+Project-URL: Homepage, https://hookhappens.com
+Project-URL: Documentation, https://hookhappens.com/#/how-to/testing
+License-Expression: LicenseRef-Proprietary
+Keywords: api,mock,pytest,testing,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Testing :: Mocking
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# HookHappens, the Python client
+
+**HookHappens** ("Mock around & find out") stands in for the endpoints your system calls, or
+sits in front of the real ones. A test changes exactly the part of the answer it needs, and you
+see what your system did with it. The service lives at **https://hookhappens.com**; this package
+is the Python client and the pytest plugin for it.
+
+```bash
+pip install hookhappens
+```
+
+```python
+from hookhappens import HookHappens
+
+with HookHappens("https://hookhappens.com", api_key="hh_…") as hh:
+    with hh.new_namespace("snack-bar") as run:         # a throwaway address for this test run
+        run.rule("order-snack", then=[{"status": 503}])  # the kitchen is on fire
+        my_app.order("cookie", 3, kitchen=run.url)       # point your system at it
+        call = run.wait_for("order-snack")               # the call your system made, with its answer
+        assert call.status == 503
+```
+
+With pytest, the `hh` fixture does the same with no setup beyond two environment variables:
+
+```bash
+export HOOKHAPPENS_URL=https://hookhappens.com
+export HOOKHAPPENS_API_KEY=hh_…
+pytest
+```
+
+```python
+def test_the_kitchen_on_fire(hh):
+    hh.scenario_on("kitchen-on-fire")
+    my_app.order("cookie", 3, kitchen=hh.url)
+    assert hh.wait_for(endpoint="order-snack").status == 503
+```
+
+The whole story, with a runnable example app and its test suite, is the **Testing your system**
+guide: https://hookhappens.com/#/how-to/testing. The service is hosted only; nothing to install
+but this client. © 2026 Carolina Shulman Grigoriev. All rights reserved.

hookhappens-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+hookhappens/__init__.py,sha256=xwopvWUUEBBFKyPVHr_eM8GD6NNbE1vs_oPTc1oTk_8,120
+hookhappens/client.py,sha256=uBuy5NwnhiUAIk2F82NuSXG_1DmGnGRrhMMy0BCor0U,17820
+hookhappens/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hookhappens/pytest_plugin.py,sha256=ysTut2m-GDv-sRiHg9yMD1hmw44fXs48jfUwfaIstDQ,8147
+hookhappens-0.1.0.dist-info/METADATA,sha256=_2e2iXEUvdHd2R8PUZIAVSFYrWmU54Lmke5ugOo3Bhc,2406
+hookhappens-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+hookhappens-0.1.0.dist-info/entry_points.txt,sha256=eaQgfbts17b_gc_avsutFevd836SuCpUFYugKdafGCI,51
+hookhappens-0.1.0.dist-info/RECORD,,

hookhappens-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hookhappens-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+hookhappens = hookhappens.pytest_plugin