Source code for pyretis.testing.helpers

# Copyright (c) 2026, PyRETIS Development Team.
# Distributed under the LGPLv2.1+ License. See LICENSE for more info.
"""Methods that might be useful for testing.

This module defines generic methods for testing.

"""
import os
import sys


#: Environment variable that turns the numerical reference comparison on
#: (``"1"``, the default) or off (``"0"``). It is set to ``"0"`` by the
#: engine test runners when only a non-reference-grade external MD engine
#: is available (for example a single-precision GROMACS build when the
#: reference data was generated in double precision). External MD engines
#: are not bit-for-bit reproducible across build, precision and hardware,
#: so a reference comparison is only meaningful against the exact
#: reference-grade engine.
VALIDATE_ENV = 'PYRETIS_VALIDATE'


def reference_validation_enabled():
    """Return whether numerical reference comparison should be performed.

    Returns
    -------
    out : boolean
        ``True`` unless the ``PYRETIS_VALIDATE`` environment variable is
        set to ``"0"``. The default (variable unset) is ``True`` so that
        the validated path is unchanged when a reference-grade engine is
        present.

    """
    return os.environ.get(VALIDATE_ENV, '1') != '0'


def skip_reference_validation(reason):
    """Report that the run was executed but not numerically validated.

    This prints a clearly labelled ``NOT VALIDATED`` message and exits
    with status ``0``. It is used by the engine test scripts as the
    "execution smoke" outcome: the simulation ran without error, but the
    numerical comparison against the committed reference was skipped
    because no reference-grade engine was available. Following the
    project rule "better a fail than a wrong pass", a skipped comparison
    is never reported as a pass.

    Parameters
    ----------
    reason : string
        Why the numerical comparison was skipped (for example
        ``"single-precision GROMACS; reference is double precision"``).

    """
    print('=' * 70)
    print('NOT VALIDATED: %s' % reason)
    print('The simulation ran (execution smoke check passed) but the '
          'numerical comparison against the committed reference was '
          'skipped.')
    print('=' * 70)
    sys.exit(0)


def search_for_files(rootdir, match=None):
    """Find files by walking the given directory.

    Parameters
    ----------
    rootdir : string
        The path where we will search from.
    match : string, optional
        If given, the method will only return files that
        are equal to the given match.

    Return
    ------
    out : list of strings
        The paths of the found files.

    """
    files = []
    for root, _, filei in os.walk(rootdir):
        for i in filei:
            if match is None:
                files.append(os.path.join(root, i))
            elif i == match:
                files.append(os.path.join(root, i))
    return files


def clean_dir(dirname):
    """Remove ALL files in the given directory."""
    for files in os.listdir(dirname):
        filename = os.path.join(dirname, files)
        if os.path.isfile(filename):
            os.remove(filename)