diff --git a/tests/test_generate_type_registry.py b/tests/test_generate_type_registry.py
new file mode 100644
index 00000000..1aa62599
--- /dev/null
+++ b/tests/test_generate_type_registry.py
@@ -0,0 +1,56 @@
+from __future__ import annotations
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SCRIPT = REPO_ROOT / "scripts" / "generate_type_registry.py"
+REGISTRY_DIR = REPO_ROOT / "docs" / "type_registry"
+
+
+def test_script_runs_without_error() -> None:
+ result = subprocess.run([sys.executable, str(SCRIPT)], capture_output=True, text=True, cwd=REPO_ROOT)
+ assert result.returncode == 0, f"stderr: {result.stderr}"
+
+
+def test_script_generates_index_md() -> None:
+ subprocess.run([sys.executable, str(SCRIPT)], capture_output=True, text=True, cwd=REPO_ROOT, check=True)
+ index_path = REGISTRY_DIR / "index.md"
+ assert index_path.exists()
+
+
+def test_script_generates_type_aliases_md() -> None:
+ subprocess.run([sys.executable, str(SCRIPT)], capture_output=True, text=True, cwd=REPO_ROOT, check=True)
+ aliases_path = REGISTRY_DIR / "type_aliases.md"
+ assert aliases_path.exists()
+ content = aliases_path.read_text()
+ assert "Metadata" in content
+ assert "CommsLogEntry" in content
+ assert "FileItems" in content
+
+
+def test_script_generates_per_source_file_md() -> None:
+ subprocess.run([sys.executable, str(SCRIPT)], capture_output=True, text=True, cwd=REPO_ROOT, check=True)
+ models_path = REGISTRY_DIR / "src_models.md"
+ assert models_path.exists()
+
+
+def test_check_mode_exits_zero_when_in_sync() -> None:
+ subprocess.run([sys.executable, str(SCRIPT)], capture_output=True, text=True, cwd=REPO_ROOT, check=True)
+ result = subprocess.run([sys.executable, str(SCRIPT), "--check"], capture_output=True, text=True, cwd=REPO_ROOT)
+ assert result.returncode == 0, f"--check failed; stderr: {result.stderr}"
+
+
+def test_check_mode_exits_nonzero_when_drifting() -> None:
+ subprocess.run([sys.executable, str(SCRIPT)], capture_output=True, text=True, cwd=REPO_ROOT, check=True)
+ index_path = REGISTRY_DIR / "index.md"
+ original = index_path.read_text()
+ index_path.write_text(original + "\n# fake drift marker\n", encoding="utf-8")
+ try:
+  result = subprocess.run([sys.executable, str(SCRIPT), "--check"], capture_output=True, text=True, cwd=REPO_ROOT)
+  assert result.returncode == 1, f"--check should fail on drift; got {result.returncode}; stderr: {result.stderr}"
+ finally:
+  index_path.write_text(original, encoding="utf-8")
+  subprocess.run([sys.executable, str(SCRIPT)], capture_output=True, text=True, cwd=REPO_ROOT, check=True)
\ No newline at end of file