# pymatgen.util.testing package

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 materials science, etc.

class PymatgenTest(methodName='runTest')

  Bases: `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.

  Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

  TEST_STRUCTURES: ClassVar[dict[PathLike, Structure | None]] = {PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/BaNiO3.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/CsCl.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/Graphite.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/He_BCC.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/K2O2.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/La2CoO4F.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/Li10GeP2S12.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/Li2O.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/Li2O2.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/Li3V2(PO4)3.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/LiFePO4.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/NaFePO4.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/Pb2TiZrO6.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/Si.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/SiO2.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/Si_SiO2_Interface.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/Sn.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/SrTiO3.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/TiO2.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/TlBiSe2.json'): None, PosixPath('/build/pymatgen-g6au1f/pymatgen-2025.2.18+dfsg1/.pybuild/cpython3_3.13_pymatgen/build/pymatgen/util/structures/VO2.json'): None}
  static assert_msonable(obj: Any, test_is_subclass: bool = True) → str

    Test if an object is MSONable and verify the contract is fulfilled, and return the serialized object.

    By default, the method tests whether obj is an instance of MSONable. This check can be deactivated by setting test_is_subclass to False.

    Parameters:

      - obj (Any) – The object to be checked.

      - test_is_subclass (bool) – Check if object is an instance of MSONable or its subclasses.

    Returns:

      Serialized object.

    Return type:

      str

  static assert_str_content_equal(actual: str, expected: str) → None

    Test if two strings are equal, ignoring whitespaces.

    Parameters:

      - actual (str) – The string to be checked.

      - expected (str) – The reference string.

    Raises:

      AssertionError – When two strings are not equal.

  classmethod get_structure(name: str) → Structure

    Load a structure from pymatgen.util.structures.

    Parameters:

      name (str) – Name of the structure file, for example “LiFePO4”.

    Returns:

      Structure

  serialize_with_pickle(objects: Any, protocols: Sequence[int] | None = None, test_eq: bool = True) → list

    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 pickled format and compares the two objects with the == operator if test_eq.

    Parameters:

      - objects (Any) – Object or list of objects.

      - protocols (Sequence[int]) – List of pickle protocols to test. If protocols is None, HIGHEST_PROTOCOL is tested.

      - test_eq (bool) – If True, the deserialized object is compared with the original object using the __eq__ method.

    Returns:

      Objects deserialized with the specified protocols.

    Return type:

      list[Any]