src/testutils/cmdlinetest.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013,2014,2015,2016,2017,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 /*! \libinternal \file
  36  * \brief
  37  * Declares utilities testing command-line programs.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \inlibraryapi
  41  * \ingroup module_testutils
  42  */
  43 #ifndef GMX_TESTUTILS_CMDLINETEST_H
  44 #define GMX_TESTUTILS_CMDLINETEST_H
  45
  46 #include <functional>
  47 #include <memory>
  48 #include <string>
  49
  50 #include <gtest/gtest.h>
  51
  52 // arrayref.h is not strictly necessary for this header, but nearly all
  53 // callers will need it to use the constructor that takes ArrayRef.
  54 #include "gromacs/utility/arrayref.h"
  55 #include "gromacs/utility/classhelpers.h"
  56
  57 namespace gmx
  58 {
  59
  60 class ICommandLineModule;
  61 class ICommandLineOptionsModule;
  62
  63 namespace test
  64 {
  65
  66 class FloatingPointTolerance;
  67 class IFileMatcherSettings;
  68 class ITextBlockMatcherSettings;
  69 class TestFileManager;
  70 class TestReferenceChecker;
  71
  72 /*! \libinternal \brief
  73  * Helper class for tests that need to construct command lines.
  74  *
  75  * This class helps in writing tests for command-line handling.
  76  * The constructor method takes an array of const char pointers, specifying the
  77  * command-line arguments, each as one array element.  It is also possible to
  78  * construct the command line by adding individual arguments with append() and
  79  * addOption().
  80  * The argc() and argv() methods can then be used to obtain `argc` and `argv`
  81  * (non-const char pointers) arrays for passing into methods that expect these.
  82  *
  83  * Note that although the interface allows passing the argc and argv pointers
  84  * to methods that modify them (typically as \p f(&argc(), argv())), currently
  85  * the CommandLine object is not in a consistent state internally if the
  86  * parameters are actually modified.  Reading the command line is possible
  87  * afterwards, but modification is not.
  88  *
  89  * If you need to construct command lines that refer to files on the file
  90  * system, see CommandLineTestHelper and CommandLineTestBase for additional
  91  * convenience utilities.
  92  *
  93  * All constructors and methods that modify this class may throw an
  94  * std::bad_alloc.  Const methods and accessors do not throw.
  95  *
  96  * \inlibraryapi
  97  * \ingroup module_testutils
  98  */
  99 class CommandLine
 100 {
 101 public:
 102     //! Initializes an empty command-line object.
 103     CommandLine();
 104     /*! \brief
 105      * Initializes a command-line object from an array.
 106      *
 107      * \param[in] cmdline  Array of command-line arguments.
 108      *
 109      * \p cmdline should include the binary name as the first element if
 110      * that is desired in the output.
 111      *
 112      * This constructor is not explicit to make it possible to create a
 113      * CommandLine object directly from a C array.
 114      */
 115     CommandLine(const ArrayRef<const char* const>& cmdline);
 116     //! \copydoc CommandLine(const ArrayRef<const char *const> &)
 117     CommandLine(const ArrayRef<const std::string>& cmdline);
 118     //! Creates a deep copy of a command-line object.
 119     CommandLine(const CommandLine& other);
 120     ~CommandLine();
 121
 122     /*! \brief
 123      * Initializes a command-line object in-place from an array.
 124      *
 125      * \param[in] cmdline  Array of command-line arguments.
 126      *
 127      * \p cmdline should include the binary name as the first element if
 128      * that is desired in the output.
 129      *
 130      * This function does the same as the constructor that takes a
 131      * ArrayRef.  Any earlier contents of the object are discarded.
 132      *
 133      * Strong exception safety.
 134      */
 135     void initFromArray(const ArrayRef<const char* const>& cmdline);
 136
 137     /*! \brief
 138      * Appends an argument to the command line.
 139      *
 140      * \param[in] arg  Argument to append.
 141      *
 142      * Strong exception safety.
 143      */
 144     void append(const char* arg);
 145     //! Convenience overload taking a std::string.
 146     void append(const std::string& arg) { append(arg.c_str()); }
 147     /*! \brief
 148      * Adds an option to the command line, typically a boolean.
 149      *
 150      * \param[in] name   Name of the option to append, which
 151      *                   should start with "-".
 152      */
 153     void addOption(const char* name);
 154     /*! \brief
 155      * Adds an option-value pair to the command line.
 156      *
 157      * \param[in] name   Name of the option to append, which
 158      *                   should start with "-".
 159      * \param[in] value  Value of the argument to append.
 160      */
 161     void addOption(const char* name, const char* value);
 162     //! Convenience overload taking a std::string.
 163     void addOption(const char* name, const std::string& value);
 164     //! Overload taking an int.
 165     void addOption(const char* name, int value);
 166     //! Overload taking a double.
 167     void addOption(const char* name, double value);
 168     /*! \brief
 169      * Appends all arguments from \p args to the command line.
 170      *
 171      * If the first argument of \p args does not start with a `-`, it is
 172      * skipped, assuming it is a gmx module name and thus useless.
 173      */
 174     void merge(const CommandLine& args);
 175
 176     //! Returns argc for passing into C-style command-line handling.
 177     int& argc();
 178     //! Returns argv for passing into C-style command-line handling.
 179     char** argv();
 180     //! Returns argc for passing into C-style command-line handling.
 181     int argc() const;
 182     //! Returns argv for passing into C-style command-line handling.
 183     const char* const* argv() const;
 184     //! Returns a single argument.
 185     const char* arg(int i) const;
 186
 187     //! Returns the command line formatted as a single string.
 188     std::string toString() const;
 189
 190     //! Whether the command line contains the given option.
 191     bool contains(const char* name) const;
 192
 193 private:
 194     class Impl;
 195
 196     PrivateImplPointer<Impl> impl_;
 197 };
 198
 199 /*! \libinternal \brief
 200  * Helper class for tests that construct command lines that need to reference
 201  * existing files.
 202  *
 203  * This class provides helper methods for:
 204  *
 205  *   1. Adding input files to a CommandLine instance by generating them from a
 206  *      string provided in the test (setInputFileContents()).
 207  *   2. Adding output files to a CommandLine instance (setOutputFile()).
 208  *   3. Checking the contents of some of the output files using
 209  *      TestReferenceData (setOutputFile() and checkOutputFiles()).
 210  *   4. Static methods for easily executing command-line modules
 211  *      (various overloads of runModule()).
 212  *
 213  * All files created during the test are cleaned up at the end of the test.
 214  *
 215  * All methods can throw std::bad_alloc.
 216  *
 217  * \see TestFileManager
 218  * \inlibraryapi
 219  * \ingroup module_testutils
 220  */
 221 class CommandLineTestHelper
 222 {
 223 public:
 224     /*! \brief
 225      * Runs a command-line program that implements ICommandLineModule.
 226      *
 227      * \param[in,out] module       Module to run.
 228      *     The function does not take ownership.
 229      * \param[in,out] commandLine  Command line parameters to pass.
 230      *     This is only modified if \p module modifies it.
 231      * \returns The return value of the module.
 232      * \throws  unspecified  Any exception thrown by the module.
 233      */
 234     static int runModuleDirect(ICommandLineModule* module, CommandLine* commandLine);
 235     /*! \brief
 236      * Runs a command-line program that implements
 237      * ICommandLineOptionsModule.
 238      *
 239      * \param[in,out] module       Module to run.
 240      * \param[in,out] commandLine  Command line parameters to pass.
 241      *     This is only modified if \p module modifies it.
 242      * \returns The return value of the module.
 243      * \throws  unspecified  Any exception thrown by the module.
 244      */
 245     static int runModuleDirect(std::unique_ptr<ICommandLineOptionsModule> module, CommandLine* commandLine);
 246     /*! \brief
 247      * Runs a command-line program that implements
 248      * ICommandLineOptionsModule.
 249      *
 250      * \param[in] factory          Factory method for the module to run.
 251      * \param[in,out] commandLine  Command line parameters to pass.
 252      *     This is only modified if the module modifies it.
 253      * \returns The return value of the module.
 254      * \throws  unspecified  Any exception thrown by the factory or the
 255      *     module.
 256      */
 257     static int runModuleFactory(const std::function<std::unique_ptr<ICommandLineOptionsModule>()>& factory,
 258                                 CommandLine* commandLine);
 259
 260     /*! \brief
 261      * Initializes an instance.
 262      *
 263      * \param  fileManager  File manager to use for generating temporary
 264      *     file names and to track temporary files.
 265      */
 266     explicit CommandLineTestHelper(TestFileManager* fileManager);
 267     ~CommandLineTestHelper();
 268
 269     /*! \brief
 270      * Generates and sets an input file.
 271      *
 272      * \param[in,out] args      CommandLine to which to add the option.
 273      * \param[in]     option    Option to set.
 274      * \param[in]     extension Extension for the file to create.
 275      * \param[in]     contents  Text to write to the input file.
 276      *
 277      * Creates a temporary file with contents from \p contents, and adds
 278      * \p option to \p args with a value that points to the generated file.
 279      */
 280     void setInputFileContents(CommandLine*       args,
 281                               const char*        option,
 282                               const char*        extension,
 283                               const std::string& contents);
 284     /*! \brief
 285      * Generates and sets an input file.
 286      *
 287      * \param[in,out] args      CommandLine to which to add the option.
 288      * \param[in]     option    Option to set.
 289      * \param[in]     extension Extension for the file to create.
 290      * \param[in]     contents  Text to write to the input file.
 291      *
 292      * Creates a temporary file with contents from \p contents (each array
 293      * entry on its own line), and adds \p option to \p args with a value
 294      * that points to the generated file.
 295      */
 296     void setInputFileContents(CommandLine*                       args,
 297                               const char*                        option,
 298                               const char*                        extension,
 299                               const ArrayRef<const char* const>& contents);
 300     /*! \brief
 301      * Sets an output file parameter and adds it to the set of tested files.
 302      *
 303      * \param[in,out] args      CommandLine to which to add the option.
 304      * \param[in]     option    Option to set.
 305      * \param[in]     filename  Name of the output file.
 306      * \param[in]     matcher   Specifies how the contents of the file are
 307      *     tested.
 308      *
 309      * This method does the following:
 310      *  - Adds \p option to \p args to point a temporary file name
 311      *    constructed from \p filename.
 312      *  - Makes checkOutputFiles() to check the contents of the file
 313      *    against reference data, using \p matcher.
 314      *  - Marks the temporary file for removal at test teardown.
 315      *
 316      * \p filename is given to TestTemporaryFileManager to make a unique
 317      * filename for the temporary file.
 318      * If \p filename starts with a dot, a unique number is prefixed (such
 319      * that it is possible to create multiple files with the same extension
 320      * by just specifying the extension for every call of setOutputFile()).
 321      *
 322      * If the output file is needed to trigger some computation, or is
 323      * unconditionally produced by the code under test, but the contents
 324      * are not interesting for the test, use NoContentsMatch as the matcher.
 325      * Note that the existence of the output file is still verified.
 326      */
 327     void setOutputFile(CommandLine*                     args,
 328                        const char*                      option,
 329                        const char*                      filename,
 330                        const ITextBlockMatcherSettings& matcher);
 331     //! \copydoc setOutputFile(CommandLine *, const char *, const char *, const ITextBlockMatcherSettings &)
 332     void setOutputFile(CommandLine*                args,
 333                        const char*                 option,
 334                        const char*                 filename,
 335                        const IFileMatcherSettings& matcher);
 336
 337     /*! \brief
 338      * Checks output files added with setOutputFile() against reference
 339      * data.
 340      *
 341      * \param     checker  Reference data root location where the reference
 342      *     data is stored.
 343      *
 344      * The file contents are tested verbatim, using direct string
 345      * comparison.  The text can be found verbatim in the reference data
 346      * XML files for manual inspection.
 347      *
 348      * Generates non-fatal test failures if some output file contents do
 349      * not match the reference data.
 350      */
 351     void checkOutputFiles(TestReferenceChecker checker) const;
 352
 353 private:
 354     class Impl;
 355
 356     PrivateImplPointer<Impl> impl_;
 357 };
 358
 359 /*! \libinternal \brief
 360  * Test fixture for tests that call a single command-line program with
 361  * input/output files.
 362  *
 363  * This class provides a convenient package for using CommandLineTestHelper in
 364  * a test that do not need special customization.  It takes care of creating
 365  * the other necessary objects (like TestFileManager, TestReferenceData, and
 366  * CommandLine) and wrapping the methods from CommandLineTestHelper such that
 367  * extra parameters are not needed.  Additionally, it provides setInputFile()
 368  * as a convenience function for adding a fixed input file, pointing to a file
 369  * that resides in the source tree.
 370  *
 371  * \see CommandLineTestHelper
 372  * \inlibraryapi
 373  * \ingroup module_testutils
 374  */
 375 class CommandLineTestBase : public ::testing::Test
 376 {
 377 public:
 378     CommandLineTestBase();
 379     ~CommandLineTestBase() override;
 380
 381     /*! \brief
 382      * Sets an input file.
 383      *
 384      * \param[in]     option    Option to set.
 385      * \param[in]     filename  Name of the input file.
 386      *
 387      * \see TestFileManager::getInputFilePath()
 388      */
 389     void setInputFile(const char* option, const char* filename);
 390     //! \copydoc setInputFile(const char *, const char *);
 391     void setInputFile(const char* option, const std::string& filename);
 392     /*! \brief
 393      * Sets an input file that may be modified. The file is copied to a
 394      * temporary file, which is used as the test input
 395      *
 396      * \param[in]     option    Option to set.
 397      * \param[in]     filename  Name of the input file.
 398      *
 399      */
 400     void setModifiableInputFile(const char* option, const char* filename);
 401     //! \copydoc setModifiableInputFile(const char *, const char *);
 402     void setModifiableInputFile(const char* option, const std::string& filename);
 403     /*! \brief
 404      * Generates and sets an input file.
 405      *
 406      * \see CommandLineTestHelper::setInputFileContents()
 407      */
 408     void setInputFileContents(const char* option, const char* extension, const std::string& contents);
 409     /*! \brief
 410      * Generates and sets an input file.
 411      *
 412      * \see CommandLineTestHelper::setInputFileContents()
 413      */
 414     void setInputFileContents(const char*                        option,
 415                               const char*                        extension,
 416                               const ArrayRef<const char* const>& contents);
 417     /*! \brief
 418      * Sets an output file parameter and adds it to the set of tested files.
 419      *
 420      * \see CommandLineTestHelper::setOutputFile()
 421      */
 422     void setOutputFile(const char* option, const char* filename, const ITextBlockMatcherSettings& matcher);
 423     /*! \brief
 424      * Sets an output file parameter and adds it to the set of tested files.
 425      *
 426      * \see CommandLineTestHelper::setOutputFile()
 427      */
 428     void setOutputFile(const char* option, const char* filename, const IFileMatcherSettings& matcher);
 429     /*! \brief
 430      * Sets a file parameter that is used for input and modified as output. The input file
 431      * is copied to a temporary file that is used as input and can be modified.
 432      */
 433     void setInputAndOutputFile(const char*                      option,
 434                                const char*                      filename,
 435                                const ITextBlockMatcherSettings& matcher);
 436     //! \copydoc setInputAndOutputFile(const char *, const char *, const ITextBlockMatcherSettings&);
 437     void setInputAndOutputFile(const char* option, const char* filename, const IFileMatcherSettings& matcher);
 438
 439     /*! \brief
 440      * Returns the internal CommandLine object used to construct the
 441      * command line for the test.
 442      *
 443      * Derived test fixtures can use this to add additional options, and
 444      * to access the final command line to do the actual call that is being
 445      * tested.
 446      *
 447      * Does not throw.
 448      */
 449     CommandLine& commandLine();
 450     /*! \brief
 451      * Returns the internal TestFileManager object used to manage the
 452      * files.
 453      *
 454      * Derived test fixtures can use this to manage files in cases the
 455      * canned methods are not sufficient.
 456      *
 457      * Does not throw.
 458      */
 459     TestFileManager& fileManager();
 460     /*! \brief
 461      * Returns the root reference data checker.
 462      *
 463      * Derived test fixtures can use this to check other things than output
 464      * file contents.
 465      */
 466     TestReferenceChecker rootChecker();
 467     /*! \brief
 468      * Sets the tolerance for floating-point comparisons.
 469      *
 470      * All following floating-point comparisons using the checker will use
 471      * the new tolerance.
 472      *
 473      * Does not throw.
 474      */
 475     void setDefaultTolerance(const FloatingPointTolerance& tolerance);
 476     /*! \brief
 477      * Checks the output of writeHelp() against reference data.
 478      */
 479     void testWriteHelp(ICommandLineModule* module);
 480     /*! \brief
 481      * Checks output files added with setOutputFile() against reference
 482      * data.
 483      *
 484      * \see CommandLineTestHelper::checkOutputFiles()
 485      */
 486     void checkOutputFiles();
 487
 488 private:
 489     class Impl;
 490
 491     PrivateImplPointer<Impl> impl_;
 492 };
 493
 494 } // namespace test
 495 } // namespace gmx
 496
 497 #endif