test
["Little Useful Bits" Library]

This utiltiy provides a simple unittest facility. More...

Enumerations
enum	lub_test_status_t { LUB_TEST_PASS, LUB_TEST_FAIL }
enum	lub_test_verbosity_t { LUB_TEST_TERSE = 0, LUB_TEST_NORMAL, LUB_TEST_VERBOSE }
Functions
void	lub_test_parse_command_line (int argc, const char *const *argv)
void	lub_test_begin (const char *fmt,...)
void	lub_test_log (lub_test_verbosity_t level, const char *fmt,...)
lub_test_status_t	lub_test_get_status (void)
int	lub_test_failure_count (void)
void	lub_test_end (void)
void	lub_test_stop_here (void)
void	lub_test_seq_begin (int seq, const char *fmt,...)
void	lub_test_seq_log (lub_test_verbosity_t level, const char *fmt,...)
void	lub_test_seq_end (void)
lub_test_status_t	lub_test_check (bool_t expr, const char *fmt,...)
lub_test_status_t	lub_test_check_int (int expect, int actual, const char *fmt,...)
lub_test_status_t	lag_test_test_float (double min, double max, double actual, const char *fmt,...)

---

Detailed Description

This utiltiy provides a simple unittest facility.

Unit Testing Philosophy

The tests are used during development as a means of exercising and debugging the new code, and once developed serve as a means of regression-testing to ensure that changes or additions have not introduced defects. Unit testing in this manner offers many benefits:

• Well designed unit tests allow for more complete exercise & test coverage of new code.

• They do not require product hardware or even a product simulator; they are compact, standalone executables.

• It is easy to instrument the unit tests with commercial tools such as Purify/PureCoverage.

• Use as regression tests increases code maintainability.

• They can be run during builds as ``sanity-checks'' that components are functional.

What is the unit test interface?

The Unit Test Interface provide a set of basic capabilities that all unit tests need, and which are trivially easy to incorporate into a test. They make it easy to do things such as:

• Log output to the screen and/or to a logfile

• Test values of various types and record the results

• Provide well-formatted, concise output with controllable verbosity

• Track test status.

• Have a consistent set of command-line options for controlling the unit test behavior. (see unitTestCL() below)

Verbosity

Depending on the length of a test, why it is being run, and the stage of development, it is desirable to have different levels of detail output. The Unit Test Utilities provide three levels of detail:

• Terse output is the minimal set. Only test failures, serious errors, and final results are logged.

• Normal output is the default. All test results, sequence headers, etc. are logged.

• Verbose output includes all output messages. This level is not used by the Utilities themselves but is useful for providing additional, detailed messages within unit tests.

Most Utility functions handle verbosity issues automatically; for example, Tests automatically log failures as ``terse'' and pass results as ``normal''. The only time a user needs to specify verbosity is with Log messages.

All output has an associated Verbosity level, and will only be output if the current Verbosity setting is equal to or greater than that level.

Sequences

Simple numbering of tests is adequate only for very small unit tests. More commonly, there are groups of related tests covering a particular function or set of functionality. This gives rise to the concept of Sequences. A Sequence assigns a name and number to a group of tests; within the sequence, tests are numbered automatically. While their use is not strictly required, the use of Sequences is encouraged as a means of organizing test output for easy understanding.

Sequences are begun with a function call specifying their sequence number and a printf-style format specification of their name. This outputs a sequence header (at 'normal' verbosity) and resets the test counter. Another call ends the sequence.

Tests

Tests are the heart of the unit test. Every test has a pass/fail result, which is returned as well as affecting the overall pass/fail status of the unit test. Every test also accepts a ``name'' argument (in printf style), and generates appropriate log output. Although null strings are accepted as names, naming each test is encouraged as it makes the output much more readable.

At the Terse verbosity level, only failing tests generate log output.

Test functions are provided for testing:

• Expressions: the expression's true/false value is evaluated. This is the most basic test, similar to an assert(). Virtually anything can be tested using this, but the log output is minimal; only a Pass/Fail result and the test name are logged.

• Integer Comparison: the test function is passed an expected and actual value. The test passes if the values are the same. The log includes Pass/Fail, expected & actual values, and the test name; because the values appear in the log, failures may be more easily investigated.

• Float Comparison: the test function is passed minimum, maximum, and actual values. The test passes if the actual value is less than or equal to maximum, and greater than or equal to minimum. Like the integer comparison, the min, max, and actual values are all logged in addition to the Pass/Fail result and test name.

The overall unit test pass/fail result can be requested at any time via a function call.

Logging

Three different logging functions are provided. All are similar but each is appropriate for different purposes. Each function takes as its first argument a verbosity level, specifying the minimum verbosity at which the message should be logged. Each also takes a printf-style specification of format and arguments, which is used to generate the output. In this way anything can be output: strings, variables, formatted floats, whatever the unit test needs to record.

Note that it is not required to use any logging function; the Utilities will generate a reasonable log based on the sequence and test calls. However, additional logging may add significant value and human readability to the test results.

Author:

Graeme McKerrell

Brett B. Bonner

Date:

Created On Thu Feb 28 11:25:44 2002

Last Revised 03-Oct-2002 (BBB)

Version:

UNTESTED

---

Enumeration Type Documentation

enum lub_test_status_t

Status codes

Enumerator:

LUB_TEST_PASS	Indicates a test has passed
LUB_TEST_FAIL	Indicates a test has failed

enum lub_test_verbosity_t

Message priority/verbosity levels

Enumerator:

LUB_TEST_TERSE	Only output test failures, errors and final result
LUB_TEST_NORMAL	Output all test results, sequence headers, errors and results
LUB_TEST_VERBOSE	Output everything

---

Function Documentation

lub_test_status_t lag_test_test_float	(	double	min,
		double	max,
		double	actual,
		const char *	fmt,
			...
	)

This function is designed to ensure that a floating point value is within acceptible limits. It takes a minimum, maximum and actual value. The test passes if the actual value is greater or equal than the minimum, and less than or equal to the maximum. All three values are recorded in the log output.

Precondition:

• lub_test_begin() must have been called

Returns:

A status code (LUB_TEST_PASS/LUB_TEST_FAIL)

Postcondition:

• The formatted scenario and result is reported in the logfile and/or stdout.
• The test count is incremented by one.
• If the tests fails then the overall unit-test status is changed to LUB_TEST_FAIL
• If lub_test_begin() has not been called the behaviour is undefined

Parameters:

min	the minimum acceptible value
max	the maximum acceptible value
actual	the actual value
fmt	a printf style format string to specify the test scenario

void lub_test_begin	(	const char *	fmt,
			...
	)

This starts and specifies the name for the unit-test.

Precondition:

• lub_test_CL() must have been called.

Returns:

none

Postcondition:

• The begining of the test is reported in the logfile and/or stdout
• The overall pass/fail status is reset.

Parameters:

fmt	a printf style format string to specify the name of the test

lub_test_status_t lub_test_check	(	bool_t	expr,
		const char *	fmt,
			...
	)

The most basic test function, this simply evaluates an expression for BOOL_TRUE/BOOL_FALSE and passes/fails as a result. Like all test functions it accepts a printf-style format and parameters to describe the test.

Precondition:

• lub_test_begin() must have been called

Returns:

A status code (LUB_TEST_PASS/LUB_TEST_FAIL)

Postcondition:

• The formatted scenario and result is reported in the logfile and/or stdout.
• The test count is incremented by one.
• If the tests fails then the overall unit-test status is changed to LUB_TEST_FAIL
• If lub_test_begin() has not been called the behaviour is undefined

Parameters:

expr	a boolean expression to evaluate
fmt	a printf style format string to specify the test scenario

lub_test_status_t lub_test_check_int	(	int	expect,
		int	actual,
		const char *	fmt,
			...
	)

This function is almost identical to test() except it accepts an exepcted and actual value to compares them. Equal values cause the test to pass, unequal cause the test to fail. Both values are recorded in the log output making it easier to understand failures.

Precondition:

• lub_test_begin() must have been called

Returns:

A status code (LUB_TEST_PASS/LUB_TEST_FAIL)

Postcondition:

• The formatted scenario and result is reported in the logfile and/or stdout.
• The test count is incremented by one.
• If the tests fails then the overall unit-test status is changed to LUB_TEST_FAIL
• If lub_test_begin() has not been called the behaviour is undefined

Parameters:

expect	the expected integer value
actual	the actual integer value
fmt	a printf style format string to specify the test scenario

void lub_test_end

(

void

)

This function ends the unit-test and closes the log file.

Precondition:

• lub_test_begin() must have been called.
• lub_test_end() must not have been called.

Returns:

none

Postcondition:

• The overall pass/fail status is reported to the log file and/or stdout.
• The log file is closed.
• If lub_test_begin() has not been called then behaviour is undefined
• If lub_test_end() has been called the behaviour is undefined

int lub_test_failure_count

(

void

)

The test utilities maintain internal counts for all the tests that have been performed since the unittest_begin() call. This function lets a client get the number of failures so far.

Precondition:

• lub_test_begin() must have been called.
• lub_test_end() must not have been called.

Returns:

The current number of failed tests.

Postcondition:

• If lub_test_begin() has not been called then behaviour is undefined
• If lub_test_end() has been called the behaviour is undefined

lub_test_status_t lub_test_get_status

(

void

)

This function provide the current overall status for the unit-test. If any tests have failed then the unit-test is deemed to have failed.

Precondition:

• lub_test_begin() must have been called.
• lub_test_end() must not have been called.

Returns:

The current overall status. (TESTPASS/TESTFAIL)

Postcondition:

• If lub_test_begin() has not been called then behaviour is undefined
• If lub_test_end() has been called the behaviour is undefined

void lub_test_log	(	lub_test_verbosity_t	level,
		const char *	fmt,
			...
	)

This is the most generic of the logging functions. No addition formating is performed.

Precondition:

• lub_test_begin() must have been called.
• lub_test_end() must not have been called.

Returns:

none

Postcondition:

• If the specified verbosity is higher than that specified on the command line then the message will not be logged to the logfile and/or stdout.
• If lub_test_begin() has not been called then behaviour is undefined

Parameters:

level	the verbosity level for this message
fmt	a printf style format string to specify the message to log

void lub_test_parse_command_line	(	int	argc,
		const char *const *	argv
	)

This function is responsible for parsing all the command line options, setting run time variables, and opening a log file if necessary.

Supported Command Line Switches:

Set the Verbosity level

• -terse
• -normal (default)
• -verbose

Set behaviour upon failure

• -stoponfail
• -continueonfail (default)

Logging:

Enable and disable logging to stdout

• -stdout (default)
• -nostdout

Log to file named FILENAME (if no filename is specified "test.log" is used), or disable logging to a file

• -logfile [FILENAME] (default)
• -nologfile

Prints usage message and exit -usage -help

Precondition:

Must be the first unitTest function called.

Returns:

none

Postcondition:

If there are conflicting command line options it will exit(1)

If the log file cannot be opened it will exit(1)

Parameters:

argc	The number of command line arguments
argv	An array of command line arguments

void lub_test_seq_begin	(	int	seq,
		const char *	fmt,
			...
	)

This function starts a new test sequence.

Precondition:

• lub_test_begin() must have been called.
• lub_test_end() must not have been called.

Returns:

none

Postcondition:

• The test count is reset to zero.
• The current sequence number and description is updated.
• The begining of the sequence is reported in the logfile and/or stdout.
• If lub_test_begin() has not been called the behaviour is undefined
• If lub_test_end() has been called the behaviour is undefined

Parameters:

seq	a user specified sequence number
fmt	a printf style format string to specify the sequence name

void lub_test_seq_end

(

void

)

This function marks the end of the current sequence.

Precondition:

• lub_test_seq_begin() must have been called.

Returns:

none

Postcondition:

• An end of sequence message is reported to the log file and/or stdout.
• The current sequence number and description remains unchanged until the next call to unittest_seq_begin()
• If lub_test_seq_begin() has not been called then behaviour is undefined

void lub_test_seq_log	(	lub_test_verbosity_t	level,
		const char *	fmt,
			...
	)

This is a good general purpose logging function. It parameters are the same as unittest_log, but this will log the provided information with the current sequence number, properly indented to provide nicely formatted output within a test.

Precondition:

• lub_test_seq_begin() must have been called.

Returns:

none

Postcondition:

• The formatted message is reported in the logfile and/or stdout.
• If lub_test_seq_begin() has not been called the behaviour is undefined

Parameters:

level	The verbosity level of the message
fmt	a printf style format string to specify the message

void lub_test_stop_here

(

void

)

This function is provided as a DEBUG aid. A breakpoint set on this function will be reached everytime a test fails, with the failure case in context.

Precondition:

none

Returns:

none

Postcondition:

none

---