pyhttp-app 2.0.1__py3-none-any.whl

pyhttp/assertions.py

@@ -0,0 +1,289 @@
+"""Code-free tests (assertions) and value extraction, evaluated after a response.
+
+A request can carry a list of tests such as "status equals 200" or
+"json data.token exists", and a list of extractions such as "set env variable
+`token` from json `data.token`". Both are plain dicts so they survive
+import/export, and neither needs a script engine.
+
+Test shape:
+    {"type": "status"|"time"|"header"|"body"|"json",
+     "target": "<header name or json path>", "op": "<operator>",
+     "value": "<expected>", "enabled": true}
+
+Extraction shape:
+    {"name": "token", "source": "json"|"header"|"status"|"body"|"regex",
+     "path": "data.token" | "Set-Cookie" | "<regex with one group>",
+     "scope": "env"|"global", "enabled": true}
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from .templating import _Missing, _walk, to_text
+
+OPS: dict[str, list[str]] = {
+    "status": ["equals", "not_equals", "less_than", "greater_than", "is_2xx", "is_3xx", "is_4xx", "is_5xx", "in"],
+    "time": ["less_than", "greater_than"],
+    "header": ["exists", "not_exists", "equals", "not_equals", "contains", "not_contains", "matches"],
+    "body": ["contains", "not_contains", "equals", "not_equals", "matches", "is_json", "is_empty", "not_empty"],
+    "json": ["exists", "not_exists", "equals", "not_equals", "contains", "not_contains", "matches",
+             "type_is", "length_equals", "less_than", "greater_than", "is_empty", "not_empty", "is_true", "is_false", "is_null"],
+}
+
+_LABEL = {
+    "equals": "equals", "not_equals": "does not equal", "less_than": "is less than", "greater_than": "is greater than",
+    "is_2xx": "is 2xx", "is_3xx": "is 3xx", "is_4xx": "is 4xx", "is_5xx": "is 5xx", "in": "is one of",
+    "exists": "exists", "not_exists": "does not exist", "contains": "contains", "not_contains": "does not contain",
+    "matches": "matches", "is_json": "is valid JSON", "is_empty": "is empty", "not_empty": "is not empty",
+    "type_is": "is of type", "length_equals": "has length", "is_true": "is true", "is_false": "is false", "is_null": "is null",
+}
+
+
+def describe(t: dict[str, Any]) -> str:
+    """Human name for a test, like Postman's "Status code is 200"."""
+    kind, op, target, value = t.get("type", ""), t.get("op", ""), t.get("target", ""), t.get("value", "")
+    label = _LABEL.get(op, op)
+    subject = {"status": "Status code", "time": "Response time (ms)", "header": f"Header {target}",
+               "body": "Body", "json": f"JSON {target}"}.get(kind, kind)
+    needs_value = op not in ("exists", "not_exists", "is_json", "is_empty", "not_empty", "is_2xx", "is_3xx",
+                             "is_4xx", "is_5xx", "is_true", "is_false", "is_null")
+    return f"{subject} {label}{' ' + str(value) if needs_value and value != '' else ''}".strip()
+
+
+def _num(v: Any) -> float | None:
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def _as_text(v: Any) -> str:
+    return v if isinstance(v, str) else to_text(v)
+
+
+def _json_type(v: Any) -> str:
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "boolean"
+    if isinstance(v, (int, float)):
+        return "number"
+    if isinstance(v, str):
+        return "string"
+    if isinstance(v, list):
+        return "array"
+    return "object"
+
+
+def _loose_equal(actual: Any, expected: str) -> bool:
+    if isinstance(actual, bool):
+        return expected.strip().lower() in (("true", "1") if actual else ("false", "0"))
+    if actual is None:
+        return expected.strip().lower() in ("null", "none", "")
+    if isinstance(actual, (int, float)):
+        n = _num(expected)
+        return n is not None and float(actual) == n
+    if isinstance(actual, (dict, list)):
+        try:
+            return actual == json.loads(expected)
+        except ValueError:
+            return json.dumps(actual, sort_keys=True) == expected
+    return str(actual) == expected
+
+
+def _compare(op: str, actual: Any, expected: str) -> tuple[bool, str]:
+    """Shared operators for json/header/body values. Returns (passed, note)."""
+    shown = _as_text(actual)
+    if len(shown) > 120:
+        shown = shown[:117] + "…"
+    if op == "equals":
+        return _loose_equal(actual, expected), f"actual: {shown}"
+    if op == "not_equals":
+        return not _loose_equal(actual, expected), f"actual: {shown}"
+    if op == "contains":
+        if isinstance(actual, list):
+            return any(_loose_equal(x, expected) for x in actual), f"{len(actual)} item(s)"
+        if isinstance(actual, dict):
+            return expected in actual, f"keys: {', '.join(list(actual)[:10])}"
+        return expected in _as_text(actual), f"actual: {shown}"
+    if op == "not_contains":
+        ok, note = _compare("contains", actual, expected)
+        return not ok, note
+    if op == "matches":
+        try:
+            return re.search(expected, _as_text(actual)) is not None, f"actual: {shown}"
+        except re.error as exc:
+            return False, f"invalid regex: {exc}"
+    if op in ("less_than", "greater_than"):
+        a, e = _num(actual), _num(expected)
+        if a is None or e is None:
+            return False, f"not a number: {shown}"
+        return (a < e) if op == "less_than" else (a > e), f"actual: {shown}"
+    if op == "is_empty":
+        return actual in ("", None, [], {}), f"actual: {shown}"
+    if op == "not_empty":
+        return actual not in ("", None, [], {}), f"actual: {shown}"
+    if op == "type_is":
+        return _json_type(actual) == expected.strip().lower(), f"actual type: {_json_type(actual)}"
+    if op == "length_equals":
+        n = len(actual) if isinstance(actual, (str, list, dict)) else None
+        e = _num(expected)
+        return n is not None and e is not None and n == int(e), f"actual length: {n}"
+    if op == "is_true":
+        return actual is True, f"actual: {shown}"
+    if op == "is_false":
+        return actual is False, f"actual: {shown}"
+    if op == "is_null":
+        return actual is None, f"actual: {shown}"
+    return False, f"unknown operator {op}"
+
+
+def _header(result: dict[str, Any], name: str) -> str | None:
+    resp = result.get("response") or {}
+    for k, v in resp.get("headers", []):
+        if k.lower() == name.strip().lower():
+            return v
+    return None
+
+
+def _json_value(result: dict[str, Any], path: str) -> Any:
+    data = result.get("_json")
+    if data is None and (result.get("response") or {}).get("body_text"):
+        try:
+            data = json.loads(result["response"]["body_text"])
+        except ValueError as exc:
+            raise _Missing("body is not JSON") from exc
+    path = (path or "").strip()
+    if path in ("", "$", "."):
+        return data
+    if path.startswith("$."):
+        path = path[2:]
+    return _walk(data, path)
+
+
+def run_tests(tests: list[dict[str, Any]], result: dict[str, Any]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for t in tests or []:
+        if not t.get("enabled", True):
+            continue
+        name = (t.get("name") or "").strip() or describe(t)
+        try:
+            passed, note = _evaluate(t, result)
+        except _Missing as exc:
+            passed, note = False, f"missing: {exc}"
+        except Exception as exc:  # noqa: BLE001 - a broken test must not break the run
+            passed, note = False, f"{type(exc).__name__}: {exc}"
+        out.append({"name": name, "passed": bool(passed), "note": note})
+    return out
+
+
+def _evaluate(t: dict[str, Any], result: dict[str, Any]) -> tuple[bool, str]:
+    kind, op = t.get("type"), t.get("op") or ""
+    expected = str(t.get("value", "") if t.get("value") is not None else "")
+    if kind == "status":
+        code = result.get("status_code")
+        if code is None:
+            return False, f"no response: {result.get('error') or 'error'}"
+        note = f"actual: {code}"
+        if op == "equals":
+            return str(code) == expected.strip(), note
+        if op == "not_equals":
+            return str(code) != expected.strip(), note
+        if op == "less_than":
+            return (_num(expected) is not None) and code < _num(expected), note
+        if op == "greater_than":
+            return (_num(expected) is not None) and code > _num(expected), note
+        if op in ("is_2xx", "is_3xx", "is_4xx", "is_5xx"):
+            return code // 100 == int(op[3]), note
+        if op == "in":
+            wanted = [s.strip() for s in re.split(r"[,\s]+", expected) if s.strip()]
+            return str(code) in wanted, note
+        return False, f"unknown operator {op}"
+    if kind == "time":
+        ms = result.get("duration_ms") or 0
+        e = _num(expected)
+        note = f"actual: {ms:.0f} ms"
+        if e is None:
+            return False, "expected value is not a number"
+        return (ms < e) if op == "less_than" else (ms > e), note
+    if kind == "header":
+        if result.get("response") is None:
+            return False, f"no response: {result.get('error') or 'error'}"
+        value = _header(result, t.get("target") or "")
+        if op == "exists":
+            return value is not None, "present" if value is not None else "absent"
+        if op == "not_exists":
+            return value is None, "present" if value is not None else "absent"
+        if value is None:
+            return False, "header absent"
+        return _compare(op, value, expected)
+    if kind == "body":
+        if result.get("response") is None:
+            return False, f"no response: {result.get('error') or 'error'}"
+        text = result["response"].get("body_text") or ""
+        if op == "is_json":
+            try:
+                json.loads(text)
+                return True, "valid JSON"
+            except ValueError as exc:
+                return False, f"invalid JSON: {exc}"
+        return _compare(op, text, expected)
+    if kind == "json":
+        if result.get("response") is None:
+            return False, f"no response: {result.get('error') or 'error'}"
+        path = t.get("target") or ""
+        try:
+            value = _json_value(result, path)
+        except _Missing:
+            if op == "not_exists":
+                return True, "absent"
+            return False, f"path not found: {path or '$'}"
+        if op == "exists":
+            return True, "present"
+        if op == "not_exists":
+            return False, "present"
+        return _compare(op, value, expected)
+    return False, f"unknown test type {kind}"
+
+
+def extract(rules: list[dict[str, Any]], result: dict[str, Any]) -> list[dict[str, Any]]:
+    """Evaluate extraction rules. Returns [{name, scope, value, ok, note}] without saving anything."""
+    out: list[dict[str, Any]] = []
+    for r in rules or []:
+        if not r.get("enabled", True):
+            continue
+        name = (r.get("name") or "").strip()
+        if not name:
+            continue
+        scope = r.get("scope") or "env"
+        src, path = r.get("source") or "json", r.get("path") or ""
+        try:
+            if src == "status":
+                value: Any = result.get("status_code")
+                if value is None:
+                    raise _Missing("no response")
+            elif src == "header":
+                value = _header(result, path)
+                if value is None:
+                    raise _Missing(f"header {path}")
+            elif src == "body":
+                value = (result.get("response") or {}).get("body_text")
+                if value is None:
+                    raise _Missing("no response")
+            elif src == "regex":
+                text = (result.get("response") or {}).get("body_text") or ""
+                m = re.search(path, text)
+                if not m:
+                    raise _Missing(f"no match for {path}")
+                value = m.group(1) if m.groups() else m.group(0)
+            else:
+                value = _json_value(result, path)
+            out.append({"name": name, "scope": scope, "value": _as_text(value), "ok": True,
+                        "note": f"{src} {path}".strip()})
+        except _Missing as exc:
+            out.append({"name": name, "scope": scope, "value": None, "ok": False, "note": f"not found: {exc}"})
+        except re.error as exc:
+            out.append({"name": name, "scope": scope, "value": None, "ok": False, "note": f"invalid regex: {exc}"})
+    return out

pyhttp/cli.py

@@ -0,0 +1,364 @@
+"""`pyhttp run`: run a collection headless, for CI (like Postman's newman).
+
+    python -m pyhttp run                          # every request in your collection
+    python -m pyhttp run "API/Users" Login        # folders (by name or path) and requests (by name or id)
+    python -m pyhttp run collection.json          # a Postman / pyhttp / OpenAPI file, without importing it
+    python -m pyhttp run --env QA --junit out/junit.xml --html out/report.html
+
+Exit code: 0 when every request passed, 1 when any failed, 2 for usage errors.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import html
+import json
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+from xml.etree import ElementTree as ET
+
+from . import __version__, db, openapi, postman, runner
+
+
+def _color(enabled: bool):
+    def paint(code: str, text: str) -> str:
+        return f"\033[{code}m{text}\033[0m" if enabled else text
+    return paint
+
+
+def build_parser(default_data_dir: Path) -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="pyhttp run", description="Run requests headless and report the results (for CI).")
+    p.add_argument("targets", nargs="*", help="folder names or paths (A/B), request names or ids, or a collection "
+                                               "file (Postman v2.1, pyhttp export, OpenAPI). Default: everything")
+    p.add_argument("--data-dir", type=Path, default=default_data_dir, help=f"pyhttp data folder (default: {default_data_dir})")
+    p.add_argument("-e", "--env", help="environment to use (name); default: the active one")
+    p.add_argument("--env-file", type=Path, help="Postman environment file to use instead of a saved environment")
+    p.add_argument("--var", action="append", default=[], metavar="KEY=VALUE", help="set a global variable (repeatable)")
+    p.add_argument("--tag", action="append", default=[], help="only requests with this tag (repeatable)")
+    p.add_argument("-n", "--iterations", type=int, default=1, help="run everything N times")
+    p.add_argument("-d", "--data", type=Path, help="CSV or JSON variables file: one row of variable values per iteration")
+    p.add_argument("-P", "--parallel", type=int, nargs="?", const=8, default=0, metavar="N",
+                   help="send everything at once, at most N in flight (default 8), instead of in order")
+    p.add_argument("--bail", action="store_true", help="stop at the first failure")
+    p.add_argument("--delay", type=float, default=0, metavar="MS", help="pause between requests")
+    p.add_argument("--no-fail-on-http-error", action="store_true", help="4xx/5xx responses do not count as failures")
+    p.add_argument("--no-fail-on-tests", action="store_true", help="failed tests do not count as failures")
+    p.add_argument("--insecure", action="store_true", help="skip SSL certificate verification")
+    p.add_argument("--timeout", type=float, help="default request timeout in seconds")
+    p.add_argument("--junit", type=Path, help="write a JUnit XML report here")
+    p.add_argument("--html", type=Path, help="write an HTML report here")
+    p.add_argument("--json", type=Path, help="write the full results as JSON here")
+    p.add_argument("--name", help="name of the run (default: the targets)")
+    p.add_argument("-q", "--quiet", action="store_true", help="print only the summary")
+    p.add_argument("--no-color", action="store_true", help="plain output")
+    p.add_argument("--list", action="store_true", help="list what would run, then exit")
+    return p
+
+
+# ---------------------------------------------------------------- selection
+
+
+def _ordered() -> list[dict[str, Any]]:
+    """Every request in collection order: subfolders first, then the folder's own requests."""
+    folders = db.list_folders()
+    known = {f["id"] for f in folders}
+    kids: dict[str, list[dict[str, Any]]] = {}
+    for f in folders:
+        kids.setdefault(f["parent_id"] if f["parent_id"] in known else "", []).append(f)
+    reqs: dict[str, list[dict[str, Any]]] = {}
+    for r in db.list_requests():
+        reqs.setdefault(r["folder_id"] if r["folder_id"] in known else "", []).append(r)
+
+    def walk(fid: str) -> list[dict[str, Any]]:
+        out: list[dict[str, Any]] = []
+        for f in kids.get(fid, []):
+            out += walk(f["id"])
+        return out + reqs.get(fid, [])
+    return walk("")
+
+
+def _folder_paths() -> dict[str, str]:
+    folders = {f["id"]: f for f in db.list_folders()}
+    paths: dict[str, str] = {}
+    for fid in folders:
+        chain, f, seen = [], folders.get(fid), set()
+        while f and f["id"] not in seen:
+            seen.add(f["id"])
+            chain.append(f["name"])
+            f = folders.get(f["parent_id"]) if f.get("parent_id") else None
+        paths[fid] = "/".join(reversed(chain))
+    return paths
+
+
+def select(targets: list[str], tags: list[str]) -> list[dict[str, Any]]:
+    """Requests matching the targets (in collection order, no duplicates). Raises ValueError for unknown targets."""
+    ordered = _ordered()
+    if not targets:
+        chosen = ordered
+    else:
+        paths = _folder_paths()
+        under: dict[str, set[str]] = {}  # folder id -> itself and descendants
+        for fid, path in paths.items():
+            under[fid] = {g for g, p in paths.items() if p == path or p.startswith(path + "/")}
+        chosen_ids: list[str] = []
+        for t in targets:
+            tl = t.strip().strip("/").lower()
+            folder_hits = [fid for fid, path in paths.items() if path.lower() == tl or path.lower().rsplit("/", 1)[-1] == tl]
+            req_hits = [r["id"] for r in ordered if r["id"] == t or r["name"].lower() == tl]
+            if not folder_hits and not req_hits:
+                raise ValueError(f"no folder or request named “{t}”")
+            fids = set().union(*(under[f] for f in folder_hits)) if folder_hits else set()
+            for r in ordered:
+                if (r["folder_id"] in fids or r["id"] in req_hits) and r["id"] not in chosen_ids:
+                    chosen_ids.append(r["id"])
+        by_id = {r["id"]: r for r in ordered}
+        chosen = [by_id[i] for i in chosen_ids]
+    if tags:
+        chosen = [r for r in chosen if any(t in r["tags"] for t in tags)]
+    return chosen
+
+
+def load_file(path: Path) -> dict[str, Any]:
+    """A collection file in pyhttp's import shape."""
+    data = openapi.parse_text(path.read_text(encoding="utf-8-sig"))
+    if postman.is_collection(data):
+        return postman.from_collection(data)
+    if openapi.is_openapi(data):
+        return openapi.from_openapi(data)
+    if openapi.is_har(data):
+        return openapi.from_har(data)
+    if isinstance(data, list):
+        return {"folders": [], "requests": data, "environments": [], "variables": {}}
+    if isinstance(data, dict) and ("requests" in data or "folders" in data):
+        return {"folders": data.get("folders") or [], "requests": data.get("requests") or [],
+                "environments": data.get("environments") or [], "variables": data.get("variables") or {}}
+    raise ValueError(f"{path}: not a Postman collection, pyhttp export, OpenAPI spec or HAR file")
+
+
+# ------------------------------------------------------------------ reports
+
+
+def junit_xml(run: dict[str, Any]) -> str:
+    results = run["results"]
+    suites = ET.Element("testsuites", name=run["name"], tests=str(len(results)),
+                        failures=str(sum(1 for r in results if r["status"] == "failed")),
+                        time=f"{sum((r.get('duration_ms') or 0) for r in results) / 1000:.3f}")
+    by_iter: dict[int, list[dict[str, Any]]] = {}
+    for r in results:
+        by_iter.setdefault(int(r.get("iteration") or 1), []).append(r)
+    for it, items in by_iter.items():
+        suite = ET.SubElement(suites, "testsuite", name=run["name"] + (f" (iteration {it})" if len(by_iter) > 1 else ""),
+                              tests=str(len(items)), failures=str(sum(1 for r in items if r["status"] == "failed")),
+                              time=f"{sum((r.get('duration_ms') or 0) for r in items) / 1000:.3f}")
+        for r in items:
+            name = r["request_name"] + (f" · {r['body_name']}" if r.get("body_name") else "")
+            case = ET.SubElement(suite, "testcase", classname=run["name"], name=name,
+                                 time=f"{(r.get('duration_ms') or 0) / 1000:.3f}")
+            if r["status"] == "failed":
+                problems = []
+                if r.get("error"):
+                    problems.append(r["error"])
+                elif r.get("status_code") and r["status_code"] >= 400:
+                    problems.append(f"HTTP {r['status_code']}")
+                problems += [f"{t.get('name')}: {t.get('note') or 'failed'}" for t in r.get("tests") or [] if not t.get("passed")]
+                fail = ET.SubElement(case, "failure", message=(problems[0] if problems else "failed")[:500])
+                fail.text = "\n".join(problems)
+            tests = r.get("tests") or []
+            if tests:
+                out = ET.SubElement(case, "system-out")
+                out.text = "\n".join(f"[{'PASS' if t.get('passed') else 'FAIL'}] {t.get('name')}" + (f" — {t['note']}" if t.get("note") else "") for t in tests)
+    ET.indent(suites)
+    return '<?xml version="1.0" encoding="UTF-8"?>\n' + ET.tostring(suites, encoding="unicode")
+
+
+def html_report(run: dict[str, Any]) -> str:
+    e = html.escape
+    rows = []
+    for r in run["results"]:
+        tests = "".join(f"<li class='{'ok' if t.get('passed') else 'bad'}'>{'✓' if t.get('passed') else '✗'} {e(str(t.get('name')))}"
+                        f"{(' — ' + e(str(t['note']))) if t.get('note') else ''}</li>" for t in r.get("tests") or [])
+        rows.append(
+            f"<tr class='{e(r['status'])}'><td>{r['position']}</td><td>{e(r.get('method') or '')}</td>"
+            f"<td>{e(r['request_name'])}{(' · ' + e(r['body_name'])) if r.get('body_name') else ''}"
+            f"{f'<ul>{tests}</ul>' if tests else ''}{(chr(10) + '<div class=bad>' + e(r['error']) + '</div>') if r.get('error') else ''}</td>"
+            f"<td>{r.get('status_code') or '—'}</td><td>{(r.get('duration_ms') or 0):.0f} ms</td><td>{e(r['status'])}</td></tr>")
+    passed = sum(1 for r in run["results"] if r["status"] != "failed")
+    return f"""<!doctype html><html><head><meta charset="utf-8"><title>{e(run['name'])} — pyhttp report</title>
+<style>body{{font:14px system-ui,sans-serif;margin:24px;color:#1f2328}}table{{border-collapse:collapse;width:100%}}
+td,th{{border-bottom:1px solid #d0d7de;padding:6px 8px;text-align:left;vertical-align:top}}tr.failed td{{background:#fff1f0}}
+.ok{{color:#1a7f37}}.bad{{color:#cf222e}}ul{{margin:4px 0 0;padding-left:18px;font-size:12px}}.sum{{font-size:16px;margin:8px 0 16px}}</style>
+</head><body><h1>{e(run['name'])}</h1>
+<div class="sum">{passed}/{len(run['results'])} passed · {run['status']} · pyhttp {__version__} · {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(run['started_at']))}</div>
+<table><tr><th>#</th><th>Method</th><th>Request</th><th>Status</th><th>Time</th><th>Result</th></tr>{''.join(rows)}</table></body></html>"""
+
+
+# --------------------------------------------------------------------- main
+
+
+def main(argv: list[str], default_data_dir: Path) -> int:
+    args = build_parser(default_data_dir).parse_args(argv)
+    paint = _color(not args.no_color and sys.stdout.isatty())
+    if hasattr(sys.stdout, "reconfigure"):
+        try:
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        except Exception:  # noqa: BLE001
+            pass
+
+    files = [Path(t) for t in args.targets if Path(t).is_file() and Path(t).suffix.lower() in (".json", ".yaml", ".yml", ".har")]
+    tmp: tempfile.TemporaryDirectory[str] | None = None
+    if files:
+        # run straight from files: a throwaway data folder, the user's collection is not touched
+        tmp = tempfile.TemporaryDirectory(prefix="pyhttp-run-", ignore_cleanup_errors=True)
+        data_dir = Path(tmp.name)
+        targets = [t for t in args.targets if Path(t) not in files]
+        args.targets_from_files = True
+    else:
+        data_dir = args.data_dir.resolve()
+        targets = list(args.targets)
+        args.targets_from_files = False
+        if not (data_dir / "pyhttp.db").exists():
+            print(f"No pyhttp data in {data_dir} (use --data-dir, or pass a collection file)", file=sys.stderr)
+            return 2
+    try:
+        db.init(data_dir / "pyhttp.db")
+        if files:
+            from .app import import_collection
+            for f in files:
+                conv = load_file(f)
+                import_collection(conv["folders"], conv["requests"], conv.get("environments") or [],
+                                  conv.get("variables") or {}, False)
+        return _run(args, targets, data_dir, paint)
+    except ValueError as exc:
+        print(f"pyhttp run: {exc}", file=sys.stderr)
+        return 2
+    finally:
+        db.close()
+        if tmp:
+            tmp.cleanup()
+
+
+def _run(args: argparse.Namespace, targets: list[str], data_dir: Path, paint) -> int:
+    # environment, variables and settings for this run (restored afterwards when using the user's data)
+    restore: dict[str, Any] = {"active_env": db.get_setting("active_env"), "settings": db.app_settings(),
+                               "variables": db.get_variables()}
+    temp_env_id = None
+    try:
+        if args.env_file:
+            env = postman.from_environment(openapi.parse_text(args.env_file.read_text(encoding="utf-8-sig")))
+            temp_env_id = db.create_environment(env["name"] + " (pyhttp run)", env["variables"])["id"]
+            db.set_setting("active_env", temp_env_id)
+        elif args.env:
+            match = [e for e in db.list_environments() if e["name"].lower() == args.env.lower() or e["id"] == args.env]
+            if not match:
+                names = ", ".join(e["name"] for e in db.list_environments()) or "none"
+                raise ValueError(f"no environment “{args.env}” (have: {names})")
+            db.set_setting("active_env", match[0]["id"])
+        if args.var:
+            values = db.get_variables()
+            for kv in args.var:
+                k, sep, v = kv.partition("=")
+                if not sep or not k.strip():
+                    raise ValueError(f"--var expects KEY=VALUE, got “{kv}”")
+                values[k.strip()] = v
+            db.set_variables(values)
+        patch: dict[str, Any] = {}
+        if args.insecure:
+            patch["verify_ssl"] = False
+        if args.timeout:
+            patch["default_timeout"] = args.timeout
+        if patch:
+            db.update_settings(patch)
+
+        chosen = select(targets, args.tag)
+        if not chosen:
+            raise ValueError("nothing to run")
+        env = db.active_environment()
+        if args.list:
+            paths = _folder_paths()
+            for r in chosen:
+                where = paths.get(r["folder_id"] or "", "")
+                print(f"{r['method']:7} {(where + '/') if where else ''}{r['name']}   {paint('2', r['url'])}")
+            return 0
+
+        data_rows: list[dict[str, Any]] = []
+        if args.data:
+            from .app import parse_data_file
+            data_rows = parse_data_file(args.data.read_text(encoding="utf-8-sig"), args.data.name)
+        name = args.name or (" + ".join(targets) if targets else "Collection run")
+        options = {
+            "name": name, "stop_on_error": args.bail, "fail_on_http_error": not args.no_fail_on_http_error,
+            "fail_on_test": not args.no_fail_on_tests, "delay_ms": args.delay,
+            "iterations": max(1, args.iterations), "data": data_rows, "source": "cli",
+            "parallel": args.parallel > 0, "concurrency": args.parallel or 8,
+        }
+        if not args.quiet:
+            print(paint("1", f"pyhttp {__version__} · {name}") + paint("2", f" · {len(chosen)} request(s)"
+                  + (f" · environment {env['name']}" if env else "") + (f" · {max(1, args.iterations) if not data_rows else len(data_rows)} iterations" if (args.iterations > 1 or data_rows) else "")))
+        run = asyncio.run(_execute(chosen, options, data_dir, args.quiet, paint))
+    finally:
+        if temp_env_id:
+            db.delete_environment(temp_env_id)
+        db.set_setting("active_env", restore["active_env"])
+        if args.var:
+            db.set_variables(restore["variables"])
+        if args.insecure or args.timeout:
+            db.update_settings({k: restore["settings"][k] for k in ("verify_ssl", "default_timeout")})
+
+    results = run["results"]
+    failed = sum(1 for r in results if r["status"] == "failed")
+    tests = [t for r in results for t in r.get("tests") or []]
+    tests_failed = sum(1 for t in tests if not t.get("passed"))
+    total_ms = sum((r.get("duration_ms") or 0) for r in results)
+    summary = (f"{len(results) - failed}/{len(results)} requests passed"
+               + (f", {len(tests) - tests_failed}/{len(tests)} tests passed" if tests else "")
+               + f" · {total_ms / 1000:.2f}s · {run['status']}")
+    print(paint("32;1" if not failed and run["status"] == "completed" else "31;1", summary))
+    if failed and not args.quiet:
+        print(paint("31", "Failures:"))
+        for r in results:
+            if r["status"] == "failed":
+                why = r.get("error") or (f"HTTP {r['status_code']}" if (r.get("status_code") or 0) >= 400 else "")
+                bad = [t.get("name") for t in r.get("tests") or [] if not t.get("passed")]
+                print(f"  {r['position']}. {r['request_name']}: " + "; ".join(x for x in [why, *bad] if x))
+    for path, content in ((args.junit, junit_xml(run) if args.junit else None),
+                          (args.html, html_report(run) if args.html else None),
+                          (args.json, json.dumps(run, indent=2, ensure_ascii=False, default=str) if args.json else None)):
+        if path and content is not None:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+            if not args.quiet:
+                print(paint("2", f"Report: {path}"))
+    if not args.quiet and not args.targets_from_files:
+        print(paint("2", f"Outputs: {run['output_dir']}"))
+    return 1 if failed or run["status"] not in ("completed",) else 0
+
+
+async def _execute(chosen: list[dict[str, Any]], options: dict[str, Any], data_dir: Path, quiet: bool, paint) -> dict[str, Any]:
+    out_root = data_dir / "outputs"
+    out_root.mkdir(parents=True, exist_ok=True)
+    manager = runner.RunManager(out_root)
+    run = await manager.start_saved([r["id"] for r in chosen], options)
+    printed = 0
+    while True:
+        await asyncio.sleep(0.1)
+        cur = db.get_run(run["id"])
+        assert cur is not None
+        if not quiet:
+            for r in cur["results"][printed:]:
+                ok = r["status"] != "failed"
+                code = r.get("status_code")
+                mark = paint("32", "✓") if ok else paint("31", "✗")
+                label = r["request_name"] + (f" · {r['body_name']}" if r.get("body_name") else "")
+                it = f"[{r.get('iteration')}] " if (options.get("iterations") or 1) > 1 or options.get("data") else ""
+                print(f"{mark} {it}{r.get('method', ''):6} {label}  " + paint("2", f"{code or 'ERR'} · {(r.get('duration_ms') or 0):.0f} ms"))
+                if r.get("error"):
+                    print("    " + paint("31", r["error"]))
+                for t in r.get("tests") or []:
+                    if not t.get("passed"):
+                        print("    " + paint("31", f"✗ {t.get('name')}") + (paint("2", f" — {t['note']}") if t.get("note") else ""))
+            printed = len(cur["results"])
+        if not manager.is_active(run["id"]) and cur["status"] != "running":
+            return cur