Merge pull request #65 from ber-data/copilot/fix-64

Add tests targeting functions that expose sample data

Author: ialarmedalien

.github/workflows/run_tests.yaml

@@ -37,22 +37,28 @@ jobs:
                   make validate-examples
               continue-on-error: true
 
+            - name: Test Python code
+              id: test_python_code
+              run: |
+                  make test-python
+              continue-on-error: true
+
             - name: Test documentation generation
               id: test_docgen
               run: |
                 make gendoc
               continue-on-error: true
 
             - name: outcome failure
-              if: steps.lint_linkml.outcome != 'success' || steps.validate_sample_data.outcome != 'success' || steps.test_docgen.outcome != 'success'
+              if: steps.lint_linkml.outcome != 'success' || steps.validate_sample_data.outcome != 'success' || steps.test_python_code.outcome != 'success' || steps.test_docgen.outcome != 'success'
               run: |
                   echo "linkml linting: ${{ steps.lint_linkml.outcome }}"
                   echo "sample data validation: ${{ steps.validate_sample_data.outcome }}"
                   echo "documentation generator: ${{ steps.test_docgen.outcome }}"
                   exit 1
 
             - name: outcome success
-              if: steps.lint_linkml.outcome == 'success' && steps.validate_sample_data.outcome == 'success' && steps.test_docgen.outcome == 'success'
+              if: steps.lint_linkml.outcome == 'success' && steps.validate_sample_data.outcome == 'success' && steps.test_python_code.outcome == 'success' && steps.test_docgen.outcome == 'success'
               run: |
                   echo All tests passed successfully!
                   exit 0

src/sample_data/__init__.py

@@ -3,10 +3,24 @@
 import json
 from importlib import resources
 from importlib.abc import Traversable
+from pathlib import Path
 from typing import Any
 
 import yaml
 
+# Define the path someone could use to `import` the Python package _containing_ the
+# `invalid/` and `valid/` directories (e.g. `import {something}`); which, currently,
+# happens to be the directory containing this `__init__.py` file.
+PACKAGE_IMPORT_PATH = "sample_data"
+
+# Define a mapping from file extension to a function that can be used to parse the
+# content of a file having that extension.
+PARSERS_BY_FILE_EXTENSION = {
+    "yaml": yaml.safe_load,
+    "yml": yaml.safe_load,
+    "json": json.loads,
+}
+
 
 def _get_traversable() -> Traversable:
     """Get a `Traversable` object for the `sample_data/` package.
@@ -23,13 +37,8 @@ def _get_traversable() -> Traversable:
     - https://docs.python.org/3/library/importlib.resources.abc.html#importlib.resources.abc.Traversable
 
     """
-    # Define the path someone could use to `import` the Python package _containing_ the
-    # `invalid/` and `valid/` directories (e.g. `import {something}`); which, currently,
-    # happens to be the directory containing this `__init__.py` file.
-    package_import_path = "sample_data"
-
     # Create a `Traversable` object that can be passed to the `resources.as_file()` function.
-    return resources.files(package_import_path)
+    return resources.files(PACKAGE_IMPORT_PATH)
 
 
 def get_sample_data_file_paths() -> list[str]:
@@ -44,12 +53,14 @@ def get_sample_data_file_paths() -> list[str]:
 
     """
     traversable = _get_traversable()
+    file_extension_patterns = [f"**/*.{ext}" for ext in PARSERS_BY_FILE_EXTENSION]
     with resources.as_file(traversable) as path:
-        return [
+        paths = [
             str(p.relative_to(path))
-            for pattern in ["**/*.yaml", "**/*.yml", "**/*.json"]
+            for pattern in file_extension_patterns
             for p in path.glob(pattern)
         ]
+        return sorted(paths)
 
 
 def get_sample_data_text(file_path: str, encoding: str = "utf-8") -> str:
@@ -84,15 +95,15 @@ def get_sample_data(file_path: str, encoding: str = "utf-8") -> Any:  # noqa: AN
 
     """
     # Determine which parsing function we will use, based upon the file's extension.
-    if file_path.endswith((".yaml", ".yml")):
-        parse = yaml.safe_load
-    elif file_path.endswith(".json"):
-        parse = json.loads
+    path = Path(file_path)
+    file_extension = path.suffix.lstrip(".")  # ".yaml" -> "yaml"
+    if file_extension in PARSERS_BY_FILE_EXTENSION:
+        parse = PARSERS_BY_FILE_EXTENSION[file_extension]
     else:
         # Raise an error indicating that we don't support files having that extension.
         # Note: The `!r` after the in-string variable below calls `repr()` on the value.
         #       Since the value is a string, the string will appear wrapped in quotes.
-        msg = f"File extension suggest an unsupported file type: {file_path!r}"
+        msg = f"Filename extension suggests an unsupported file type: {file_path!r}"
         raise ValueError(msg)
 
     text = get_sample_data_text(file_path, encoding=encoding)

tests/test_sample_data.py

@@ -0,0 +1,95 @@
+"""Tests targeting functions that expose sample data."""
+
+import json
+from collections.abc import Generator
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import pytest
+import yaml
+
+from sample_data import get_sample_data, get_sample_data_file_paths, get_sample_data_text
+
+
+@pytest.fixture
+def sample_json_content() -> str:
+    """Fixture that returns the text content of a sample JSON file."""
+    return r"""
+{
+  "id": "001",
+  "name": "foo bar",
+  "primary email": "foo.bar@example.com",
+  "age_in_years": 33
+}
+"""
+
+@pytest.fixture
+def sample_yaml_content() -> str:
+    """Fixture that returns the text content of a sample YAML file."""
+    return r"""
+# Some YAML documents begin with "front matter".
+---
+id: "001"
+name: foo bar
+primary email: foo.bar@example.com
+age_in_years: 33
+"""
+
+@pytest.fixture(autouse=True)
+def mock__get_traversable(
+    monkeypatch: Generator[pytest.MonkeyPatch, None, None],
+    sample_yaml_content: str,
+    sample_json_content: str,
+) -> Generator[None, None, None]:
+    """Fixture that mocks the `sample_data._get_traversable` helper function.
+
+    This fixture (a) creates a temporary directory, (b) populates it with sample data files,
+    and (c) patches the `_get_traversable` function so it returns a `Path` object pointing
+    to that temporary directory. This decouples the tests from the contents of the real
+    `sample_data/` directory that the module-under-test accesses in production.
+
+    Note: All `Path` objects are also `Traversable` object.
+    """
+    with TemporaryDirectory() as temp_dir:
+        temp_dir_path = Path(temp_dir)
+        (temp_dir_path / "data.json").write_text(sample_json_content)
+        (temp_dir_path / "data.yaml").write_text(sample_yaml_content)
+        (temp_dir_path / "data.yml").write_text(sample_yaml_content)
+        (temp_dir_path / "data.txt").write_text("some text")  # unsupported file suffix
+        monkeypatch.setattr("sample_data._get_traversable", lambda: temp_dir_path)
+        yield None
+
+
+def test_get_sample_data_file_paths_returns_list_of_file_paths_supported() -> None:
+    """Test that `get_sample_data_file_paths` returns a list of the file paths we support."""
+    assert get_sample_data_file_paths() == ["data.json", "data.yaml", "data.yml"]
+
+
+def test_get_sample_data_text_returns_expected_sample_data_as_string(
+    sample_json_content: str,
+    sample_yaml_content: str,
+) -> None:
+    """Test that `get_sample_data_text` returns the sample data we expect, as a string."""
+    for path in get_sample_data_file_paths():
+        if path == "data.json":
+            assert sample_json_content == get_sample_data_text(path)
+        if path in ("data.yaml", "data.yml"):
+            assert sample_yaml_content == get_sample_data_text(path)
+
+
+def test_get_sample_data_returns_sample_data_as_python_object(
+    sample_json_content: str,
+    sample_yaml_content: str,
+) -> None:
+    """Test that `get_sample_data` returns sample data as a Python object."""
+    for path in get_sample_data_file_paths():
+        if path == "data.json":
+            assert json.loads(sample_json_content) == get_sample_data(path)
+        if path in ("data.yaml", "data.yml"):
+            assert yaml.safe_load(sample_yaml_content) == get_sample_data(path)
+
+
+def test_get_sample_data_rejects_unsupported_filename_extensions() -> None:
+    """Test that `get_sample_data` raises an exception for an unsupported filename extension."""
+    with pytest.raises(ValueError, match=r"^Filename extension"):
+        get_sample_data("my_file.txt")