tests: add first approval tests

docs/development-setup.md

@@ -70,6 +70,7 @@ celery --app sketch_map_tool.tasks worker --loglevel=INFO
 
 ```bash
 mamba activate smt
+pybabel compile -d sketch_map_tool/translations
 flask --app sketch_map_tool/routes.py --debug run
 # Go to http://127.0.0.1:5000
 ```
@@ -104,12 +105,26 @@ pytest
 
 #### Integration Tests
 
-The integration test suite utilizes the Testcontainers framework to run unique instances of Redis and Postgres for each test session. It also configures and starts Flask and Celery workers in the background.
+The integration test suite utilizes the [Testcontainers framework](https://testcontainers.com/) to run unique instances of Redis and Postgres for each test session. It also configures and starts Flask and Celery workers in the background.
 
 Many fixtures are written to a temporary directory on disk managed by Pytest. This makes it easy to inspect the results at various steps of the program (E.g. Marking detection pipeline). Unix users usually find this directory under `/tmp/pytest-of-{user}/pytest-current/{uuid}/`. The UUID of requests triggered by the tests (E.g. Create or digitize) is the directory name.
 
 The integration tests will make requests external services. Among others requests are made to HeiGIT Maps (WMS) to retrieve basemap images. Those requests can only be made from HeiGITs internal network.
 
+Some test are using the [Approval Testing methodology](https://approvaltests.com/).
+Approval tests capture the output (snapshot) of a piece of code and compare it
+with a previously approved version of the output.
+
+Once the output has been *approved* then as long as the output stays the same
+the test will pass. A test fails if the *received* output is not identical to
+the approved version. In that case, the difference of the received and the
+approved output is reported to the tester. The representation of the report can
+take any form: A diff-tool comparing received and approved text or images side-by-side.
+
+In the case of the Sketch Map Tool the report takes the form of two images
+side-by-side, the uploaded sketch map with markings (input) and the resulting
+GeoJSON with the detected markings.
+
 ### Update dependencies
 
 When dependencies changed the environment can be updated by running:

pyproject.toml

@@ -49,6 +49,10 @@ testcontainers-postgres = "^0.0.1rc1"
 testcontainers-redis = "^0.0.1rc1"
 hypothesis = "^6.88.4"
 ruff = "^0.1.15"
+approvaltests = "^12.0.0"
+matplotlib = "^3.8.4"
+geopandas = "^0.14.4"
+numpy = "^1.26.4"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

tests/comparator.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+import geopandas
+from approvaltests.core import FileComparator
+
+
+class GeoJSONComparator(FileComparator):
+    def compare(self, received_path: str, approved_path: str) -> bool:
+        if not Path(approved_path).exists() or Path(approved_path).stat().st_size == 0:
+            return False
+
+        # EPSG:8857 - small scale equal-area mapping
+        df_received = geopandas.read_file(received_path).to_crs("EPSG:8857")
+        df_approved = geopandas.read_file(approved_path).to_crs("EPSG:8857")
+
+        if len(df_approved) != len(df_received):
+            return False
+
+        area_clipped = df_received.clip(df_approved).area
+        area_diff = df_approved.area - area_clipped
+        area_ratio = area_diff / df_approved.area
+        for r in area_ratio:
+            if r > 0.01:
+                return False
+        return True

tests/integration/test_approval.py

@@ -0,0 +1,29 @@
+import pytest
+from approvaltests import Options, verify_binary
+
+from tests.comparator import GeoJSONComparator
+from tests.namer import PytestNamer
+from tests.reporter import SketchMapToolReporter
+
+
+@pytest.mark.use_fixtures("vector")
+@pytest.fixture(scope="session")
+def vector_path(tmp_path_factory, uuid_digitize) -> bytes:
+    return tmp_path_factory.getbasetemp() / uuid_digitize / "vector.geojson"
+
+
+@pytest.mark.use_fixtures("sketch_map_marked")
+@pytest.fixture(scope="session")
+def sketch_map_marked_path(tmp_path_factory, uuid_create) -> bytes:
+    return tmp_path_factory.getbasetemp() / uuid_create / "sketch-map-marked.png"
+
+
+def test_smt_approver(sketch_map_marked_path, vector_path):
+    options = (
+        Options()
+        .with_reporter(SketchMapToolReporter(sketch_map=sketch_map_marked_path))
+        .with_comparator(GeoJSONComparator())
+        .with_namer(PytestNamer())
+    )
+    with open(vector_path, "rb") as f:
+        verify_binary(f.read(), ".geojson", options=options)

tests/namer.py

@@ -0,0 +1,40 @@
+import os
+
+from approvaltests import Namer
+
+from tests import FIXTURE_DIR
+
+APPROVED_DIR = FIXTURE_DIR / "approved"
+
+
+class PytestNamer(Namer):
+    def __init__(self):
+        """An approval tests Namer for naming approved and received text files.
+
+        The Namer includes fixture dir, module, class and function in name.
+
+        This class utilizes the `PYTEST_CURRENT_TEST` environment variable, which
+        consist of the nodeid and the current stage:
+        `relative/path/to/test_file.py::TestClass::test_func[a] (call)`
+
+        For better readability this class formats the filename to something like:
+        `test_file-TestClass-test_func-a
+        """
+        # TODO: name clashes are possible.
+        # Include dir names (except tests/integration/) to avoid name clashes
+        nodeid = os.environ["PYTEST_CURRENT_TEST"]
+        nodeid_without_dir = nodeid.split("/")[-1]
+        parts = nodeid_without_dir.split("::")
+        raw = "-".join(parts)
+        self.name = (
+            raw.replace(".py", "")
+            .replace("[", "-")
+            .replace("]", "")
+            .replace(" (call)", "")
+        )
+
+    def get_received_filename(self) -> str:
+        return str(APPROVED_DIR / str(self.name + ".received" + ".txt"))
+
+    def get_approved_filename(self) -> str:
+        return str(APPROVED_DIR / str(self.name + ".approved" + ".txt"))

tests/reporter.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+
+import geopandas
+import matplotlib.patches as mpatches
+import numpy as np
+from approvaltests import Reporter
+from matplotlib import pyplot as plt
+from matplotlib.widgets import Button
+from PIL import Image
+
+
+class Approver:
+    def __init__(self, approved_path: Path, received_path: Path, sketch_map: Path):
+        self.approved_path: Path = approved_path  # geojson
+        self.received_path: Path = received_path  # geojson
+        self.sketch_map: Path = sketch_map  # jpg
+
+    def plot_difference(self, ax):
+        """Plot difference between approved and received GeoJSON features."""
+        if self.approved_path.exists() and self.approved_path.stat().st_size != 0:
+            df_approved = geopandas.read_file(self.approved_path)
+            df_approved.plot(ax=ax, facecolor="none", edgecolor="blue")
+        df_received = geopandas.read_file(self.received_path)
+        df_received.plot(ax=ax, facecolor="none", edgecolor="red")
+
+    def plot_sketch_map(self, ax):
+        """Plot sketch map image."""
+        image = np.asarray(Image.open(self.sketch_map))
+        ax.imshow(image)
+
+    def approve(self, *_):
+        self.received_path.replace(self.approved_path)
+        plt.close()
+
+    def open(self):
+        """Open dialog for visual comparison."""
+        fig, axs = plt.subplots(1, 2)
+        fig.subplots_adjust(bottom=0.2)
+        self.plot_sketch_map(axs[0])
+        self.plot_difference(axs[1])
+
+        blue_patch = mpatches.Patch(color="blue", label="Approved")
+        red_patch = mpatches.Patch(color="red", label="Received")
+        axs[1].legend(handles=[blue_patch, red_patch])
+
+        ax_approve = fig.add_axes((0.45, 0.05, 0.1, 0.075))
+        button = Button(ax_approve, "Approve")
+        button.on_clicked(self.approve)
+        plt.show()
+
+
+class SketchMapToolReporter(Reporter):
+    def __init__(self, sketch_map: Path):
+        self.sketch_map: Path = sketch_map
+
+    def report(self, received_path, approved_path):
+        Approver(Path(approved_path), Path(received_path), self.sketch_map).open()
+        return True