test(m1): add conftest fixtures and golden helpers

tests/helpers/golden.py

@@ -0,0 +1,51 @@
+"""Golden-file comparison, with regeneration that has to be asked for.
+
+A golden test is only worth its file if updating that file is a deliberate
+act. The failure mode this module exists to prevent is the silent
+self-heal: a comparator that rewrites the reference whenever it disagrees
+turns every golden into a mirror and every golden test into a no-op. So the
+rewrite lives behind the ``--update-golden`` flag, and the flag defaults off.
+
+The update flag is a parameter rather than something this module reads off
+the pytest config, so the rewrite path is reachable from an ordinary test
+without running pytest inside pytest. `tests/conftest.py` binds the flag to
+the `golden` fixture for callers who want the wiring instead.
+"""
+
+import difflib
+import os
+
+
+def assert_golden(path, actual, update=False):
+    """Compare ``actual`` against the golden file at ``path``.
+
+    With ``update`` the file is rewritten and nothing is asserted. Without it,
+    a missing golden and a differing golden both raise, and the message
+    carries a unified diff -- "golden mismatch" on its own sends the reader
+    back to the file to work out what moved.
+    """
+    if update:
+        with open(path, "w", encoding="utf-8") as handle:
+            handle.write(actual)
+        return
+
+    if not os.path.exists(path):
+        raise AssertionError(
+            "golden %r does not exist yet. Re-run with --update-golden to "
+            "create it, having first read the output you are blessing." % path
+        )
+
+    with open(path, "r", encoding="utf-8") as handle:
+        expected = handle.read()
+    if expected == actual:
+        return
+
+    diff = "".join(
+        difflib.unified_diff(
+            expected.splitlines(keepends=True),
+            actual.splitlines(keepends=True),
+            fromfile="golden: %s" % path,
+            tofile="actual",
+        )
+    )
+    raise AssertionError("golden %r does not match actual output:\n%s" % (path, diff))