Deprecate PymatgenTest, migrate tests to pytest from unittest (#4212)

* revert for a separate migration PR

* Revert "revert for a separate migration PR"

This reverts commit 6f95ba8.

* remove hard-coded and failing test

* batch remove PymatgenTest inheritance and see what fail

* migrate alchemy and command_line

* deprecate pymatgen with matscitest

* migrate utils

* migrate optimization

* migrate vis

* global replacement of setUp and TearDown, setupClass

* revert all changes to before global replace PymatgenTest

* deprecate pymatgen with matscitest

* global replace setUp with setup_method

* replace tearDown

* replace  setUpClass(cls) with setup_class(cls)

* global remove inheritance from TestCase

* global replace inheritance from PymatgenTest

* global replace PymatgenTest import

* global replace get_structure

* global replace PymatgenTest with MatSciTest

* fix tests

* fix internal index and add require for pytest style

* fix test

* remove seemingly unused conftest

* add deprecated decorator and enhance docstring

* inherit to reduce code duplicate

* add some test for legacy tester

* also check future warning

* remove unnecessary chdir

* prep for merge

* fix bad merge behaviour

* pre-commit auto-fixes

* fix merge

* migrate recently added tests

---------

Signed-off-by: Haoyu (Daniel) YANG <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: DanielYang59

docs/contributing.md

@@ -1,8 +1,7 @@
 """This module implements testing utilities for materials science codes.
 
-While the primary use is within pymatgen, the functionality is meant to
-be useful for external materials science codes as well. For instance, obtaining
-example crystal structures to perform tests, specialized assert methods for
+While the primary use is within pymatgen, the functionality is meant to be useful for external materials science
+codes as well. For instance, obtaining example crystal structures to perform tests, specialized assert methods for
 materials science, etc.
 """
 
@@ -16,6 +15,7 @@
 from unittest import TestCase
 
 import pytest
+from monty.dev import deprecated
 from monty.json import MontyDecoder, MontyEncoder, MSONable
 from monty.serialization import loadfn
 
@@ -42,12 +42,14 @@
 FAKE_POTCAR_DIR: str = f"{VASP_IN_DIR}/fake_potcars"
 
 
-class PymatgenTest(TestCase):
-    """Extends unittest.TestCase with several convenient methods for testing:
-    - assert_msonable: Test if an object is MSONable and return the serialized object.
-    - assert_str_content_equal: Test if two string are equal (ignore whitespaces).
-    - get_structure: Load a Structure with its formula.
-    - serialize_with_pickle: Test if object(s) can be (de)serialized with `pickle`.
+class MatSciTest:
+    """`pytest` based test framework extended to facilitate testing with
+    the following methods:
+    - tmp_path (attribute): Temporary directory.
+    - get_structure: Load a Structure from `util.structures` with its name.
+    - assert_str_content_equal: Check if two strings are equal (ignore whitespaces).
+    - serialize_with_pickle: Test whether object(s) can be (de)serialized with pickle.
+    - assert_msonable: Test if obj is MSONable and return its serialized string.
     """
 
     # dict of lazily-loaded test structures (initialized to None)
@@ -201,7 +203,15 @@ def serialize_with_pickle(
         if errors:
             raise ValueError("\n".join(errors))
 
-        # Return list so that client code can perform additional tests
+        # 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
+
+
+@deprecated(MatSciTest, deadline=(2026, 1, 1))
+class PymatgenTest(TestCase, MatSciTest):
+    """Extends unittest.TestCase with several assert methods for array and str comparison.
+
+    Deprecated: please use `MatSciTest` instead (migrate from `unittest` to `pytest`).
+    """

src/pymatgen/util/testing.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", encoding="utf-8") 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", encoding="utf-8") as file:
             entries = json.load(file, cls=MontyDecoder)
         self._struct_list = [entry.structure for entry in entries]

tests/alchemy/test_filters.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_materials.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/alchemy/test_transmuters.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_connected_components.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_environment_nodes.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, encoding="utf-8") as file:

tests/analysis/chemenv/connectivity/test_structure_connectivity.py

@@ -10,12 +10,12 @@
     DistanceCutoffFloat,
     SimplestChemenvStrategy,
 )
-from pymatgen.util.testing import PymatgenTest
+from pymatgen.util.testing import MatSciTest
 
 __author__ = "waroquiers"
 
 
-class TestStrategyOptions(PymatgenTest):
+class TestStrategyOptions(MatSciTest):
     def test_options(self):
         # DistanceCutoffFloat
         with pytest.raises(ValueError, match=r"Distance cutoff should be between 1 and \+infinity"):

tests/analysis/chemenv/coordination_environments/test_chemenv_strategies.py

@@ -11,7 +11,7 @@
     ExplicitPermutationsAlgorithm,
     SeparationPlane,
 )
-from pymatgen.util.testing import PymatgenTest
+from pymatgen.util.testing import MatSciTest
 
 __author__ = "waroquiers"
 
@@ -23,7 +23,7 @@ def __init__(self, coords):
         self.coords = coords
 
 
-class TestCoordinationGeometries(PymatgenTest):
+class TestCoordinationGeometries(MatSciTest):
     def test_algorithms(self):
         expl_algo = ExplicitPermutationsAlgorithm(permutations=[[0, 1, 2], [1, 2, 3]])
         expl_algo2 = ExplicitPermutationsAlgorithm.from_dict(expl_algo.as_dict())

tests/analysis/chemenv/coordination_environments/test_coordination_geometries.py

@@ -19,15 +19,15 @@
     symmetry_measure,
 )
 from pymatgen.core.structure import Lattice, Structure
-from pymatgen.util.testing import TEST_FILES_DIR, PymatgenTest
+from pymatgen.util.testing import TEST_FILES_DIR, MatSciTest
 
 __author__ = "waroquiers"
 
 json_dir = f"{TEST_FILES_DIR}/analysis/chemenv/json"
 
 
-class TestCoordinationGeometryFinder(PymatgenTest):
-    def setUp(self):
+class TestCoordinationGeometryFinder(MatSciTest):
+    def setup_method(self):
         self.lgf = LocalGeometryFinder()
         self.lgf.setup_parameters(
             centering_type="standard",

tests/analysis/chemenv/coordination_environments/test_coordination_geometry_finder.py

@@ -22,17 +22,17 @@
 )
 from pymatgen.analysis.chemenv.coordination_environments.voronoi import DetailedVoronoiContainer
 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"
 
 json_dir = f"{TEST_FILES_DIR}/analysis/chemenv/json"
 struct_env_dir = f"{TEST_FILES_DIR}/analysis/chemenv/structure_environments"
 
 
-class TestReadWriteChemenv(PymatgenTest):
+class TestReadWriteChemenv(MatSciTest):
     @classmethod
-    def setUpClass(cls):
+    def setup_class(cls):
         cls.lgf = LocalGeometryFinder()
         cls.lgf.setup_parameters(centering_type="standard")
 

tests/analysis/chemenv/coordination_environments/test_read_write.py

@@ -17,14 +17,14 @@
     StructureEnvironments,
 )
 from pymatgen.core import Species, Structure
-from pymatgen.util.testing import TEST_FILES_DIR, PymatgenTest
+from pymatgen.util.testing import TEST_FILES_DIR, MatSciTest
 
 __author__ = "waroquiers"
 
 TEST_DIR = f"{TEST_FILES_DIR}/analysis/chemenv/structure_environments"
 
 
-class TestStructureEnvironments(PymatgenTest):
+class TestStructureEnvironments(MatSciTest):
     def test_structure_environments(self):
         with open(f"{TEST_DIR}/se_mp-7000.json", encoding="utf-8") as file:
             dct = json.load(file)