Add test for deprecator function

tests/test_misc.py

@@ -1,9 +1,14 @@
 from __future__ import annotations
 
 import os
+import warnings
 
+import pytest
 import yaml  # type: ignore
 
+import geoutils
+import geoutils.misc
+
 
 class TestMisc:
     def test_environment_files(self) -> None:
@@ -36,3 +41,60 @@ def test_environment_files(self) -> None:
         # We do the same for the conda dependency, first a sanity check that everything that is in env is also in dev-ev
         diff_conda_check = list(set(conda_dep_env) - set(conda_dep_devenv))
         assert len(diff_conda_check) == 0
+
+    @pytest.mark.parametrize("deprecation_increment", [-1, 0, 1, None])  # type: ignore
+    @pytest.mark.parametrize("details", [None, "It was completely useless!", "dunnowhy"])  # type: ignore
+    def test_deprecate(self, deprecation_increment: int | None, details: str | None) -> None:
+        """
+        Test the deprecation warnings/errors.
+
+        If the removal_version is larger than the current, it should warn.
+        If the removal_version is smaller or equal, it should raise an error.
+
+        :param deprecation_increment: The version number relative to the current version.
+        :param details: An optional explanation for the description.
+        """
+        warnings.simplefilter("error")
+
+        current_version = geoutils.version.version
+
+        # Set the removal version to be the current version plus the increment (e.g. 0.0.5 + 1 -> 0.0.6)
+        removal_version = (
+            current_version[:-1] + str(int(current_version.rsplit(".", 1)[1]) + deprecation_increment)
+            if deprecation_increment is not None
+            else None
+        )
+
+        # Define a function with no use that is marked as deprecated.
+        @geoutils.misc.deprecate(removal_version, details=details)  # type: ignore
+        def useless_func() -> int:
+            return 1
+
+        # If True, a warning is expected. If False, a ValueError is expected.
+        should_warn = removal_version is None or removal_version > current_version
+
+        # Add the expected text depending on the parametrization.
+        text = (
+            "Call to deprecated function 'useless_func'."
+            if should_warn
+            else f"Deprecated function 'useless_func' was removed in {removal_version}."
+        )
+
+        if details is not None:
+            text += " " + details.strip().capitalize()
+
+            if not any(text.endswith(c) for c in ".!?"):
+                text += "."
+
+        if should_warn and removal_version is not None:
+            text += f" This functionality will be removed in version {removal_version}."
+        elif not should_warn:
+            text += f" Current version: {current_version}."
+
+        # Expect either a warning or an exception with the right text.
+        if should_warn:
+            with pytest.warns(DeprecationWarning, match="^" + text + "$"):
+                useless_func()
+        else:
+            with pytest.raises(ValueError, match="^" + text + "$"):
+                useless_func()