src/gromacs/trajectoryanalysis/tests/moduletest.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013, 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/common.h"
  49
  50 namespace gmx
  51 {
  52
  53 class TrajectoryAnalysisModule;
  54
  55 namespace test
  56 {
  57
  58 class CommandLine;
  59
  60 /*! \internal
  61  * \brief
  62  * Test fixture for trajectory analysis modules.
  63  *
  64  * This class implements common logic for all tests for trajectory analysis
  65  * modules.  The tests simply need to specify the type of the module to test,
  66  * input files and any additional options, names of datasets to test (if not
  67  * all), and possible output files to explicitly test by calling the different
  68  * methods in this class.  runTest() then runs the specified module with the
  69  * given options and performs all the requested tests against reference data.
  70  *
  71  * The actual module to be tested is constructed in the pure virtual
  72  * createModule() method, which should be implemented in a subclass.
  73  * Typically, the TrajectoryAnalysisModuleTestFixture template can be used.
  74  *
  75  * Any method in this class may throw std::bad_alloc if out of memory.
  76  *
  77  * \ingroup module_trajectoryanalysis
  78  */
  79 class AbstractTrajectoryAnalysisModuleTestFixture : public ::testing::Test
  80 {
  81     public:
  82         AbstractTrajectoryAnalysisModuleTestFixture();
  83         virtual ~AbstractTrajectoryAnalysisModuleTestFixture();
  84
  85         /*! \brief
  86          * Sets the topology file to use for the test.
  87          *
  88          * \param[in] filename  Name of input topology file.
  89          *
  90          * \p filename is interpreted relative to the test input data
  91          * directory, see getTestDataPath().
  92          *
  93          * Must be called at most once.  Either this method or setTrajectory()
  94          * must be called before runTest().
  95          */
  96         void setTopology(const char *filename);
  97         /*! \brief
  98          * Sets the trajectory file to use for the test.
  99          *
 100          * \param[in] filename  Name of input trajectory file.
 101          *
 102          * \p filename is interpreted relative to the test input data
 103          * directory, see getTestDataPath().
 104          *
 105          * Must be called at most once.  Either this method or setTopology()
 106          * must be called before runTest().
 107          */
 108         void setTrajectory(const char *filename);
 109         /*! \brief
 110          * Sets an output file to use for the test.
 111          *
 112          * \param[in] option    Option to set.
 113          * \param[in] filename  Name of the output file.
 114          *
 115          * This method:
 116          *  - Sets \p option in the tested module to a temporary file name
 117          *    constructed from \p filename.
 118          *  - Makes runTest() to check the contents of the file against
 119          *    reference data after running the module.
 120          *  - Marks the temporary file for removal at test teardown.
 121          *
 122          * \p filename is given to TestTemporaryFileManager to make a unique
 123          * filename for the temporary file, but is not otherwise used.
 124          *
 125          * Currently, this method should not be called for an XVG file, because
 126          * the comments in the beginning of the file contain timestamps and
 127          * other variable information, causing the test to fail.  Best used
 128          * only for custom data formats.  For numeric data, testing the
 129          * underlying dataset is typically sufficient.
 130          */
 131         void setOutputFile(const char *option, const char *filename);
 132         /*! \brief
 133          * Includes only specified dataset for the test.
 134          *
 135          * \param[in] name  Name of dataset to include.
 136          *
 137          * If this method is not called, all datasets are tested by default.
 138          * If called once, only the specified dataset is tested.
 139          * If called more than once, also the additional datasets are tested.
 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 includeDataset(const char *name);
 146         /*! \brief
 147          * Excludes specified dataset from the test.
 148          *
 149          * \param[in] name  Name of dataset to exclude.
 150          *
 151          * If includeDataset() has been called, \p name must be one of the
 152          * included datasets.
 153          *
 154          * \p name should be one of the names registered for the tested module
 155          * using TrajectoryAnalysisModule::registerBasicDataset() or
 156          * TrajectoryAnalysisModule::registerAnalysisDataset().
 157          */
 158         void excludeDataset(const char *name);
 159
 160         /*! \brief
 161          * Runs the analysis module with the given additional options.
 162          *
 163          * \param[in] args  Options to provide to the module.
 164          *
 165          * \p args should be formatted as command-line options, and contain the
 166          * name of the module as the first argument (the latter requirement is
 167          * for clarity only).  They are passed to the module in addition to
 168          * those specified using other methods in this class.
 169          *
 170          * All other methods should be called before calling this method.
 171          *
 172          * Exceptions thrown by the module are caught by this method.
 173          */
 174         void runTest(const CommandLine &args);
 175
 176     protected:
 177         /*! \brief
 178          * Constructs the analysis module to be tested.
 179          */
 180         virtual TrajectoryAnalysisModulePointer createModule() = 0;
 181
 182     private:
 183         class Impl;
 184
 185         PrivateImplPointer<Impl> impl_;
 186 };
 187
 188 /*! \internal \brief
 189  * Test fixture for a trajectory analysis module.
 190  *
 191  * \tparam ModuleInfo  Info object for the analysis module to test.
 192  *
 193  * \p ModuleInfo should provide a static
 194  * `TrajectoryAnalysisModulePointer create()` method.
 195  *
 196  * \ingroup module_trajectoryanalysis
 197  */
 198 template <class ModuleInfo>
 199 class TrajectoryAnalysisModuleTestFixture
 200     : public AbstractTrajectoryAnalysisModuleTestFixture
 201 {
 202     protected:
 203         virtual TrajectoryAnalysisModulePointer createModule()
 204         {
 205             return ModuleInfo::create();
 206         }
 207 };
 208
 209 } // namespace test
 210 } // namespace gmx
 211
 212 #endif