robotframework-snapshot 0.1.0__py3-none-any.whl

SnapshotLibrary/__init__.py

@@ -0,0 +1,6 @@
+"""Snapshot testing for text and structured data in Robot Framework."""
+
+from .library import SnapshotLibrary
+from .version import __version__
+
+__all__ = ["SnapshotLibrary", "__version__"]

SnapshotLibrary/__main__.py

@@ -0,0 +1,77 @@
+"""Command line: ``python -m SnapshotLibrary unused <output dir> [--delete]``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+
+from . import unused as unused_module
+
+
+def _relative(path) -> str:
+    try:
+        return os.path.relpath(path)
+    except ValueError:
+        return str(path)
+
+
+def unused_command(arguments) -> int:
+    result = unused_module.report(arguments.output_directory)
+    if result is None:
+        print(
+            f"No snapshot usage records found below '{arguments.output_directory}'. "
+            "Pass the output directory of a run that used SnapshotLibrary."
+        )
+        return 2
+    print(f"Checked {len(result.checked)} suite(s).")
+    if result.not_checked:
+        print(
+            f"Not checked, because not all tests ran and passed: {len(result.not_checked)} suite(s)."
+        )
+        for source in result.not_checked:
+            print(f"  {_relative(source)}")
+    if result.clean:
+        print("No unused snapshots.")
+        return 0
+    if result.unused:
+        print(f"Unused snapshots: {len(result.unused)}")
+        for path in result.unused:
+            print(f"  {_relative(path)}")
+    if result.orphan_directories:
+        print(f"Snapshot directories without a suite file: {len(result.orphan_directories)}")
+        for path in result.orphan_directories:
+            print(f"  {_relative(path)}")
+    if arguments.delete:
+        for path in result.unused:
+            path.unlink()
+        for path in result.orphan_directories:
+            shutil.rmtree(path)
+        print("Deleted.")
+        return 0
+    print("Delete them, or run again with --delete.")
+    return 1
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m SnapshotLibrary")
+    commands = parser.add_subparsers(dest="command", required=True)
+    unused = commands.add_parser(
+        "unused",
+        help="report snapshot files that no test used in a finished run",
+        description=(
+            "Reads the usage records of a finished robot or pabot run and lists snapshot "
+            "files no test used. Exit code 0: nothing unused, 1: unused snapshots found, "
+            "2: no records found."
+        ),
+    )
+    unused.add_argument("output_directory", help="the --outputdir of the run")
+    unused.add_argument("--delete", action="store_true", help="delete what is reported")
+    unused.set_defaults(handler=unused_command)
+    arguments = parser.parse_args(argv)
+    return arguments.handler(arguments)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

SnapshotLibrary/core.py

@@ -0,0 +1,149 @@
+"""The snapshot decision logic, free of any Robot Framework dependency."""
+
+from __future__ import annotations
+
+import copy
+import difflib
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, Iterable, List, Optional, Tuple
+
+from . import jsonpath, serializers, store, xmlpath
+from .normalizers import Normalizer, apply_all
+
+
+class Outcome(Enum):
+    MATCHED = "matched"
+    RECORDED = "recorded"
+    UPDATED = "updated"
+    MISSING = "missing"
+    MISMATCH = "mismatch"
+
+
+@dataclass
+class Result:
+    outcome: Outcome
+    path: Path
+    actual: str
+    expected: Optional[str] = None
+    diff: Optional[List[str]] = None
+
+    @property
+    def passed(self) -> bool:
+        return self.outcome in (Outcome.MATCHED, Outcome.RECORDED, Outcome.UPDATED)
+
+
+def split_paths(ignore) -> List[str]:
+    """``ignore`` is one JSONPath, several separated by ``;``, or a list."""
+    if not ignore:
+        return []
+    if isinstance(ignore, str):
+        ignore = ignore.split(";")
+    return [str(path).strip() for path in ignore if str(path).strip()]
+
+
+def prepare(
+    value: Any,
+    fmt: str = "auto",
+    ignore=None,
+    normalizers: Iterable[Normalizer] = (),
+):
+    """Serialise, mask and normalise ``value``. Returns ``(text, extension)``."""
+    data, extension = serializers.to_data(value, fmt)
+    paths = split_paths(ignore)
+    if paths:
+        if extension == serializers.JSON:
+            data = copy.deepcopy(data)
+            for path in paths:
+                jsonpath.mask(data, path)
+        elif extension == serializers.XML:
+            data = serializers.canonical_xml(xmlpath.mask(data, paths))
+        else:
+            raise ValueError(
+                "ignore= needs structured data: JSONPath for a dictionary, a list or "
+                "a JSON string with format=json, XPath for XML with format=xml. "
+                "For plain text, use a normalizer."
+            )
+    text = serializers.render(data, extension)
+    text = apply_all(text, normalizers)
+    return serializers.normalize_text(text), extension
+
+
+UPDATE_HINT = "If the change is intended, update the snapshot with: --variable REFERENCE_RUN:True"
+# Robot Framework counts a message line longer than this as several lines
+# when it checks a failure message against --maxerrorlines.
+_MESSAGE_LINE_WIDTH = 78
+
+
+def _message_lines(lines: Iterable[str]) -> int:
+    return sum(max(1, -(-len(line) // _MESSAGE_LINE_WIDTH)) for line in lines)
+
+
+def _omitted_note(count: int) -> str:
+    return (
+        f"... {count} more diff line{'s' if count != 1 else ''}. The full diff is in the log; "
+        "run with --maxerrorlines NONE to show it here."
+    )
+
+
+def mismatch_message(label: str, diff: List[str], max_lines: Optional[int] = None) -> Tuple[str, int]:
+    """The failure message for a snapshot that does not match, and how many diff lines it leaves out.
+
+    Robot Framework removes the middle of a failure message that is longer
+    than ``max_lines`` (its ``--maxerrorlines``, ``None`` for no limit). To
+    keep the start of the diff readable the message is shortened here
+    instead: diff lines are shown from the top until the limit is reached,
+    followed by a note on how to see the rest.
+    """
+    header = [f"Snapshot '{label}' does not match."]
+    footer = ["", UPDATE_HINT]
+    if max_lines is None or _message_lines(header + diff + footer) <= max_lines:
+        return "\n".join(header + diff + footer), 0
+    budget = max_lines - _message_lines(header + footer + [_omitted_note(len(diff))])
+    shown: List[str] = []
+    for line in diff:
+        if _message_lines(shown + [line]) > budget:
+            break
+        shown.append(line)
+    omitted = len(diff) - len(shown)
+    return "\n".join(header + shown + [_omitted_note(omitted)] + footer), omitted
+
+
+def unified_diff(expected: str, actual: str) -> List[str]:
+    # No path in the header: every message that shows a diff already names the snapshot.
+    return list(
+        difflib.unified_diff(
+            expected.splitlines(),
+            actual.splitlines(),
+            fromfile="snapshot",
+            tofile="actual",
+            lineterm="",
+        )
+    )
+
+
+def check(path: Path, actual: str, update: bool = False, strict: bool = False) -> Result:
+    """Compare ``actual`` with the snapshot at ``path`` and record or update as the mode allows.
+
+    | Mode    | Snapshot missing | Snapshot differs |
+    | default | record           | mismatch         |
+    | update  | record           | overwrite        |
+    | strict  | missing          | mismatch         |
+
+    ``update`` wins over ``strict`` when both are set.
+    """
+    path = Path(path)
+    if not path.is_file():
+        if strict and not update:
+            return Result(Outcome.MISSING, path, actual)
+        store.write(path, actual)
+        return Result(Outcome.RECORDED, path, actual)
+    expected = store.read(path)
+    if expected == actual:
+        return Result(Outcome.MATCHED, path, actual, expected)
+    if update:
+        store.write(path, actual)
+        return Result(Outcome.UPDATED, path, actual, expected)
+    diff = unified_diff(expected, actual)
+    return Result(Outcome.MISMATCH, path, actual, expected, diff)

SnapshotLibrary/jsonpath.py

@@ -0,0 +1,96 @@
+"""A small JSONPath subset used to mask values before a snapshot is taken.
+
+Supported: ``$.key``, ``$['key']``, ``$.list[0]``, ``$.list[*]``, ``$.*`` and
+the recursive ``$..key``. That covers "ignore this field wherever it is"
+without adding a dependency.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, List, Tuple
+
+IGNORED = "<IGNORED>"
+
+_TOKEN = re.compile(
+    r"""
+    \.\.(?P<deep>[^.\[\]]+)           # ..key
+  | \.(?P<key>[^.\[\]]+)              # .key or .*
+  | \[\s*(?P<index>-?\d+)\s*\]        # [0]
+  | \[\s*\*\s*\]                      # [*]
+  | \[\s*(?P<quote>['"])(?P<qkey>.*?)(?P=quote)\s*\]   # ['key']
+    """,
+    re.VERBOSE,
+)
+
+
+def parse(path: str) -> List[Tuple[str, Any]]:
+    path = path.strip()
+    if not path.startswith("$"):
+        raise ValueError(f"JSONPath '{path}' must start with '$'.")
+    tokens: List[Tuple[str, Any]] = []
+    position = 1
+    while position < len(path):
+        match = _TOKEN.match(path, position)
+        if not match:
+            raise ValueError(f"Unsupported JSONPath syntax in '{path}' at position {position}.")
+        if match.group("deep") is not None:
+            tokens.append(("deep", match.group("deep")))
+        elif match.group("key") is not None:
+            key = match.group("key")
+            tokens.append(("wild", None) if key == "*" else ("key", key))
+        elif match.group("index") is not None:
+            tokens.append(("index", int(match.group("index"))))
+        elif match.group("qkey") is not None:
+            tokens.append(("key", match.group("qkey")))
+        else:
+            tokens.append(("wild", None))
+        position = match.end()
+    if not tokens:
+        raise ValueError(f"JSONPath '{path}' selects the whole value; nothing would be left to compare.")
+    return tokens
+
+
+def _children(node: Any):
+    if isinstance(node, dict):
+        return list(node.keys())
+    if isinstance(node, list):
+        return list(range(len(node)))
+    return []
+
+
+def _apply(node: Any, tokens: List[Tuple[str, Any]], placeholder: str) -> int:
+    kind, arg = tokens[0]
+    last = len(tokens) == 1
+    hits = 0
+
+    def visit(container, key):
+        nonlocal hits
+        if last:
+            container[key] = placeholder
+            hits += 1
+        else:
+            hits += _apply(container[key], tokens[1:], placeholder)
+
+    if kind == "key":
+        if isinstance(node, dict) and arg in node:
+            visit(node, arg)
+    elif kind == "index":
+        if isinstance(node, list) and -len(node) <= arg < len(node):
+            visit(node, arg)
+    elif kind == "wild":
+        for key in _children(node):
+            visit(node, key)
+    elif kind == "deep":
+        if isinstance(node, dict) and arg in node:
+            visit(node, arg)
+        for key in _children(node):
+            child = node[key]
+            if isinstance(child, (dict, list)) and not (last and key == arg):
+                hits += _apply(child, tokens, placeholder)
+    return hits
+
+
+def mask(data: Any, path: str, placeholder: str = IGNORED) -> int:
+    """Replace every value selected by ``path`` in place. Returns the hit count."""
+    return _apply(data, parse(path), placeholder)