Macros to test assertions, flag failures, and log events. More...

Macros
#define	MU_ASSERT(expr)
	Confirm truth of predicate or fail. More...

#define	MU_ASSERT_EQUAL(type, expr1, expr2)
	Confirm equality of values or fail. More...

#define	MU_ASSERT_NOT_EQUAL(type, expr1, expr2)
	Confirm inequality of values or fail. More...

#define	MU_ASSERT_NOT_REACHED()
	Fail due to unexpected code path. More...

#define	MU_SUCCESS()
	Succeed immediately. More...

#define	MU_FAILURE(format,...)
	Fail immediately. More...

#define	MU_SKIP(format,...)
	Skip test. More...

#define	MU_EXPECT(result)
	Specify expected result. More...

#define	MU_TIMEOUT(ms)
	Set or reset time allowance. More...

#define	MU_ITERATE(count)
	Specify number of iterations for current test. More...

#define	MU_LOG(level,...)
	Log non-fatal message. More...

#define	MU_WARNING(...)
	Log a warning. More...

#define	MU_INFO(...)
	Log an informational message. More...

#define	MU_VERBOSE(...)
	Log a verbose message. More...

#define	MU_DEBUG(...)
	Log a debug message. More...

#define	MU_TRACE(...)
	Log a trace message. More...

Detailed Description

This module contains macros for use in the body of unit tests to make assertions, raise errors, report unexpected results, and log arbitrary messages.

Macro Definition Documentation

#define MU_ASSERT ( expr )

This macro asserts that an arbitrary boolean expression is true. If the assertion succeeds, execution of the current test will continue as usual. If it fails, the test will immediately fail and be terminated; the expression, filename, and line number will be reported as part of the cause of failure.

Example:

MU_ASSERT(foo != NULL && bar > baz);

Parameters

expr	the expression to test

#define MU_ASSERT_EQUAL	(	type,
		expr1,
		expr2
	)

This macro asserts that the values of two expressions are equal. If the assertion succeeds, execution of the current test will continue as usual. If it fails, the test will immediately fail and be terminated; the expressions, their values, and the source filename and line number will be reported as part of the cause of failure.

The type of the two expressions must be specified as the first argument of this macro. The expressions must have the same type. The following are legal values of the type argument:

MU_TYPE_INTEGER
MU_TYPE_FLOAT
MU_TYPE_STRING
MU_TYPE_POINTER
MU_TYPE_BOOLEAN

Example:

MU_ASSERT_EQUAL(MU_TYPE_INTEGER, 2 * 2, 2 + 2);

Parameters

type	the type of the two expressions
expr1	the first expression
expr2	the second expression

#define MU_ASSERT_NOT_EQUAL	(	type,
		expr1,
		expr2
	)

This macro asserts that the values of two expressions are not equal. If the assertion succeeds, execution of the current test will continue as usual. If it fails, the test will immediately fail and be terminated; the expressions, their values, and the source filename and line number will be reported as part of the cause of failure.

The type of the two expressions must be specified as the first argument of this macro. The expressions must have the same type. The following are legal values of the type argument:

MU_TYPE_INTEGER
MU_TYPE_FLOAT
MU_TYPE_STRING
MU_TYPE_POINTER
MU_TYPE_BOOLEAN

Example:

MU_ASSERT_NOT_EQUAL(MU_TYPE_INTEGER, 2 + 2, 5);

Parameters

type	the type of the two expressions
expr1	the first expression
expr2	the second expression

#define MU_ASSERT_NOT_REACHED ( )

This macro always causes immediate failure of the current test when executed; it is meant to denote an area of code that should not be reached under correct behavior.

Example:

MU_ASSERT_NOT_REACHED;

#define MU_DEBUG ( ... )

Equivalent to MU_LOG(MU_LEVEL_DEBUG, ...)

#define MU_EXPECT ( result )

Use of this macro indicates the expected result of the current test. By default, all tests are expected to succeed (MU_STATUS_SUCCESS). However, some tests are most naturally written in a way such that they normally fail, such as by throwing an uncaught exception. In these cases, MU_EXPECT may be used to indicate the expected test status before proceeding. If the indicated status is not MU_STATUS_SUCCESS, test results will be classified as follows:

If the test result is the same as that given to MU_EXPECT, it will be classified as an expected failure
If the test result is different from that given to MU_EXPECT but is not MU_STATUS_SUCCESS, it will be classified as a failure
If the test result is MU_STATUS_SUCCESS, it will be classified as an unexpected success

Example:

MU_EXPECT(MU_STATUS_EXCEPTION);

Parameters

result the expected MuTestStatus value

#define MU_FAILURE	(	format,
		...
	)

Use of this macro will cause the current test to terminate and fail immediately. This macro takes a printf format string and an arbitrary number of trailing arguments; the expansion of this string will become the explanation reported for the test failing.

Example:

MU_FAILURE("String '%s' does not contain an equal number of a's and b's",

the_string);

Parameters

format a printf format string for the failure message

#define MU_INFO ( ... )

Equivalent to MU_LOG(MU_LEVEL_INFO, ...)

#define MU_ITERATE ( count )

Use of this macro specifies the number of times the current test should be run. Tests that might demonstrate non-deterministic or external state-dependent behavior may benefit from being run multiple times to decrease the likelihood of race conditions and other Heisenbugs going unnoticed.

The test will be run either the specified number of times or until it fails or requests to be skipped. The overall result of the test will be that of the last run. Logged events will be recorded from all runs.

Example:

// This test should be run 100 times

MU_ITERATE(100);

Parameters

count the number of iterations

#define MU_LOG	(	level,
		...
	)

It is sometimes desirable for a unit test to be able to report information which is orthogonal to the actual test result. This macro will log a message in the test results without causing the current test to succeed or fail.

MU_LOG supports 4 different logging levels of decreasing severity and increasing verbosity:

MU_LEVEL_WARNING - indicates a worrisome but non-fatal condition
MU_LEVEL_INFO - indicates an important informational message
MU_LEVEL_VERBOSE - indicates information that is usually extraneous but sometimes relevant
MU_LEVEL_TRACE - indicates a message designed to help trace the execution of a test

Example:

MU_LOG(MU_LEVEL_TRACE, "About to call foo()");

MU_ASSERT(foo() != NULL);

Parameters

level	the logging level
...	a printf-style format string and trailing arguments for the message to log

#define MU_SKIP	(	format,
		...
	)

Use of this macro will cause the current test to terminate immediately and be reported as skipped. Skipped tests are not counted as failures but are reported differently from successful tests. This macro takes a printf format string and an arbitrary number of trailing arguments; the expansion of this string will serve as an explanation for the test being skipped.

Example:

MU_SKIP("This test is not applicable to the current system");

Parameters

format a printf format string for the explanation message

#define MU_SUCCESS ( )

Use of this macro will cause the current test to terminate and succeed immediately.

Example:

MU_SUCCESS;

#define MU_TIMEOUT ( ms )

Use of this macro sets the time allowance for the current test. If the time allowance is exceeded before the test completes, the test will be forcefully terminated and reported as timing out. Time is counted down starting from the last use of MU_TIMEOUT.

Example:

// This test should complete in at most 5 seconds

MU_TIMEOUT(5000);

Parameters

ms	the time allowance in milliseconds

#define MU_TRACE ( ... )

Equivalent to MU_LOG(MU_LEVEL_TRACE, ...)

#define MU_VERBOSE ( ... )

Equivalent to MU_LOG(MU_LEVEL_VERBOSE, ...)

#define MU_WARNING ( ... )

Equivalent to MU_LOG(MU_LEVEL_WARNING, ...)