AceUnit.h File Reference

AceUnit header file. More...

#include "AceUnitAnnotations.h"
#include <setjmp.h>
#include "AceUnitAssert.h"
#include "AceUnitData.h"

Go to the source code of this file.

Data Structures

struct  AssertionId_t
 AssertionId_t specifies an assertion failure within a test case. More...
struct  AssertionError_t
 Assertion Error. More...
struct  TestSuite_t
 A Suite is a loose collection of test cases. More...
struct  TestFixture_t
 A Fixture is a collection of test cases sharing the same before, after, beforeClass and afterClass methods. More...

Defines

#define ACEUNIT_H   1
 Include shield to protect the header file from being included more than once.
#define ACEUNIT_C_MODE   ACEUNIT_C_MODE_C89
#define ACEUNIT_C_MODE_C99_INCLUDES   1
 Value for ACEUNIT_C_MODE for including C99 standard header files.
#define ACEUNIT_C_MODE_C89   2
 Value for ACEUNIT_C_MODE for using AceUnit's own replacement definitions.
#define ACEUNIT_C_MODE_PROPRIETARY   3
 Value for ACEUNIT_C_MODE for providing proprietary replacement definitions by the user.
#define bool   int
 Replacement for stdbool.h bool in case stdbool.h is not available.
#define true   1
 Replacement for stdbool.h true in case stdbool.h is not available.
#define false   0
 Replacement for stdbool.h false in case stdbool.h is not available.
#define __bool_true_false_are_defined   1
 Replacement for stdbool.h __bool_true_false_are_defined in case stdbool.h is not available.
#define NULL   ((void *) 0)
 Replacement for stddef.h NULL in case stddef.h is not available.
#define ACEUNIT_ASSERTION_STYLE_RETURN   1
 Value for ACEUNIT_ASSERTION_STYLE for using return for assertions to abort test cases.
#define ACEUNIT_ASSERTION_STYLE_ASSERT   2
 Value for ACEUNIT_ASSERTION_STYLE for using assert for assertions to abort test cases.
#define ACEUNIT_ASSERTION_STYLE_ABORT   3
 Value for ACEUNIT_ASSERTION_STYLE for using abort() for assertions to abort.
#define ACEUNIT_ASSERTION_STYLE_LONGJMP   4
 Value for ACEUNIT_ASSERTION_STYLE for using longjmp() for assertions to abort.
#define ACEUNIT_ASSERTION_STYLE_CUSTOM   5
 Value for ACEUNIT_ASSERTION_STYLE for using custom assertion aborts.
#define ACEUNIT_ASSERTION_STYLE   ACEUNIT_ASSERTION_STYLE_LONGJMP
 Determines the style of assertions to use.
#define ACEUNIT_ABORT   longjmp(runnerData->jmpBuf, 1)
 Code for aborting a test case in case of an assertion.
#define NO_TEST   ((AceTestId_t) 0)
 Special value for AceTestId_t that specifies no test.
#define ALL_TESTS   ((AceTestId_t) -1)
 Special value for AceTestId_t that specifies all tests.
#define TestCaseId_NULL   0
 The value for something of type TestCaseId_t for denoting no testcase.
#define newAssertionError(message)   { AssertionId_t assertion = { __LINE__, message }; recordError(A_FIXTURE_ID, assertion); } ACEUNIT_ABORT
 Creates a new assertion error.

Typedefs

typedef signed char int8_t
 Replacement for stdint.h int8_t in case stdint.h is not available.
typedef signed short int int16_t
 Replacement for stdint.h int16_t in case stdint.h is not available.
typedef signed long int int32_t
 Replacement for stdint.h int32_t in case stdint.h is not available.
typedef unsigned char uint8_t
 Replacement for stdint.h uint8_t in case stdint.h is not available.
typedef unsigned
short int 		uint16_t
 Replacement for stdint.h uint16_t in case stdint.h is not available.
typedef unsigned long int uint32_t
 Replacement for stdint.h uint32_t in case stdint.h is not available.
typedef long unsigned int size_t
 Replacement for stddef.h size_t in case stddef.h is not available.
typedef uint16_t AceTestId_t
 TestId_t specifies a test.
typedef uint16_t AceGroupId_t
 GroupId_t specifies a group.
typedef AceTestId_t SuiteId_t
 SuiteId_t specifies a test suite.
typedef SuiteId_t FixtureId_t
 FixtureId_t specifies a test fixture.
typedef AceTestId_t TestCaseId_t
 TestCaseId_t specifies a test case.
typedef int linenumber_t
 The type to use for line numbers.
typedef void(* testMethod_t )(void)
 Method signature for annotated test methods.

Functions

void recordError (const FixtureId_t fixtureId, const AssertionId_t assertionId)
 Records an error.
void runFixture (const TestFixture_t *const fixture, AceGroupId_t group)
 Runs all test cases from a test fixture.
void runSuite (const TestSuite_t *const suite, AceGroupId_t group)
 Runs all test cases from a test suite.

Detailed Description

AceUnit header file.

You do not need to include this header file in a fixture. The generated header file for your fixture will automatically include it.

The following options are supported:

ACEUNIT_EMBEDDED
Define this macro if you want to use AceUnit in embedded mode. Using AceUnit in embedded mode will use test element ids that are uint16_t instead of char*. Memory consumption in embedded mode is significantly reduced. Some non-vital features are not available in embedded mode. TODO: describe which features are not available in embedded mode.
ACEUNIT_C_MODE
Set this macro to explicitely specify how AceUnit shall interact with the compiler environment regarding header files. The following options are possible:
ACEUNIT_C_MODE_C99_INCLUDES (default in a C99 environment)
This tells AceUnit to include files like <stdint.h> and <stddef.h> to define required symbols like uint16_t or NULL.
ACEUNIT_C_MODE_C89 (default in a C89 environment)
This tells AceUnit that neither C99 include files nor replacement definitions are available, so AceUnit shall use its own definitions.<7dd>
ACEUNIT_C_MODE_PROPRIETARY
This tells AceUnit to assume that the required definitions for symbols like uint16_t or NULL are provided by header files already included by the user before the AceUnit header files.
If you use non-C99 compilers, you should bug your compiler vendor to produce an ISO/IEC 9899/1999 (aka ISO C99) compiler. As you can correctly guess from this description or have read elsewhere, AceUnit works without problems on C89 compilers. But it's a shame that even today, about a decade after the release of C99, still only a small minority of compilers actually properly support that standard.

Note: this replaces ACEUNIT_INTERNAL_ISO_TYPES and ACEUNIT_SKIP_ISO_DEFINES from previous versions of AceUnit.

Note: If you do not set this macro, AceUnit will make the decision itself. The default is to assume ACEUNIT_C_MODE_C99_INCLUDES for a C99 environment, ACEUNIT_C_MODE_C89 otherwise.

ACEUNIT_STATIC_ANNOTATIONS
Define this macro to make AceUnit annotations (A_Test, A_Before, A_After, A_BeforeClass, A_AfterClass, A_Ignore) behave like the static keyword. That way you have easy and flexible control whether or not test methods are static.

Declaring test methods as static has a significant advantage. You will be able to use the same name in different fixtures and still build and run them all together. For logging, it is not required that test methods have unique names. Logging will always also include the associated fixture (e.g. filename + line number). So you will always uniquely identify which test case filed, even if the names of the test cases are not unique.

However, there are debuggers which will cause head ache if you try to debug functions which are static. Some tool chains (compilers / linkers) will not emit proper debug information for functions which are static.

The pros and cons for static test methods are both very significant. Whether or not you want to use static depends on your environment. Because of that, we've left the choice to you.

But we've prepared everything for you. Toggling between these two options is as simple as (not) defining this macro. Of course, toggling static off will only be that simple in the real world if the test method names are unique across all fixtures that you link together.

If you're unsure, a rule of thumb is define either ACEUNIT_EMBEDDED or ACEUNIT_STATIC_ANNOTATIONS but not both.

ACEUNIT_CODE_INCLUDE
Include this header file before AceUnit Code (only applies to framework, not to test cases / generated code). Use this if you need to specify section information for your compiler e.g. in an embedded environment.

Of course you could just modify the AceUnit source code to include the section information. But it is not recommended to modify the AceUnit source code because it will cause extra work for you if you want to upgrade to a newer version of AceUnit. Therefore we tried to design AceUnit in a way that you shouldn't need to modify AceUnit's source code to get AceUnit running in your environment.

ACEUNIT_DATA_INCLUDE
Include this header file before AceUnit Data (only applies to framework, not to test cases / generated code). Use this if you need to specify section information for your compiler e.g. in an embedded environment.

Of course you could just modify the AceUnit source code to include the section information. But it is not recommended to modify the AceUnit source code because it will cause extra work for you if you want to upgrade to a newer version of AceUnit. Therefore we tried to design AceUnit in a way that you shouldn't need to modify AceUnit's source code to get AceUnit running in your environment.

ACEUNIT_DATA_ON_STACK
Define this macro to use AceUnit Data on the Stack. You will then have to initialize runnerData yourself. AceUnit doesn't automatically put it on the stack itself because you might want to access the results from where you invoked the runner.
ACEUNIT_SUITES
Define this macro to use AceUnit with support for Suites.
ACEUNIT_PRE_BEFORECLASS
If you want AceUnit to execute code before every beforeclass method, define this macro with that code.
ACEUNIT_POST_BEFORECLASS
If you want AceUnit to execute code after every beforeclass method, define this macro with that code.
ACEUNIT_PRE_BEFORE
If you want AceUnit to execute code before every before method, define this macro with that code.
ACEUNIT_POST_BEFORE
If you want AceUnit to execute code after every before method, define this macro with that code.
ACEUNIT_PRE_TEST
If you want AceUnit to execute code before every test method, define this macro with that code.
ACEUNIT_POST_TEST
If you want AceUnit to execute code after every test method, define this macro with that code.
ACEUNIT_PRE_AFTER
If you want AceUnit to execute code before every after method, define this macro with that code.
ACEUNIT_POST_AFTER
If you want AceUnit to execute code after every after method, define this macro with that code.
ACEUNIT_PRE_AFTERCLASS
If you want AceUnit to execute code before every afterclass method, define this macro with that code.
ACEUNIT_POST_AFTERCLASS
If you want AceUnit to execute code after every afterclass method, define this macro with that code.
ACEUNIT_RUNNERDATA_EXTENSION
If you want to add additional data to the data available to the runner, define this macro. The macro should expand to valid fields in a structure. These fields will be inserted at the end of AceUnitRunnerData_t.
ACEUNIT_CONFIG_FILE
If you want to configure AceUnit more comfortably than with defines passed via make to your compiler, you can define this macro. The macro then must evaluate to a valid include file.
ACEUNIT_SETJMP_INCLUDE
If you want AceUnit to use setjmp / longjmp but want it to include a different file than <setjmp.h>, define this macro. The macro then must evaluate to a valid include file.
ACEUNIT_SKIP_SETJMP_INCLUDE
If you want AceUnit to use setjmp / longjmp but do not want AceUnit to automatically include any file for it, define this macro.
ACEUNIT_LOOP
This feature enables A_Loop annotation support. A_Loop support is independent of the generator. You may turn A_Loop support on and off during compile time without having to rerun the generator.
ACEUNIT_EXPLICIT_MESSAGES
This feature enables explicit message support. That means assertions which have an expected and an actual value will report those values. For this feature to work, a message buffer which can be used by snprintf is required. Currently, only snprintf is supported. sprintf and _snprintf are not yet supported.
ACEUNIT_EXPLICIT_MESSAGES_INLINE_BUFFER
This means that the structure AceUnitRunnerData_t directly contains the buffer for message formatting. Otherwise the structure only contains a pointer which has to be initialized by the user.

Warning:
AceUnit can define types for itself for exotic compilation environments where standard includes are not available or shall not be used. But though AceUnit can do that, this is strongly deprecated. This will certainly cause a lot of problems:
Author:
Christian Hujer

Define Documentation

#define __bool_true_false_are_defined   1

Replacement for stdbool.h __bool_true_false_are_defined in case stdbool.h is not available.

#define ACEUNIT_ABORT   longjmp(runnerData->jmpBuf, 1)

Code for aborting a test case in case of an assertion.

#define ACEUNIT_ASSERTION_STYLE   ACEUNIT_ASSERTION_STYLE_LONGJMP

Determines the style of assertions to use.

Defaults to ACEUNIT_ASSERTION_STYLE_CUSTOM if ACEUNIT_CUSTOM_ASSERT is defined. Defaults to ACEUNIT_ASSERTION_STYLE_LONGJMP otherwise.

See also:
ACEUNIT_ASSERTION_STYLE_RETURN

ACEUNIT_ASSERTION_STYLE_ASSERT

ACEUNIT_ASSERTION_STYLE_ABORT

ACEUNIT_ASSERTION_STYLE_LONGJMP

ACEUNIT_ASSERTION_STYLE_CUSTOM

#define ACEUNIT_ASSERTION_STYLE_ABORT   3

Value for ACEUNIT_ASSERTION_STYLE for using abort() for assertions to abort.

It will use stdlib.h from ISO C.

Note:
If you use this assertion style, the first assertion will invoke abort() and therefore exit the test program. Normal logging is useless in conjunction with this assertion style.
Todo:
instead of exiting, optionally catch SIGABRT with a signal handler
See also:
ACEUNIT_ASSERTION_STYLE

#define ACEUNIT_ASSERTION_STYLE_ASSERT   2

Value for ACEUNIT_ASSERTION_STYLE for using assert for assertions to abort test cases.

It will use assert.h from ISO C. Because of that do not define NDEBUG.

Warning:
If you define NDEBUG with this assertion style, assertions will not work as expected. The test case will not be aborted. If another assertion occurs it will overwrite the previous assertion even before the assertion is logged. Therefore you MUST NOT define NDEBUG with this assertion style.
Note:
If you use this assertion style, the first assertion will invoke assert() and therefore exit the test program. Normal logging is useless in conjunction with this assertion style. This assertion style is especially useful for debugging when assert() is useful in your debugging environment.
Todo:
instead of exiting, optionally catch SIGABRT with a signal handler
See also:
ACEUNIT_ASSERTION_STYLE

#define ACEUNIT_ASSERTION_STYLE_CUSTOM   5

Value for ACEUNIT_ASSERTION_STYLE for using custom assertion aborts.

If you use this for ACEUNIT_ASSERTION_STYLE, you also MUST define the macro ACEUNIT_CUSTOM_ASSERT to the code you want to use to make assertions abort test cases.

See also:
ACEUNIT_ASSERTION_STYLE

#define ACEUNIT_ASSERTION_STYLE_LONGJMP   4

Value for ACEUNIT_ASSERTION_STYLE for using longjmp() for assertions to abort.

It will use setjmp.h from ISO C.

This is the preferred assertion style and therefore default for AceUnit.

See also:
ACEUNIT_ASSERTION_STYLE

#define ACEUNIT_ASSERTION_STYLE_RETURN   1

Value for ACEUNIT_ASSERTION_STYLE for using return for assertions to abort test cases.

This is primarily meant for embedded systems where everything should be as small and simple as possible. It is also currently used by AceUnit when AceUnit tests itself.

Warning:
This assertion style has a severe disadvantage. Assertions in this style will only work as expected if the assertion appears directly in the test case. If an assertion is placed in a function invoked from a test case, the assertion error will be stored. But the test case will not be aborted. If another assertion occurs it will overwrite the previous assertion even before the assertion is logged. Also if the remaining code of the test case would run wild if the assertion failed, it will as it is not aborted. Therefore you SHOULD NOT use this assertion style unless you really explicitely want it.
See also:
ACEUNIT_ASSERTION_STYLE

#define ACEUNIT_C_MODE_C89   2

Value for ACEUNIT_C_MODE for using AceUnit's own replacement definitions.

#define ACEUNIT_C_MODE_C99_INCLUDES   1

Value for ACEUNIT_C_MODE for including C99 standard header files.

#define ACEUNIT_C_MODE_PROPRIETARY   3

Value for ACEUNIT_C_MODE for providing proprietary replacement definitions by the user.

#define ACEUNIT_H   1

Include shield to protect the header file from being included more than once.

#define ALL_TESTS   ((AceTestId_t) -1)

Special value for AceTestId_t that specifies all tests.

The value is all bits set. This value can be used in AceTestId_t values.

#define bool   int

Replacement for stdbool.h bool in case stdbool.h is not available.

#define false   0

Replacement for stdbool.h false in case stdbool.h is not available.

#define newAssertionError ( message   )     { AssertionId_t assertion = { __LINE__, message }; recordError(A_FIXTURE_ID, assertion); } ACEUNIT_ABORT

Creates a new assertion error.

Parameters:
message Message to create.

#define NO_TEST   ((AceTestId_t) 0)

Special value for AceTestId_t that specifies no test.

The value is zero. This value can be used to terminate vectors of AceTestId_t values.

#define NULL   ((void *) 0)

Replacement for stddef.h NULL in case stddef.h is not available.

#define TestCaseId_NULL   0

The value for something of type TestCaseId_t for denoting no testcase.

#define true   1

Replacement for stdbool.h true in case stdbool.h is not available.

Typedef Documentation

typedef uint16_t AceGroupId_t

GroupId_t specifies a group.

typedef uint16_t AceTestId_t

TestId_t specifies a test.

typedef SuiteId_t FixtureId_t

FixtureId_t specifies a test fixture.

On embedded systems, this is a 16 bit quantity that uniquely identifies the test fixture. On normal systems, this is the filename of fixture.

typedef signed short int int16_t

Replacement for stdint.h int16_t in case stdint.h is not available.

typedef signed long int int32_t

Replacement for stdint.h int32_t in case stdint.h is not available.

typedef signed char int8_t

Replacement for stdint.h int8_t in case stdint.h is not available.

typedef int linenumber_t

The type to use for line numbers.

typedef long unsigned int size_t

Replacement for stddef.h size_t in case stddef.h is not available.

typedef AceTestId_t SuiteId_t

SuiteId_t specifies a test suite.

On embedded systems, this is a 16 bit quantity that uniquely identifies the test suite. On normal systems, this is the directory name of the suite.

Note:
Fixtures also are Suites.

typedef AceTestId_t TestCaseId_t

TestCaseId_t specifies a test case.

On embedded systems, this is a 16 bit quantity that uniquely identifies the test case within its fixture. On normal systems, this is the function name of the test case.

typedef void(* testMethod_t)(void)

Method signature for annotated test methods.

See also:
A_Test

A_Before

A_After

A_BeforeClass

A_AfterClass

A_Ignore

typedef unsigned short int uint16_t

Replacement for stdint.h uint16_t in case stdint.h is not available.

typedef unsigned long int uint32_t

Replacement for stdint.h uint32_t in case stdint.h is not available.

typedef unsigned char uint8_t

Replacement for stdint.h uint8_t in case stdint.h is not available.

Function Documentation

void recordError ( const FixtureId_t  fixtureId,
const AssertionId_t  assertionId 
)

Records an error.

Parameters:
fixtureId Id of the fixture that contained the test case with the failed assertion.
assertionId Id of the assertion that failed.

void runFixture ( const TestFixture_t *const   fixture,
AceGroupId_t  group 
)

Runs all test cases from a test fixture.

Parameters:
fixture Test fixture to run.
group Group to run. This parameter is only available if ACEUNIT_GROUP is defined.

void runSuite ( const TestSuite_t *const   suite,
AceGroupId_t  group 
)

Runs all test cases from a test suite.

Parameters:
suite Test suite to run.
group Group to run. This parameter is only available if ACEUNIT_GROUP is defined.

Generated on Sun Feb 13 11:10:16 2011 for AceUnit by  doxygen 1.5.3