src/testutils/include/testutils/testfilemanager.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013,2014,2015,2018 by the GROMACS development team.
   5  * Copyright (c) 2019,2020, by the GROMACS development team, led by
   6  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7  * and including many others, as listed in the AUTHORS file in the
   8  * top-level source directory and at http://www.gromacs.org.
   9  *
  10  * GROMACS is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public License
  12  * as published by the Free Software Foundation; either version 2.1
  13  * of the License, or (at your option) any later version.
  14  *
  15  * GROMACS is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with GROMACS; if not, see
  22  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24  *
  25  * If you want to redistribute modifications to GROMACS, please
  26  * consider that scientific software is very special. Version
  27  * control is crucial - bugs must be traceable. We will be happy to
  28  * consider code for inclusion in the official distribution, but
  29  * derived work must not be called official GROMACS. Details are found
  30  * in the README & COPYING files - if they are missing, get the
  31  * official version at http://www.gromacs.org.
  32  *
  33  * To help us fund GROMACS development, we humbly ask that you cite
  34  * the research papers on the package. Check out http://www.gromacs.org.
  35  */
  36 /*! \libinternal \file
  37  * \brief
  38  * Declares gmx::test::TestFileManager.
  39  *
  40  * \author Teemu Murtola <teemu.murtola@gmail.com>
  41  * \inlibraryapi
  42  * \ingroup module_testutils
  43  */
  44 #ifndef GMX_TESTUTILS_TESTFILEMANAGER_H
  45 #define GMX_TESTUTILS_TESTFILEMANAGER_H
  46
  47 #include <string>
  48
  49 #include "gromacs/utility/classhelpers.h"
  50
  51 namespace gmx
  52 {
  53 /*! \libinternal \brief
  54  * Testing utilities namespace.
  55  *
  56  * This namespace contains utilities for writing unit tests, mostly from the
  57  * \ref module_testutils module.
  58  */
  59 namespace test
  60 {
  61
  62 /*! \libinternal \brief
  63  * Helper for tests that need input and output files.
  64  *
  65  * To be used as a member in a test fixture class, this class provides
  66  * getTemporaryFilePath() method that returns a path for creating file names
  67  * for temporary files.  The returned path contains the name of the running
  68  * test, making it unique across tests.  Additionally, this class takes care of
  69  * removing any temporary files (i.e., all paths returned by
  70  * getTemporaryFilePath()) at test teardown (i.e., when the
  71  * TestFileManager is destructed).
  72  *
  73  * In addition, class-level static accessors provide means to
  74  * access data files that are located in the test source directory.
  75  * This is used to provide input files for the tests, and also to
  76  * store test reference data persistently (see TestReferenceData).
  77  *
  78  * Note that setInputDataDirectory(), setTestSimulationDataBaseDirectory() and
  79  * setGlobalOutputTempDirectory() must be called in setup code, before
  80  * creating any objects of this class that are used for accessing the
  81  * paths for these respective directories. Code in tests should avoid
  82  * calling setGlobalOutputTempDirectory(), and instead instantiate an
  83  * object and use setOutputTempDirectory(), so that the global state
  84  * is not changed.
  85  *
  86  * \inlibraryapi
  87  * \ingroup module_testutils
  88  */
  89 class TestFileManager
  90 {
  91 public:
  92     /*! \brief Constructor */
  93     TestFileManager();
  94     /*! \brief Frees internal storage and deletes any accessed
  95      * file paths
  96      *
  97      * Any errors (e.g., missing files) encountered while deleting the
  98      * files are ignored.
  99      */
 100     ~TestFileManager();
 101
 102     /*! \brief
 103      * Creates a name for a temporary file within a single unit test.
 104      *
 105      * \param[in] suffix  Suffix to add to the file name (should contain an
 106      *      extension if one is desired).
 107      * \returns   Temporary file name that includes the test name and
 108      *      \p suffix.
 109      *
 110      * This method should only be called from within a Google Test test.
 111      * Two calls with the same \p suffix return the same string within the
 112      * same test.
 113      */
 114     std::string getTemporaryFilePath(const char* suffix);
 115     //! \copydoc TestFileManager::getTemporaryFilePath(const char *)
 116     std::string getTemporaryFilePath(const std::string& suffix);
 117
 118     /*! \brief Returns the path to the output temporary directory
 119      * for tests which use this TestFileManager object.
 120      *
 121      * \returns Path to output temporary directory
 122      */
 123     const char* getOutputTempDirectory() const;
 124
 125     /*! \brief Sets the output temporary directory for tests which
 126      * use this TestFileManager object.
 127      *
 128      * \param[in] path  Path at which test should write temporary files
 129      *
 130      * \p path must name an existing directory. An internal copy
 131      * of path is made. The caller is responsible for holding a
 132      * valid mutex on the object before calling this member
 133      * function.
 134      */
 135     void setOutputTempDirectory(const std::string& path);
 136
 137     // static functions follow
 138
 139     /*! \brief
 140      * Creates a file name root for use within a single unit test.
 141      *
 142      * This method should only be called from within a Google Test
 143      * test. Uses the Google Test test fixture and test case name
 144      * to construct a string that is unique over all
 145      * tests. Intended to produce distinct names for files that
 146      * may be stored in the same directory for multiple tests.
 147      */
 148     static std::string getTestSpecificFileNameRoot();
 149
 150     /*! \brief
 151      * Creates a file name for use within a single unit test.
 152      *
 153      * \param[in] suffix  Suffix to add to the file name (should contain an
 154      *      extension if one is desired).
 155      * \returns   File name that includes the test name and
 156      *      \p suffix.
 157      *
 158      * This method should only be called from within a Google Test test.
 159      * Two calls with the same \p suffix return the same string within the
 160      * same test.
 161      * Intended to produce distinct names for files that may be stored in
 162      * the same directory for multiple tests.
 163      */
 164     static std::string getTestSpecificFileName(const char* suffix);
 165
 166     /*! \brief
 167      * Returns the path to a test input file.
 168      *
 169      * \param[in] filename  Relative path/filename to a test input file.
 170      * \returns Path to \p filename under the test input data directory.
 171      */
 172     static std::string getInputFilePath(const char* filename);
 173     //! \copydoc TestFileManager::getInputFilePath(const char *)
 174     static std::string getInputFilePath(const std::string& filename);
 175
 176     /*! \brief
 177      * Returns the path to the simulation input database directory.
 178      *
 179      * \returns Path to simulation input database directory.
 180      */
 181     static const char* getTestSimulationDatabaseDirectory();
 182
 183     /*! \brief
 184      * Returns the path to the test input directory.
 185      *
 186      * \returns Path to input data directory for the test executable.
 187      */
 188     static const char* getInputDataDirectory();
 189
 190     /*! \brief
 191      * Sets the test input directory.
 192      *
 193      * \param[in] path  Path from which test input data is looked up from.
 194      *
 195      * \p path must name an existing directory.
 196      *
 197      * This function is automatically called by unittest_main.cpp through
 198      * initTestUtils().
 199      */
 200     static void setInputDataDirectory(const std::string& path);
 201
 202     /*! \brief
 203      * Sets the input directory for simulation input files.
 204      *
 205      * \param[in] path Path to look up the directory for simulation input files.
 206      *
 207      * \p path must name an exisitng directory.
 208      *
 209      * This function is automatically called by unittest_main.cpp through
 210      * initTestUtils().
 211      */
 212     static void setTestSimulationDatabaseDirectory(const std::string& path);
 213
 214     /*! \brief Returns the path to the global test output
 215      * temporary directory for future TestFileManager objects.
 216      *
 217      * \returns Path to default output temporary directory for the test executable.
 218      */
 219     static const char* getGlobalOutputTempDirectory();
 220
 221     /*! \brief Sets the default global test output temporary
 222      * directory for future TestFileManager objects.
 223      *
 224      * \param[in] path  Path at which tests should write temporary files
 225      *
 226      * \p path must name an existing directory.
 227      *
 228      * This function is automatically called by unittest_main.cpp
 229      * through initTestUtils(). Test fixtures should call
 230      * setOutputTempDirectory(), rather than change the global
 231      * state.
 232      */
 233     static void setGlobalOutputTempDirectory(const char* path);
 234
 235 private:
 236     class Impl;
 237
 238     PrivateImplPointer<Impl> impl_;
 239 };
 240
 241 } // namespace test
 242 } // namespace gmx
 243
 244 #endif