Deprecate PymatgenTest, migrate pymatgen tests to pytest from unittest

src/pymatgen/util/testing/__init__.py

@@ -35,8 +35,15 @@
 FAKE_POTCAR_DIR = f"{VASP_IN_DIR}/fake_potcars"
 
 
-class PymatgenTest(TestCase):
-    """Extends unittest.TestCase with several assert methods for array and str comparison."""
+class MatSciTest:
+    """TODO: name might need discussion.
+
+    TODO: finish docstring
+
+    TODO: reduce code duplicate
+
+    TODO: add deprecation warning
+    """
 
     # dict of lazily-loaded test structures (initialized to None)
     TEST_STRUCTURES: ClassVar[dict[str | Path, Structure | None]] = dict.fromkeys(STRUCTURES_DIR.glob("*"))
@@ -149,3 +156,119 @@ def assert_msonable(self, obj: MSONable, test_is_subclass: bool = True) -> str:
         if not issubclass(type(round_trip), type(obj)):
             raise TypeError(f"{type(round_trip)} != {type(obj)}")
         return json_str
+
+
+class PymatgenTest(TestCase):
+    """Extends unittest.TestCase with several assert methods for array and str comparison.
+
+    Deprecated: please use `MatSciTest` instead (migrate from `unittest` to `pytest`).
+    """
+
+    # dict of lazily-loaded test structures (initialized to None)
+    TEST_STRUCTURES: ClassVar[dict[str | Path, Structure | None]] = dict.fromkeys(STRUCTURES_DIR.glob("*"))
+
+    @pytest.fixture(autouse=True)  # make all tests run a in a temporary directory accessible via self.tmp_path
+    def _tmp_dir(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        # https://pytest.org/en/latest/how-to/unittest.html#using-autouse-fixtures-and-accessing-other-fixtures
+        monkeypatch.chdir(tmp_path)  # change to pytest-provided temporary directory
+        self.tmp_path = tmp_path
+
+    @classmethod
+    def get_structure(cls, name: str) -> Structure:
+        """
+        Lazily load a structure from pymatgen/util/structures.
+
+        Args:
+            name (str): Name of structure file.
+
+        Returns:
+            Structure
+        """
+        return MatSciTest.get_structure(name)
+
+    @staticmethod
+    def assert_str_content_equal(actual, expected):
+        """Test if two strings are equal, ignoring things like trailing spaces, etc."""
+        MatSciTest.assert_str_content_equal(actual, expected)
+
+    def serialize_with_pickle(self, objects: Any, protocols: Sequence[int] | None = None, test_eq: bool = True):
+        """Test whether the object(s) can be serialized and deserialized with
+        pickle. This method tries to serialize the objects with pickle and the
+        protocols specified in input. Then it deserializes the pickle format
+        and compares the two objects with the __eq__ operator if
+        test_eq is True.
+
+        Args:
+            objects: Object or list of objects.
+            protocols: List of pickle protocols to test. If protocols is None,
+                HIGHEST_PROTOCOL is tested.
+            test_eq: If True, the deserialized object is compared with the
+                original object using the __eq__ method.
+
+        Returns:
+            Nested list with the objects deserialized with the specified
+            protocols.
+        """
+        # Build a list even when we receive a single object.
+        got_single_object = False
+        if not isinstance(objects, list | tuple):
+            got_single_object = True
+            objects = [objects]
+
+        protocols = protocols or [pickle.HIGHEST_PROTOCOL]
+
+        # This list will contain the objects deserialized with the different protocols.
+        objects_by_protocol, errors = [], []
+
+        for protocol in protocols:
+            # Serialize and deserialize the object.
+            tmpfile = self.tmp_path / f"tempfile_{protocol}.pkl"
+
+            try:
+                with open(tmpfile, "wb") as file:
+                    pickle.dump(objects, file, protocol=protocol)
+            except Exception as exc:
+                errors.append(f"pickle.dump with {protocol=} raised:\n{exc}")
+                continue
+
+            try:
+                with open(tmpfile, "rb") as file:
+                    unpickled_objs = pickle.load(file)  # noqa: S301
+            except Exception as exc:
+                errors.append(f"pickle.load with {protocol=} raised:\n{exc}")
+                continue
+
+            # Test for equality
+            if test_eq:
+                for orig, unpickled in zip(objects, unpickled_objs, strict=True):
+                    if orig != unpickled:
+                        raise ValueError(
+                            f"Unpickled and original objects are unequal for {protocol=}\n{orig=}\n{unpickled=}"
+                        )
+
+            # Save the deserialized objects and test for equality.
+            objects_by_protocol.append(unpickled_objs)
+
+        if errors:
+            raise ValueError("\n".join(errors))
+
+        # Return nested list so that client code can perform additional tests.
+        if got_single_object:
+            return [o[0] for o in objects_by_protocol]
+        return objects_by_protocol
+
+    def assert_msonable(self, obj: MSONable, test_is_subclass: bool = True) -> str:
+        """Test if obj is MSONable and verify the contract is fulfilled.
+
+        By default, the method tests whether obj is an instance of MSONable.
+        This check can be deactivated by setting test_is_subclass=False.
+        """
+        if test_is_subclass and not isinstance(obj, MSONable):
+            raise TypeError("obj is not MSONable")
+        if obj.as_dict() != type(obj).from_dict(obj.as_dict()).as_dict():
+            raise ValueError("obj could not be reconstructed accurately from its dict representation.")
+        json_str = json.dumps(obj.as_dict(), cls=MontyEncoder)
+        round_trip = json.loads(json_str, cls=MontyDecoder)
+        if not issubclass(type(round_trip), type(obj)):
+            raise TypeError(f"{type(round_trip)} != {type(obj)}")
+        return json_str

tests/alchemy/test_filters.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import json
-from unittest import TestCase
 
 from monty.json import MontyDecoder
 
@@ -14,10 +13,10 @@
 from pymatgen.alchemy.transmuters import StandardTransmuter
 from pymatgen.analysis.structure_matcher import StructureMatcher
 from pymatgen.core import Lattice, Species, Structure
-from pymatgen.util.testing import TEST_FILES_DIR, PymatgenTest
+from pymatgen.util.testing import TEST_FILES_DIR, MatSciTest
 
 
-class TestContainsSpecieFilter(PymatgenTest):
+class TestContainsSpecieFilter(MatSciTest):
     def test_filtering(self):
         coords = [[0, 0, 0], [0.75, 0.75, 0.75], [0.5, 0.5, 0.5], [0.25, 0.25, 0.25]]
         lattice = Lattice([[3.0, 0.0, 0.0], [1.0, 3.0, 0], [0, -2.0, 3.0]])
@@ -52,7 +51,7 @@ def test_as_from_dict(self):
         assert isinstance(ContainsSpecieFilter.from_dict(dct), ContainsSpecieFilter)
 
 
-class TestSpecieProximityFilter(PymatgenTest):
+class TestSpecieProximityFilter(MatSciTest):
     def test_filter(self):
         struct = self.get_structure("Li10GeP2S12")
         sf = SpecieProximityFilter({"Li": 1})
@@ -70,8 +69,8 @@ def test_as_from_dict(self):
         assert isinstance(SpecieProximityFilter.from_dict(dct), SpecieProximityFilter)
 
 
-class TestRemoveDuplicatesFilter(TestCase):
-    def setUp(self):
+class TestRemoveDuplicatesFilter:
+    def setup_method(self):
         with open(f"{TEST_FILES_DIR}/entries/TiO2_entries.json") as file:
             entries = json.load(file, cls=MontyDecoder)
         self._struct_list = [entry.structure for entry in entries]
@@ -89,8 +88,8 @@ def test_as_from_dict(self):
         assert isinstance(RemoveDuplicatesFilter().from_dict(dct), RemoveDuplicatesFilter)
 
 
-class TestRemoveExistingFilter(TestCase):
-    def setUp(self):
+class TestRemoveExistingFilter:
+    def setup_method(self):
         with open(f"{TEST_FILES_DIR}/entries/TiO2_entries.json") as file:
             entries = json.load(file, cls=MontyDecoder)
         self._struct_list = [entry.structure for entry in entries]

tests/alchemy/test_materials.py

@@ -16,14 +16,14 @@
     SupercellTransformation,
 )
 from pymatgen.util.provenance import StructureNL
-from pymatgen.util.testing import FAKE_POTCAR_DIR, TEST_FILES_DIR, PymatgenTest
+from pymatgen.util.testing import FAKE_POTCAR_DIR, TEST_FILES_DIR, MatSciTest
 
 TEST_DIR = f"{TEST_FILES_DIR}/alchemy"
 
 
-class TestTransformedStructure(PymatgenTest):
-    def setUp(self):
-        structure = PymatgenTest.get_structure("LiFePO4")
+class TestTransformedStructure(MatSciTest):
+    def setup_method(self):
+        structure = MatSciTest.get_structure("LiFePO4")
         self.structure = structure
         trafos = [SubstitutionTransformation({"Li": "Na"})]
         self.trans = TransformedStructure(structure, trafos)

tests/alchemy/test_transmuters.py

@@ -8,10 +8,10 @@
     RemoveSpeciesTransformation,
     SubstitutionTransformation,
 )
-from pymatgen.util.testing import TEST_FILES_DIR, VASP_IN_DIR, PymatgenTest
+from pymatgen.util.testing import TEST_FILES_DIR, VASP_IN_DIR, MatSciTest
 
 
-class TestCifTransmuter(PymatgenTest):
+class TestCifTransmuter(MatSciTest):
     def test_init(self):
         trafos = [SubstitutionTransformation({"Fe": "Mn", "Fe2+": "Mn2+"})]
         tsc = CifTransmuter.from_filenames([f"{TEST_FILES_DIR}/cif/MultiStructure.cif"], trafos)
@@ -22,7 +22,7 @@ def test_init(self):
             assert expected == els
 
 
-class TestPoscarTransmuter(PymatgenTest):
+class TestPoscarTransmuter(MatSciTest):
     def test_init(self):
         trafos = [SubstitutionTransformation({"Fe": "Mn"})]
         tsc = PoscarTransmuter.from_filenames([f"{VASP_IN_DIR}/POSCAR", f"{VASP_IN_DIR}/POSCAR"], trafos)

tests/analysis/chemenv/connectivity/test_connected_components.py

@@ -20,12 +20,12 @@
 from pymatgen.core.lattice import Lattice
 from pymatgen.core.sites import PeriodicSite
 from pymatgen.core.structure import Structure
-from pymatgen.util.testing import TEST_FILES_DIR, PymatgenTest
+from pymatgen.util.testing import TEST_FILES_DIR, MatSciTest
 
 __author__ = "waroquiers"
 
 
-class TestConnectedComponent(PymatgenTest):
+class TestConnectedComponent(MatSciTest):
     def test_init(self):
         # Generic connected component not using EnvironmentNodes
         # (as_dict won't work on such a ConnectedComponent instance)

tests/analysis/chemenv/connectivity/test_environment_nodes.py

@@ -3,7 +3,7 @@
 import json
 
 from pymatgen.analysis.chemenv.connectivity.environment_nodes import EnvironmentNode
-from pymatgen.util.testing import PymatgenTest
+from pymatgen.util.testing import MatSciTest
 
 try:
     import bson
@@ -13,7 +13,7 @@
 __author__ = "waroquiers"
 
 
-class TestEnvironmentNodes(PymatgenTest):
+class TestEnvironmentNodes(MatSciTest):
     def test_equal(self):
         struct = self.get_structure("SiO2")
         en = EnvironmentNode(central_site=struct[0], i_central_site=0, ce_symbol="T:4")

tests/analysis/chemenv/connectivity/test_structure_connectivity.py

@@ -9,12 +9,12 @@
     LightStructureEnvironments,
     StructureEnvironments,
 )
-from pymatgen.util.testing import TEST_FILES_DIR, PymatgenTest
+from pymatgen.util.testing import TEST_FILES_DIR, MatSciTest
 
 __author__ = "waroquiers"
 
 
-class TestStructureConnectivity(PymatgenTest):
+class TestStructureConnectivity(MatSciTest):
     def test_serialization(self):
         BaTiO3_se_fpath = f"{TEST_FILES_DIR}/analysis/chemenv/structure_environments/se_mp-5020.json"
         with open(BaTiO3_se_fpath) as file: