#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:

Adding input files to a CommandLine instance by generating them from a string provided in the test (setInputFileContents()).
Adding output files to a CommandLine instance (setOutputFile()).
Checking the contents of some of the output files using TestReferenceData (setOutputFile() and checkOutputFiles()).
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

fileManager File 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

checker Reference 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]	module	Module to run. The function does not take ownership.
[in,out]	commandLine	Command line parameters to pass. This is only modified if `module` modifies it.

Returns: The return value of the module.

Exceptions

unspecified Any 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]	module	Module to run.
[in,out]	commandLine	Command line parameters to pass. This is only modified if `module` modifies it.

Returns: The return value of the module.

Exceptions

unspecified Any 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]	factory	Factory method for the module to run.
[in,out]	commandLine	Command line parameters to pass. This is only modified if the module modifies it.

Returns: The return value of the module.

Exceptions

unspecified Any 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]	args	CommandLine to which to add the option.
[in]	option	Option to set.
[in]	extension	Extension for the file to create.
[in]	contents	Text 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]	args	CommandLine to which to add the option.
[in]	option	Option to set.
[in]	extension	Extension for the file to create.
[in]	contents	Text 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]	args	CommandLine to which to add the option.
[in]	option	Option to set.
[in]	filename	Name of the output file.
[in]	matcher	Specifies 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]	args	CommandLine to which to add the option.
[in]	option	Option to set.
[in]	filename	Name of the output file.
[in]	matcher	Specifies 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:

src/testutils/include/testutils/cmdlinetest.h
src/testutils/cmdlinetest.cpp

Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation