src/gromacs/trajectoryanalysis/tests/moduletest.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013,2014,2018,2019, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \internal \file
  36  * \brief
  37  * Declares test fixture for TrajectoryAnalysisModule subclasses.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \ingroup module_trajectoryanalysis
  41  */
  42 #ifndef GMX_TRAJECTORYANALYSIS_TESTS_MODULETEST_H
  43 #define GMX_TRAJECTORYANALYSIS_TESTS_MODULETEST_H
  44
  45 #include <gtest/gtest.h>
  46
  47 #include "gromacs/trajectoryanalysis/analysismodule.h"
  48 #include "gromacs/utility/classhelpers.h"
  49
  50 #include "testutils/cmdlinetest.h"
  51
  52 namespace gmx
  53 {
  54
  55 class TrajectoryAnalysisModule;
  56
  57 namespace test
  58 {
  59
  60 class FloatingPointTolerance;
  61
  62 /*! \internal
  63  * \brief
  64  * Test fixture for trajectory analysis modules.
  65  *
  66  * This class implements common logic for all tests for trajectory analysis
  67  * modules.  The tests simply need to specify the type of the module to test,
  68  * input files and any additional options, names of datasets to test (if not
  69  * all), and possible output files to explicitly test by calling the different
  70  * methods in this class.  runTest() then runs the specified module with the
  71  * given options and performs all the requested tests against reference data.
  72  *
  73  * Tests should prefer to test the underlying data sets instead of string
  74  * comparison on the output files using setOutputFile().
  75  *
  76  * The actual module to be tested is constructed in the pure virtual
  77  * createModule() method, which should be implemented in a subclass.
  78  * Typically, the TrajectoryAnalysisModuleTestFixture template can be used.
  79  *
  80  * Any method in this class may throw std::bad_alloc if out of memory.
  81  *
  82  * \todo
  83  * Adding facilities to AnalysisData to check whether there are any
  84  * output modules attached to the data object (directly or indirectly),
  85  * marking the mocks as output modules, and using these checks in the
  86  * tools instead of or in addition to the output file presence would be
  87  * a superior.
  88  * Also, the full file names should be deducible from the options.
  89  *
  90  * \ingroup module_trajectoryanalysis
  91  */
  92 class AbstractTrajectoryAnalysisModuleTestFixture : public CommandLineTestBase
  93 {
  94 public:
  95     AbstractTrajectoryAnalysisModuleTestFixture();
  96     ~AbstractTrajectoryAnalysisModuleTestFixture() override;
  97
  98     /*! \brief
  99      * Sets the topology file to use for the test.
 100      *
 101      * \param[in] filename  Name of input topology file.
 102      *
 103      * \p filename is interpreted relative to the test input data
 104      * directory, see getTestDataPath().
 105      *
 106      * Must be called at most once.  Either this method or setTrajectory()
 107      * must be called before runTest().
 108      */
 109     void setTopology(const char* filename);
 110     /*! \brief
 111      * Sets the trajectory file to use for the test.
 112      *
 113      * \param[in] filename  Name of input trajectory file.
 114      *
 115      * \p filename is interpreted relative to the test input data
 116      * directory, see getTestDataPath().
 117      *
 118      * Must be called at most once.  Either this method or setTopology()
 119      * must be called before runTest().
 120      */
 121     void setTrajectory(const char* filename);
 122     /*! \brief
 123      * Includes only specified dataset for the test.
 124      *
 125      * \param[in] name  Name of dataset to include.
 126      *
 127      * If this method is not called, all datasets are tested by default.
 128      * If called once, only the specified dataset is tested.
 129      * If called more than once, also the additional datasets are tested.
 130      *
 131      * \p name should be one of the names registered for the tested module
 132      * using TrajectoryAnalysisModule::registerBasicDataset() or
 133      * TrajectoryAnalysisModule::registerAnalysisDataset().
 134      */
 135     void includeDataset(const char* name);
 136     /*! \brief
 137      * Excludes specified dataset from the test.
 138      *
 139      * \param[in] name  Name of dataset to exclude.
 140      *
 141      * \p name should be one of the names registered for the tested module
 142      * using TrajectoryAnalysisModule::registerBasicDataset() or
 143      * TrajectoryAnalysisModule::registerAnalysisDataset().
 144      */
 145     void excludeDataset(const char* name);
 146     /*! \brief
 147      * Sets a custom tolerance for checking a dataset.
 148      *
 149      * \param[in] name       Name of dataset to set the tolerance for.
 150      * \param[in] tolerance  Tolerance used when verifying the data.
 151      *
 152      * \p name should be one of the names registered for the tested module
 153      * using TrajectoryAnalysisModule::registerBasicDataset() or
 154      * TrajectoryAnalysisModule::registerAnalysisDataset().
 155      */
 156     void setDatasetTolerance(const char* name, const FloatingPointTolerance& tolerance);
 157
 158     /*! \brief
 159      * Runs the analysis module with the given additional options.
 160      *
 161      * \param[in] args  Options to provide to the module.
 162      *
 163      * \p args should be formatted as command-line options, and contain the
 164      * name of the module as the first argument (the latter requirement is
 165      * for clarity only).  They are passed to the module in addition to
 166      * those specified using other methods in this class.
 167      *
 168      * All other methods should be called before calling this method.
 169      *
 170      * Exceptions thrown by the module are caught by this method.
 171      */
 172     void runTest(const CommandLine& args);
 173
 174 protected:
 175     /*! \brief
 176      * Constructs the analysis module to be tested.
 177      */
 178     virtual TrajectoryAnalysisModulePointer createModule() = 0;
 179
 180 private:
 181     class Impl;
 182
 183     PrivateImplPointer<Impl> impl_;
 184 };
 185
 186 /*! \internal \brief
 187  * Test fixture for a trajectory analysis module.
 188  *
 189  * \tparam ModuleInfo  Info object for the analysis module to test.
 190  *
 191  * \p ModuleInfo should provide a static
 192  * `TrajectoryAnalysisModulePointer create()` method.
 193  *
 194  * \ingroup module_trajectoryanalysis
 195  */
 196 template<class ModuleInfo>
 197 class TrajectoryAnalysisModuleTestFixture : public AbstractTrajectoryAnalysisModuleTestFixture
 198 {
 199 protected:
 200     TrajectoryAnalysisModulePointer createModule() override { return ModuleInfo::create(); }
 201 };
 202
 203 } // namespace test
 204 } // namespace gmx
 205
 206 #endif