|
| 1 | +JSON Contract & Snapshot Matching |
| 2 | +================================= |
| 3 | + |
| 4 | +``json_schema`` validates a value against an authored schema and ``jsonpath`` |
| 5 | +extracts values, but nothing matched two JSON *payloads* with relaxed rules |
| 6 | +(type-only, partial, ignore volatile paths) or diffed them path-by-path for |
| 7 | +contract / snapshot tests. This adds that layer; it composes with |
| 8 | +``json_schema`` (shape) and ``json_patch`` (structured edits). |
| 9 | + |
| 10 | +Pure standard library (``json``); deterministic; imports no ``PySide6``. |
| 11 | + |
| 12 | +Headless API |
| 13 | +------------ |
| 14 | + |
| 15 | +.. code-block:: python |
| 16 | +
|
| 17 | + from je_auto_control import match_json, diff_json, snapshot_json |
| 18 | +
|
| 19 | + report = match_json(actual, {"id": 1, "name": "Ada"}) |
| 20 | + if not report.ok: |
| 21 | + for m in report.mismatches: |
| 22 | + print(m["path"], m["kind"]) # e.g. "$.name" "changed" |
| 23 | +
|
| 24 | + # Pact-style "like": values may differ, types must match |
| 25 | + match_json(response, template, match_type=True) |
| 26 | + # subset match: extra keys in `actual` are allowed |
| 27 | + match_json(response, template, partial=True) |
| 28 | + # ignore volatile fields |
| 29 | + match_json(response, template, ignore=["$.created_at", "$.id"]) |
| 30 | +
|
| 31 | + diff_json(actual, expected) # [{path, kind, ...}] |
| 32 | + snapshot_json(actual, "golden/checkout.json") # write-if-absent, else compare |
| 33 | +
|
| 34 | +``match_json`` returns a ``MatchReport(ok, mismatches)`` where each mismatch is |
| 35 | +``{path, kind}`` with ``kind`` one of ``missing`` (in expected, absent from |
| 36 | +actual), ``extra`` (in actual, absent from expected), or ``changed``. Options: |
| 37 | +``partial`` drops ``extra`` mismatches (subset match), ``match_type`` accepts a |
| 38 | +``changed`` leaf whose types match (Pact ``like``), and ``ignore`` skips listed |
| 39 | +paths. ``diff_json`` is the raw path-tagged diff; ``normalize_json`` returns a |
| 40 | +canonical copy (sorted keys, ``drop`` keys removed) for stable comparison; |
| 41 | +``snapshot_json`` is golden-master testing (writes the file on first run, then |
| 42 | +matches against it). ``true`` stays distinct from ``1``. |
| 43 | + |
| 44 | +Executor commands |
| 45 | +----------------- |
| 46 | + |
| 47 | +``AC_match_json`` takes ``actual`` / ``expected`` (objects or JSON strings) plus |
| 48 | +optional ``partial`` / ``match_type`` and returns ``{ok, mismatches}``. |
| 49 | +``AC_diff_json`` returns ``{diffs}``. Both are exposed as MCP tools |
| 50 | +(``ac_match_json`` / ``ac_diff_json``) and as Script Builder commands under |
| 51 | +**Data**. |
0 commit comments