test.h File Reference

UCX Test Framework. More...

#include "ucx.h"
#include <stdio.h>
#include <string.h>
#include <setjmp.h>

Go to the source code of this file.

Data Structures
struct	UcxTestList
	Structure for the internal list of test cases. More...
struct	UcxTestSuite
	A test suite containing multiple test cases. More...

Macros
#define	__FUNCTION__   __func__
	Alias for the __func__ preprocessor macro. More...
#define	UCX_TEST(name)   void name(UcxTestSuite* _suite_,FILE *_output_)
	Macro for a UcxTest function header. More...
#define	UCX_TEST_BEGIN
	Marks the begin of a test. More...
#define	UCX_TEST_ASSERT(condition, message)
	Checks a test assertion. More...
#define	UCX_TEST_SUBROUTINE(name, ...)
	Macro for a test subroutine function header. More...
#define	UCX_TEST_CALL_SUBROUTINE(name, ...)   name(_suite_,_output_,_env_,__VA_ARGS__);
	Macro for calling a test subroutine. More...
#define	UCX_TEST_END   fwrite("success.\n", 1, 9, _output_); _suite_->success++;}
	Marks the end of a test. More...

Typedefs
typedef struct UcxTestSuite	UcxTestSuite
	Type for the UcxTestSuite. More...
typedef void(*	UcxTest) (UcxTestSuite *, FILE *)
	Pointer to a test function. More...
typedef struct UcxTestList	UcxTestList
	Type for the internal list of test cases. More...

Functions
UcxTestSuite *	ucx_test_suite_new ()
	Creates a new test suite. More...
void	ucx_test_suite_free (UcxTestSuite *suite)
	Destroys a test suite. More...
int	ucx_test_register (UcxTestSuite *suite, UcxTest test)
	Registers a test function with the specified test suite. More...
void	ucx_test_run (UcxTestSuite *suite, FILE *outstream)
	Runs a test suite and writes the test log to the specified stream. More...

Detailed Description

UCX Test Framework.

Usage of this test framework:

**** IN HEADER FILE: ****

UCX_TEST(function_name);
UCX_TEST_SUBROUTINE(subroutine_name, paramlist); // optional

**** IN SOURCE FILE: ****

UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
  // tests with UCX_TEST_ASSERT()
}

UCX_TEST(function_name) {
  // memory allocation and other stuff here
  UCX_TEST_BEGIN
  // tests with UCX_TEST_ASSERT() and/or
  // calls with UCX_TEST_CALL_SUBROUTINE() here
  UCX_TEST_END
  // cleanup of memory here
}

Note: if a test fails, a longjump is performed back to the UCX_TEST_BEGIN macro!

Attention: Do not call own functions within a test, that use UCX_TEST_ASSERT() macros and are not defined by using UCX_TEST_SUBROUTINE().

Author

Mike Becker

Olaf Wintermann

Macro Definition Documentation

__FUNCTION__

#define __FUNCTION__   __func__

Alias for the __func__ preprocessor macro.

Some compilers use __func__ and others use FUNCTION. We use FUNCTION so we define it for those compilers which use __func__.

UCX_TEST

#define UCX_TEST

(

name

)

void name(UcxTestSuite* _suite_,FILE *_output_)

Macro for a UcxTest function header.

Use this macro to declare and/or define a UcxTest function.

Parameters

name	the name of the test function

UCX_TEST_ASSERT

#define UCX_TEST_ASSERT	(		condition,
			message
	)

Value:

if (!(condition)) { \
        fwrite(message".\n", 1, 2+strlen(message), _output_); \
        _suite_->failure++; \
        longjmp(_env_, 1);\
    }

Checks a test assertion.

If the assertion is correct, the test carries on. If the assertion is not correct, the specified message (terminated by a dot and a line break) is written to the test suites output stream.

Parameters

condition	the condition to check
message	the message that shall be printed out on failure

UCX_TEST_BEGIN

#define UCX_TEST_BEGIN

Value:

fwrite("Running ", 1, 8, _output_);\
        fwrite(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\
        fwrite("... ", 1, 4, _output_);\
        jmp_buf _env_; \
        if (!setjmp(_env_)) {

Marks the begin of a test.

Note: Any UCX_TEST_ASSERT() calls must be performed after UCX_TEST_BEGIN.

See also

UCX_TEST_END

UCX_TEST_CALL_SUBROUTINE

#define UCX_TEST_CALL_SUBROUTINE	(		name,
			...
	)		name(_suite_,_output_,_env_,__VA_ARGS__);

Macro for calling a test subroutine.

Subroutines declared with UCX_TEST_SUBROUTINE() can be called by using this macro.

Note: You may only call subroutines within a UCX_TEST_BEGIN- UCX_TEST_END-block.

Parameters

name	the name of the subroutine
...	the argument list

See also

UCX_TEST_SUBROUTINE()

UCX_TEST_END

#define UCX_TEST_END   fwrite("success.\n", 1, 9, _output_); _suite_->success++;}

Marks the end of a test.

Note: Any UCX_TEST_ASSERT() calls must be performed before UCX_TEST_END.

See also

UCX_TEST_BEGIN

UCX_TEST_SUBROUTINE

#define UCX_TEST_SUBROUTINE	(		name,
			...
	)

Value:

void name(UcxTestSuite* _suite_,\
        FILE *_output_, jmp_buf _env_, __VA_ARGS__)

Macro for a test subroutine function header.

Use this to declare and/or define a subroutine that can be called by using UCX_TEST_CALL_SUBROUTINE().

Parameters

name	the name of the subroutine
...	the parameter list

See also

UCX_TEST_CALL_SUBROUTINE()

Typedef Documentation

UcxTest

typedef void(* UcxTest) (UcxTestSuite *, FILE *)

Pointer to a test function.

UcxTestList

typedef struct UcxTestList UcxTestList

Type for the internal list of test cases.

UcxTestSuite

typedef struct UcxTestSuite UcxTestSuite

Type for the UcxTestSuite.

Function Documentation

ucx_test_register()

int ucx_test_register	(	UcxTestSuite *	suite,
		UcxTest	test
	)

Registers a test function with the specified test suite.

Parameters

suite	the suite, the test function shall be added to
test	the test function to register

Returns

EXIT_SUCCESS on success or EXIT_FAILURE on failure

ucx_test_run()

void ucx_test_run	(	UcxTestSuite *	suite,
		FILE *	outstream
	)

Runs a test suite and writes the test log to the specified stream.

Parameters

suite	the test suite to run
outstream	the stream the log shall be written to

ucx_test_suite_free()

void ucx_test_suite_free

(

UcxTestSuite *

suite

)

Destroys a test suite.

Parameters

suite

the test suite to destroy

ucx_test_suite_new()

UcxTestSuite* ucx_test_suite_new

(

)

Creates a new test suite.

Returns

a new test suite