Extend TestFileManager

[alexxy/gromacs.git] / src / testutils / testfilemanager.h

diff --git a/src/testutils/testfilemanager.h b/src/testutils/testfilemanager.h
index 62c3314824f2810f17a2caa30c9368dbf418b561..ea88776e4b3fbd3359116a3234ef17cc99374a8e 100644 (file)
--- a/src/testutils/testfilemanager.h
+++ b/src/testutils/testfilemanager.h
@@ -1,7 +1,7 @@
 /*
  * This file is part of the GROMACS molecular simulation package.
  *
- * Copyright (c) 2012,2013, by the GROMACS development team, led by
+ * Copyright (c) 2012,2013,2014, by the GROMACS development team, led by
  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
  * and including many others, as listed in the AUTHORS file in the
  * top-level source directory and at http://www.gromacs.org.
@@ -67,7 +67,7 @@ namespace test
 {
 
 /*! \libinternal \brief
- * Helper for tests that need output files.
+ * Helper for tests that need input and output files.
  *
  * To be used as a member in a test fixture class, this class provides
  * getTemporaryFilePath() method that returns a path for creating file names
@@ -77,10 +77,18 @@ namespace test
  * getTemporaryFilePath()) at test teardown (i.e., when the
  * TestFileManager is destructed).
  *
- * Functions getInputFilePath() and getInputDataDirectory() provide means to
+ * In addition, class-level static accessors provide means to
  * access data files that are located in the test source directory.
- * This is used to provide input files for the tests, and also to store test
- * reference data persistently (see TestReferenceData).
+ * This is used to provide input files for the tests, and also to
+ * store test reference data persistently (see TestReferenceData).
+ *
+ * Note that setInputDataDirectory() and
+ * setGlobalOutputTempDirectory() must be called in setup code, before
+ * creating any objects of this class that are used for accessing the
+ * paths for these respective directories. Code in tests should avoid
+ * calling setGlobalOutputTempDirectory(), and instead instantiate an
+ * object and use setOutputTempDirectory(), so that the global state
+ * is not changed.
  *
  * \inlibraryapi
  * \ingroup module_testutils
@@ -112,6 +120,27 @@ class TestFileManager
          */
         std::string getTemporaryFilePath(const char *suffix);
 
+        /*! \brief Returns the path to the output temporary directory
+         * for tests which use this TestFileManager object.
+         *
+         * \returns Path to output temporary directory
+         */
+        const char *getOutputTempDirectory() const;
+
+        /*! \brief Sets the output temporary directory for tests which
+         * use this TestFileManager object.
+         *
+         * \param[in] path  Path at which test should write temporary files
+         *
+         * \p path must name an existing directory. An internal copy
+         * of path is made. The caller is responsible for holding a
+         * valid mutex on the object before calling this member
+         * function.
+         */
+        void setOutputTempDirectory(const std::string &path);
+
+        // static functions follow
+
         /*! \brief
          * Creates a file name for use within a single unit test.
          *
@@ -143,13 +172,6 @@ class TestFileManager
          */
         static const char *getInputDataDirectory();
 
-        /*! \brief
-         * Returns the path to the test output temporary directory.
-         *
-         * \returns Path to output temporary directory for the test executable.
-         */
-        static const char *getOutputTempDirectory();
-
         /*! \brief
          * Sets the test input directory.
          *
@@ -162,17 +184,26 @@ class TestFileManager
          */
         static void setInputDataDirectory(const char *path);
 
-        /*! \brief
-         * Sets the test output temporary directory.
+        /*! \brief Returns the path to the global test output
+         * temporary directory for future TestFileManager objects.
          *
-         * \param[in] path  Path at which test should write temporary files
+         * \returns Path to default output temporary directory for the test executable.
+         */
+        static const char *getGlobalOutputTempDirectory();
+
+        /*! \brief Sets the default global test output temporary
+         * directory for future TestFileManager objects.
+         *
+         * \param[in] path  Path at which tests should write temporary files
          *
          * \p path must name an existing directory.
          *
-         * This function is automatically called by unittest_main.cpp through
-         * initTestUtils().
+         * This function is automatically called by unittest_main.cpp
+         * through initTestUtils(). Test fixtures should call
+         * setOutputTempDirectory(), rather than change the global
+         * state.
          */
-        static void setOutputTempDirectory(const char *path);
+        static void setGlobalOutputTempDirectory(const char *path);
 
     private:
         class Impl;