Execute an example program as a test, by comparing the output to a reference file. More...

#include "example-as-test.h"

Inheritance diagram for ns3::ExampleAsTestCase:

Collaboration diagram for ns3::ExampleAsTestCase:

Public Member Functions
	ExampleAsTestCase (const std::string name, const std::string program, const std::string dataDir, const std::string args="", const bool shouldNotErr=true)
	Constructor.

	~ExampleAsTestCase () override
	Destructor.

void	DoRun () override
	Implementation to actually run this TestCase.

virtual std::string	GetCommandTemplate () const
	Customization point for more complicated patterns to invoke the example program.

virtual std::string	GetPostProcessingCommand () const
	Customization point for tests requiring post-processing of stdout.

Public Member Functions inherited from ns3::TestCase
	TestCase (const TestCase &)=delete

virtual	~TestCase ()
	Destructor.

std::string	GetName () const

TestCase &	operator= (const TestCase &)=delete

Protected Attributes
std::string	m_args
	Any additional arguments to the program.

std::string	m_dataDir
	The source directory for the test.

std::string	m_program
	The program to run.

bool	m_shouldNotErr
	Whether error return status is a test failure.

Additional Inherited Members
Public Types inherited from ns3::TestCase
enum class	Duration { QUICK = 1 , EXTENSIVE = 2 , TAKES_FOREVER = 3 }
	How long the test takes to execute. More...

Static Public Attributes inherited from ns3::TestCase
static constexpr auto	QUICK = Duration::QUICK
	Deprecated test duration simple enums.

static constexpr auto	EXTENSIVE = Duration::EXTENSIVE

static constexpr auto	TAKES_FOREVER = Duration::TAKES_FOREVER

Protected Member Functions inherited from ns3::TestCase
	TestCase (std::string name)
	Constructor.

void	AddTestCase (TestCase *testCase, Duration duration=Duration::QUICK)
	Add an individual child TestCase to this test suite.

TestCase *	GetParent () const
	Get the parent of this TestCase.

bool	IsStatusFailure () const
	Check if any tests failed.

bool	IsStatusSuccess () const
	Check if all tests passed.

void	SetDataDir (std::string directory)
	Set the data directory where reference trace files can be found.

void	ReportTestFailure (std::string cond, std::string actual, std::string limit, std::string message, std::string file, int32_t line)
	Log the failure of this TestCase.

bool	MustAssertOnFailure () const
	Check if this run should assert on failure.

bool	MustContinueOnFailure () const
	Check if this run should continue on failure.

std::string	CreateDataDirFilename (std::string filename)
	Construct the full path to a file in the data directory.

std::string	CreateTempDirFilename (std::string filename)
	Construct the full path to a file in a temporary directory.

Detailed Description

Execute an example program as a test, by comparing the output to a reference file.

User can subclass and override the GetCommandTemplate() and GetPostProcessingCommand() methods if more complex example invocation patterns are required.

See also: examples-as-tests-test-suite.cc

Definition at line 37 of file example-as-test.h.

Constructor & Destructor Documentation

◆ ExampleAsTestCase()

ns3::ExampleAsTestCase::ExampleAsTestCase	(	const std::string	name,
		const std::string	program,
		const std::string	dataDir,
		const std::string	args = "",
		const bool	shouldNotErr = true )

Constructor.

Parameters

[in]	name	The test case name, typically the program name and summary of the arguments, such as `my-example-foo`
[in]	program	The actual example program names, such as `my-example`
[in]	dataDir	The location of the reference file. This is normally provided by the symbol `NS_TEST_SOURCEDIR` in the `module-examples-test-suite.cc` file. The reference file should be named after the test case name, for example `my-example-foo.log`. If you use the `--update` argument to `test.py` or `test-runner` the reference file will be created with the correct name.
[in]	args	Any additional arguments to the program.
[in]	shouldNotErr	Whether an error return status should be considered a test failure. This is useful when testing error detection which might return a non-zero status. The output (on `std::cout` and `std::cerr`) will be compared to the reference logs as normal.

Definition at line 35 of file example-as-test.cc.

References NS_LOG_FUNCTION.

◆ ~ExampleAsTestCase()

ns3::ExampleAsTestCase::~ExampleAsTestCase ( )

override

Destructor.

Definition at line 49 of file example-as-test.cc.

References NS_LOG_FUNCTION_NOARGS.

Member Function Documentation

◆ DoRun()

void ns3::ExampleAsTestCase::DoRun ( )

overridevirtual

Implementation to actually run this TestCase.

Subclasses should override this method to conduct their tests.

Implements ns3::TestCase.

Definition at line 72 of file example-as-test.cc.

References ns3::TestCase::CreateDataDirFilename(), ns3::TestCase::CreateTempDirFilename(), ns3::EnvironmentVariable::Get(), GetCommandTemplate(), ns3::TestCase::GetName(), GetPostProcessingCommand(), m_dataDir, m_program, m_shouldNotErr, NS_ASCII_TEST_EXPECT_EQ, ns3::NS_FATAL_MSG, NS_LOG_FUNCTION_NOARGS, NS_TEST_ASSERT_MSG_EQ, and ns3::TestCase::SetDataDir().

Here is the call graph for this function:

◆ GetCommandTemplate()

std::string ns3::ExampleAsTestCase::GetCommandTemplate ( ) const

virtual

Customization point for more complicated patterns to invoke the example program.

Returns: The string to be given to the ns3 --command-template= argument.

Reimplemented in MpiTestCase.

Definition at line 55 of file example-as-test.cc.

References m_args, and NS_LOG_FUNCTION_NOARGS.

Referenced by DoRun().

Here is the caller graph for this function:

◆ GetPostProcessingCommand()

std::string ns3::ExampleAsTestCase::GetPostProcessingCommand ( ) const

virtual

Customization point for tests requiring post-processing of stdout.

For example to sort return "| sort"

One common case is to mask memory addresses, which can change when things are built on different platforms, recompiled locally, or even from run to run. A simple post-processing filter could be

‘"| sed -E 's/0x[0-9a-fA-F]{8,}/0x-address/g’"`

Default is "", no additional processing.

Returns: The string of post-processing commands

Reimplemented in MpiTestCase, and ns3::tests::CommandLineExampleTestCase.

Definition at line 64 of file example-as-test.cc.

References NS_LOG_FUNCTION_NOARGS.

Referenced by DoRun().

Here is the caller graph for this function:

Member Data Documentation

◆ m_args

std::string ns3::ExampleAsTestCase::m_args

protected

Any additional arguments to the program.

Definition at line 102 of file example-as-test.h.

Referenced by MpiTestCase::GetCommandTemplate(), and GetCommandTemplate().

◆ m_dataDir

std::string ns3::ExampleAsTestCase::m_dataDir

protected

The source directory for the test.

Definition at line 101 of file example-as-test.h.

Referenced by DoRun().

◆ m_program

std::string ns3::ExampleAsTestCase::m_program

protected

The program to run.

Definition at line 100 of file example-as-test.h.

Referenced by DoRun().

◆ m_shouldNotErr

bool ns3::ExampleAsTestCase::m_shouldNotErr

protected

Whether error return status is a test failure.

Definition at line 103 of file example-as-test.h.

Referenced by DoRun().

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

src/core/model/example-as-test.h
src/core/model/example-as-test.cc

Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ExampleAsTestCase()

◆ ~ExampleAsTestCase()

Member Function Documentation

◆ DoRun()

◆ GetCommandTemplate()

◆ GetPostProcessingCommand()

Member Data Documentation

◆ m_args

◆ m_dataDir

◆ m_program

◆ m_shouldNotErr