Gromacs  2026.0-dev-20241106-9ba7f4d
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Member Functions | Static Public Member Functions
gmx::test::CommandLineTestHelper Class Reference

#include <testutils/include/testutils/cmdlinetest.h>

Description

Helper class for tests that construct command lines that need to reference existing files.

This class provides helper methods for:

  1. Adding input files to a CommandLine instance by generating them from a string provided in the test (setInputFileContents()).
  2. Adding output files to a CommandLine instance (setOutputFile()).
  3. Checking the contents of some of the output files using TestReferenceData (setOutputFile() and checkOutputFiles()).
  4. Static methods for easily executing command-line modules (various overloads of runModule()).

All files created during the test are cleaned up at the end of the test.

All methods can throw std::bad_alloc.

See Also
TestFileManager

Public Member Functions

 CommandLineTestHelper (TestFileManager *fileManager)
 Initializes an instance. More...
 
void setInputFileContents (CommandLine *args, const char *option, const char *extension, const std::string &contents)
 Generates and sets an input file. More...
 
void setInputFileContents (CommandLine *args, const char *option, const char *extension, const ArrayRef< const char *const > &contents)
 Generates and sets an input file. More...
 
std::string setOutputFile (CommandLine *args, const char *option, const char *filename, const ITextBlockMatcherSettings &matcher)
 Sets an output file parameter and adds it to the set of tested files. More...
 
std::string setOutputFile (CommandLine *args, const char *option, const char *filename, const IFileMatcherSettings &matcher)
 Sets an output file parameter and adds it to the set of tested files. More...
 
std::string setOutputFileWithGeneratedName (const char *filename, const ITextBlockMatcherSettings &matcher)
 As for setOutputFile() but does not create an option. More...
 
std::string setOutputFileWithGeneratedName (std::string &&filename, const ITextBlockMatcherSettings &matcher)
 As for setOutputFile() but does not create an option. More...
 
std::string setOutputFileWithGeneratedName (const char *filename, const IFileMatcherSettings &matcher)
 As for setOutputFile() but does not create an option. More...
 
std::string setOutputFileWithGeneratedName (std::string &&filename, const IFileMatcherSettings &matcher)
 As for setOutputFile() but does not create an option. More...
 
void checkOutputFiles (TestReferenceChecker checker) const
 Checks output files added with setOutputFile() against reference data. More...
 

Static Public Member Functions

static int runModuleDirect (ICommandLineModule *module, CommandLine *commandLine)
 Runs a command-line program that implements ICommandLineModule. More...
 
static int runModuleDirect (std::unique_ptr< ICommandLineOptionsModule > module, CommandLine *commandLine)
 Runs a command-line program that implements ICommandLineOptionsModule. More...
 
static int runModuleFactory (const std::function< std::unique_ptr< ICommandLineOptionsModule >()> &factory, CommandLine *commandLine)
 Runs a command-line program that implements ICommandLineOptionsModule. More...
 

Constructor & Destructor Documentation

gmx::test::CommandLineTestHelper::CommandLineTestHelper ( TestFileManager fileManager)
explicit

Initializes an instance.

Parameters
fileManagerFile manager to use for generating temporary file names and to track temporary files.

Member Function Documentation

void gmx::test::CommandLineTestHelper::checkOutputFiles ( TestReferenceChecker  checker) const

Checks output files added with setOutputFile() against reference data.

Parameters
checkerReference data root location where the reference data is stored.

The file contents are tested verbatim, using direct string comparison. The text can be found verbatim in the reference data XML files for manual inspection.

Generates non-fatal test failures if some output file contents do not match the reference data.

int gmx::test::CommandLineTestHelper::runModuleDirect ( ICommandLineModule module,
CommandLine commandLine 
)
static

Runs a command-line program that implements ICommandLineModule.

Parameters
[in,out]moduleModule to run. The function does not take ownership.
[in,out]commandLineCommand line parameters to pass. This is only modified if module modifies it.
Returns
The return value of the module.
Exceptions
unspecifiedAny exception thrown by the module.
int gmx::test::CommandLineTestHelper::runModuleDirect ( std::unique_ptr< ICommandLineOptionsModule module,
CommandLine commandLine 
)
static

Runs a command-line program that implements ICommandLineOptionsModule.

Parameters
[in,out]moduleModule to run.
[in,out]commandLineCommand line parameters to pass. This is only modified if module modifies it.
Returns
The return value of the module.
Exceptions
unspecifiedAny exception thrown by the module.
int gmx::test::CommandLineTestHelper::runModuleFactory ( const std::function< std::unique_ptr< ICommandLineOptionsModule >()> &  factory,
CommandLine commandLine 
)
static

Runs a command-line program that implements ICommandLineOptionsModule.

Parameters
[in]factoryFactory method for the module to run.
[in,out]commandLineCommand line parameters to pass. This is only modified if the module modifies it.
Returns
The return value of the module.
Exceptions
unspecifiedAny exception thrown by the factory or the module.
void gmx::test::CommandLineTestHelper::setInputFileContents ( CommandLine args,
const char *  option,
const char *  extension,
const std::string &  contents 
)

Generates and sets an input file.

Parameters
[in,out]argsCommandLine to which to add the option.
[in]optionOption to set.
[in]extensionExtension for the file to create.
[in]contentsText to write to the input file.

Creates a temporary file with contents from contents, and adds option to args with a value that points to the generated file.

void gmx::test::CommandLineTestHelper::setInputFileContents ( CommandLine args,
const char *  option,
const char *  extension,
const ArrayRef< const char *const > &  contents 
)

Generates and sets an input file.

Parameters
[in,out]argsCommandLine to which to add the option.
[in]optionOption to set.
[in]extensionExtension for the file to create.
[in]contentsText to write to the input file.

Creates a temporary file with contents from contents (each array entry on its own line), and adds option to args with a value that points to the generated file.

std::string gmx::test::CommandLineTestHelper::setOutputFile ( CommandLine args,
const char *  option,
const char *  filename,
const ITextBlockMatcherSettings matcher 
)

Sets an output file parameter and adds it to the set of tested files.

Parameters
[in,out]argsCommandLine to which to add the option.
[in]optionOption to set.
[in]filenameName of the output file.
[in]matcherSpecifies how the contents of the file are tested.
Returns
The name of the output file

This method does the following:

  • Adds option to args to point a temporary file name constructed from filename.
  • Makes checkOutputFiles() to check the contents of the file against reference data, using matcher.
  • Marks the temporary file for removal at test teardown.

filename is given to TestTemporaryFileManager to make a unique filename for the temporary file. If filename starts with a dot, a unique number is prefixed (such that it is possible to create multiple files with the same extension by just specifying the extension for every call of setOutputFile()).

If the output file is needed to trigger some computation, or is unconditionally produced by the code under test, but the contents are not interesting for the test, use NoContentsMatch as the matcher. Note that the existence of the output file is still verified.

std::string gmx::test::CommandLineTestHelper::setOutputFile ( CommandLine args,
const char *  option,
const char *  filename,
const IFileMatcherSettings matcher 
)

Sets an output file parameter and adds it to the set of tested files.

Parameters
[in,out]argsCommandLine to which to add the option.
[in]optionOption to set.
[in]filenameName of the output file.
[in]matcherSpecifies how the contents of the file are tested.
Returns
The name of the output file

This method does the following:

  • Adds option to args to point a temporary file name constructed from filename.
  • Makes checkOutputFiles() to check the contents of the file against reference data, using matcher.
  • Marks the temporary file for removal at test teardown.

filename is given to TestTemporaryFileManager to make a unique filename for the temporary file. If filename starts with a dot, a unique number is prefixed (such that it is possible to create multiple files with the same extension by just specifying the extension for every call of setOutputFile()).

If the output file is needed to trigger some computation, or is unconditionally produced by the code under test, but the contents are not interesting for the test, use NoContentsMatch as the matcher. Note that the existence of the output file is still verified.

std::string gmx::test::CommandLineTestHelper::setOutputFileWithGeneratedName ( const char *  filename,
const ITextBlockMatcherSettings matcher 
)

As for setOutputFile() but does not create an option.

This method is useful when a tool generates a series of output files by modifying a common base name. Call this method with every file name that is expected to be generated by the tool. It returns the name of the output file

std::string gmx::test::CommandLineTestHelper::setOutputFileWithGeneratedName ( std::string &&  filename,
const ITextBlockMatcherSettings matcher 
)

As for setOutputFile() but does not create an option.

This method is useful when a tool generates a series of output files by modifying a common base name. Call this method with every file name that is expected to be generated by the tool. It returns the name of the output file

std::string gmx::test::CommandLineTestHelper::setOutputFileWithGeneratedName ( const char *  filename,
const IFileMatcherSettings matcher 
)

As for setOutputFile() but does not create an option.

This method is useful when a tool generates a series of output files by modifying a common base name. Call this method with every file name that is expected to be generated by the tool. It returns the name of the output file

std::string gmx::test::CommandLineTestHelper::setOutputFileWithGeneratedName ( std::string &&  filename,
const IFileMatcherSettings matcher 
)

As for setOutputFile() but does not create an option.

This method is useful when a tool generates a series of output files by modifying a common base name. Call this method with every file name that is expected to be generated by the tool. It returns the name of the output file


The documentation for this class was generated from the following files: