Add some docs

scripts/v21/tests/test_code_generator.py

@@ -1,6 +1,17 @@
+""" Some of the tests in this module load schema files from scripts/v21/tests/fixtures,
+generate code and compare that code against the 'golden files' in scripts/v21/tests/golden_files.
+
+Let's say you realize that the code generator contains a bug. The enums generated for schema
+TransactionEventRequest are incorrect. To use this schema in the the unit perform the following 2 steps:
+
+1. Add a copy of the schema to scripts/v21/tests/fixtures/enums/TransactionEventRequest.json.
+2. Create a Python file with the expected code output in scripts/v21/tests/golden_files/enums/TransactionEventRequest.py.
+
+Now run the tests with `poetry run pytest scripts/v21/tests`.
+"""
 import json
 import pathlib
-from dataclasses import dataclass
+from typing import List, Tuple
 
 import pytest
 
@@ -15,9 +26,11 @@
 
 PARENT_DIR = pathlib.Path(__file__).parent
 FIXTURES_DIR = PARENT_DIR / "fixtures"
+GOLDEN_FILES_DIR = PARENT_DIR / "golden_files"
 
 
-def _load_objects(path: pathlib.Path) -> list[(str, Object)]:
+def _load_objects(path: pathlib.Path) -> List[Tuple[str, Object]]:
+    """Load all schema files at `path` as `Object`s."""
     schema_files = sorted(path.glob("*.json"))
 
     objects = []
@@ -35,42 +48,31 @@ def _load_objects(path: pathlib.Path) -> list[(str, Object)]:
     return objects
 
 
-def compare_code_against_golden_file(code: str, golden_file: pathlib.Path):
-    if not golden_file.exists():
-        raise FileNotFoundError(f"Golden file '{golden_file}' doesn't exists")
-
-    assert code == golden_file.open().read()
-
-
 @pytest.mark.parametrize("name, object", _load_objects(FIXTURES_DIR / "enums"))
 def test_generate_enums(name: str, object: Object):
     code = generate_enums([object])
-    compare_code_against_golden_file(
-        code, PARENT_DIR / "golden_files" / "enums" / f"{name}.py"
-    )
+    compare_code_against_golden_file(code, GOLDEN_FILES_DIR / "enums" / f"{name}.py")
 
 
 @pytest.mark.parametrize("name, object", _load_objects(FIXTURES_DIR / "datatypes"))
 def test_generate_types(name: str, object: Object):
     code = generate_types([object])
     compare_code_against_golden_file(
-        code, PARENT_DIR / "golden_files" / "datatypes" / f"{name}.py"
+        code, GOLDEN_FILES_DIR / "datatypes" / f"{name}.py"
     )
 
 
 @pytest.mark.parametrize("name, object", _load_objects(FIXTURES_DIR / "calls"))
 def test_generate_calls(name: str, object: Object):
     code = generate_calls([object])
-    compare_code_against_golden_file(
-        code, PARENT_DIR / "golden_files" / "calls" / f"{name}.py"
-    )
+    compare_code_against_golden_file(code, GOLDEN_FILES_DIR / "calls" / f"{name}.py")
 
 
 @pytest.mark.parametrize("name, object", _load_objects(FIXTURES_DIR / "call_results"))
 def test_generate_call_results(name: str, object: Object):
     code = generate_call_results([object])
     compare_code_against_golden_file(
-        code, PARENT_DIR / "golden_files" / "call_results" / f"{name}.py"
+        code, GOLDEN_FILES_DIR / "call_results" / f"{name}.py"
     )
 
 
@@ -85,3 +87,11 @@ def test_generate_call_results(name: str, object: Object):
 )
 def test_camel_to_snake_case(input: str, output: str):
     assert camel_to_snake_case(input) == output
+
+
+def compare_code_against_golden_file(code: str, golden_file: pathlib.Path):
+    """Verify that `code` matches the content of `golden_file`."""
+    if not golden_file.exists():
+        raise FileNotFoundError(f"Golden file '{golden_file}' doesn't exists")
+
+    assert code == golden_file.open().read()