docs(tests): add tests README with coverage and commands\nchore(tools): add JSON report option to sanity CLI suite

Author: Nick Vaccarello

medical_diagnosis_model/tests/README.md

@@ -0,0 +1,39 @@
+# Tests Overview
+
+This directory contains unit tests and harnesses for the medical diagnosis model.
+
+## What we test
+
+- API v2 core
+  - `test_api_phase1.py`: validates responses against sample cases using FastAPI TestClient.
+- Selector math
+  - `test_selector.py`: checks Expected Information Gain (EIG) ranking on toy distributions.
+- Security & Ops
+  - `test_security_cors_rate.py`: CORS preflight (localhost:3000), API key auth (401 vs 200), rate limiting (429 on bursts).
+- Adaptive endpoints (alpha)
+  - `test_adaptive_endpoints.py`: start → answer → finish flow.
+
+## How to run
+
+```bash
+# From repo root
+PYTHONPATH="$PWD:$PWD/medical_diagnosis_model" MDM_QUICK_TRAIN=1 \
+pytest -q medical_diagnosis_model/tests
+```
+
+## Sanity CLI (recommended)
+
+Run end-to-end checks and write a JSON report:
+
+```bash
+cd medical_diagnosis_model
+python tools/sanity.py suite --auto-start --api-key devkey \
+  --with-api --with-export --with-rate --with-adaptive \
+  --report-json reports/sanity_latest.json
+```
+
+## Outputs and artifacts
+
+- tests/phase_1_backend/outputs/: cURL-based runs and summaries (gitignored)
+- exports/: generated PDFs from /export (gitignored)
+- reports/sanity_latest.json: suite status summary

medical_diagnosis_model/tools/sanity.py

@@ -212,18 +212,57 @@ def cmd_adaptive(args: argparse.Namespace) -> None:
 
 
 def cmd_suite(args: argparse.Namespace) -> None:
+    statuses = {
+        "data": None,
+        "tests": None,
+        "api": None,
+        "export": None,
+        "rate": None,
+        "adaptive": None,
+    }
+
+    def _safe(run_fn, key):
+        try:
+            run_fn(args)
+            statuses[key] = True
+        except SystemExit:
+            statuses[key] = False
+
     # Always run data + tests
-    cmd_data(args)
-    cmd_tests(args)
+    _safe(cmd_data, "data")
+    _safe(cmd_tests, "tests")
     # Optionally run API-related checks
     if args.with_api:
-        cmd_api(args)
+        _safe(cmd_api, "api")
     if args.with_export:
-        cmd_export(args)
+        _safe(cmd_export, "export")
     if args.with_rate:
-        cmd_rate(args)
+        _safe(cmd_rate, "rate")
     if args.with_adaptive:
-        cmd_adaptive(args)
+        _safe(cmd_adaptive, "adaptive")
+
+    # Optional JSON report
+    if getattr(args, "report_json", None):
+        import json, datetime
+        report = {
+            "timestamp": datetime.datetime.utcnow().isoformat() + "Z",
+            "config": {
+                "with_api": bool(args.with_api),
+                "with_export": bool(args.with_export),
+                "with_rate": bool(args.with_rate),
+                "with_adaptive": bool(args.with_adaptive),
+            },
+            "statuses": statuses,
+        }
+        out_path = Path(args.report_json)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
+        print(f"Wrote sanity report to {out_path}")
+
+    # Exit non-zero if any selected check failed
+    failures = [k for k, v in statuses.items() if v is False]
+    if failures:
+        raise SystemExit(1)
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -268,6 +307,7 @@ def add_api_opts(sp):
     sp_suite.add_argument("--with-export", action="store_true")
     sp_suite.add_argument("--with-rate", action="store_true")
     sp_suite.add_argument("--with-adaptive", action="store_true")
+    sp_suite.add_argument("--report-json", default=None, help="Write JSON summary to this path")
     sp_suite.set_defaults(func=cmd_suite)
 
     return p