<HTML>
<HEAD>
<TITLE>CUnit - Writing CUnit Test Cases</TITLE>
<LINK REL=StyleSheet HREF="CUnit_doc.css" TYPE="text/css" TITLE="CUnit Basic Style" />
</HEAD>
<BODY>
<DIV CLASS="NAVHEADER" >
<TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0">
<TR>
<TH COLSPAN="3" ALIGN="center"><H3>CUnit Progammers Guide</H3></TH>
</TR>
<TR>
<TD WIDTH="10%" ALIGN="left" VALIGN="bottom"><A HREF="introduction.html" ACCESSKEY="P" >Prev</A></TD>
<TD WIDTH="80%" ALIGN="center" VALIGN="bottom"><A HREF="index.html" ACCESSKEY="H" >Home</A></TD>
<TD WIDTH="10%" ALIGN="right" VALIGN="bottom"><A HREF="test_registry.html" ACCESSKEY="N" >Next</A></TD>
</TR>
</TABLE>
<HR ALIGN="LEFT" WIDTH="100%">
<H2>2. Writing CUnit Test Cases</H2>
<H3 ID="tests">2.1. Test Functions</H3>
A CUnit "test" is a C function having the signature:<BR /><BR />
<B><I>void test_func(void)</I></B>
<P />
There are no restrictions on the content of a test function, except
that it should not modify the CUnit framework (e.g. add suites or tests,
modify the test registry, or initiate a test run). A test function may
call other functions (which also may not modify the framework).
Registering a test will cause its function to be run when the
test is run.
<P />
An example test function for a routine that returns the maximum of 2
integers might look like:
<PRE><CODE>
int maxi(int i1, int i2)
{
return (i1 > i2) ? i1 : i2;
}
void test_maxi(void)
{
CU_ASSERT(maxi(0,2) == 2);
CU_ASSERT(maxi(0,-2) == 0);
CU_ASSERT(maxi(2,2) == 2);
}
</CODE></PRE>
<H3 ID="assertions">2.2. CUnit Assertions</H3>
CUnit provides a set of assertions for testing logical conditions. The
success or failure of these assertions is tracked by the framework,
and can be viewed when a test run is complete.
<P />
Each assertion tests a single logical condition, and fails if the
condition evaluates to <CODE>CU_FALSE</CODE>. Upon assertion failure,
the test function continues unless the user chooses the 'xxx_FATAL' version
of an assertion. In that case, the test function is aborted and returns
immediately. <B>FATAL versions of assertions should be used with caution!</B>
There is no opportunity for the test function to clean up after itself once a
FATAL assertion fails. The normal <A HREF="managing_tests.html#addsuite">suite
cleanup function</A> is not affected, however, and will be run in either case.
<P />
There are also special "assertions" for registering a
<A HREF="#pass">pass</A> or <A HREF="#fail">fail</A> with the framework
without performing a logical test. These are useful for testing flow
of control or other conditions not requiring a logical test:
<PRE><CODE>
void test_longjmp(void)
{
jmp_buf buf;
int i;
i = setjmp(buf);
if (i == 0) {
run_other_func();
CU_PASS("run_other_func() succeeded.");
}
else
CU_FAIL("run_other_func() issued longjmp.");
}
</CODE></PRE>
<P />
Other functions called by a registered test function may use the CUnit
assertions freely. These assertions will be counted for the calling
function. They may also use FATAL versions of assertions - failure
will abort the original test function and its entire call chain.
<P />
The assertions defined by CUnit are:
<P />
<B>#include <<A HREF="headers/CUnit.h">CUnit/CUnit.h</A>></B>
<P />
<TABLE CELLPADDING=5 BORDER=2>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT</B>(int expression)</CITE><BR />
<CITE><B>CU_ASSERT_FATAL</B>(int expression)</CITE><BR />
<CITE><B>CU_TEST</B>(int expression)</CITE><BR />
<CITE><B>CU_TEST_FATAL</B>(int expression)</CITE>
</CODE>
</TD>
<TD>Assert that <I>expression</I> is <CODE>CU_TRUE</CODE> (non-zero)</TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_TRUE</B>(value)</CITE><BR />
<CITE><B>CU_ASSERT_TRUE_FATAL</B>(value)</CITE>
</CODE>
</TD>
<TD>Assert that <I>value</I> is <CODE>CU_TRUE (non-zero)</TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_FALSE</B>(value)</CITE><BR />
<CITE><B>CU_ASSERT_FALSE_FATAL</B>(value)</CITE>
</CODE>
</TD>
<TD>Assert that <I>value</I> is <CODE>CU_FALSE</CODE> (zero)</TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_EQUAL</B>(actual, expected)</CITE><BR />
<CITE><B>CU_ASSERT_EQUAL_FATAL</B>(actual, expected)</CITE>
</CODE>
</TD>
<TD>Assert that <I>actual</I> = = <I>expected</I></TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_NOT_EQUAL</B>(actual, expected))</CITE><BR />
<CITE><B>CU_ASSERT_NOT_EQUAL_FATAL</B>(actual, expected)</CITE>
</CODE>
</TD>
<TD>Assert that <I>actual</I> != <I>expected</I></TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_PTR_EQUAL</B>(actual, expected)</CITE><BR />
<CITE><B>CU_ASSERT_PTR_EQUAL_FATAL</B>(actual, expected)</CITE>
</CODE>
</TD>
<TD>Assert that pointers <I>actual</I> = = <I>expected</I></TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_PTR_NOT_EQUAL</B>(actual, expected)</CITE><BR />
<CITE><B>CU_ASSERT_PTR_NOT_EQUAL_FATAL</B>(actual, expected)</CITE>
</CODE>
</TD>
<TD>Assert that pointers <I>actual</I> != <I>expected</I></TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_PTR_NULL</B>(value)</CITE><BR />
<CITE><B>CU_ASSERT_PTR_NULL_FATAL</B>(value)</CITE>
</CODE>
</TD>
<TD>Assert that pointer <I>value</I> == NULL</TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_PTR_NOT_NULL</B>(value)</CITE><BR />
<CITE><B>CU_ASSERT_PTR_NOT_NULL_FATAL</B>(value)</CITE>
</CODE>
</TD>
<TD>Assert that pointer <I>value</I> != NULL</TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_STRING_EQUAL</B>(actual, expected)</CITE><BR />
<CITE><B>CU_ASSERT_STRING_EQUAL_FATAL</B>(actual, expected)</CITE>
</CODE>
</TD>
<TD>Assert that strings <I>actual</I> and <I>expected</I> are equivalent</TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_STRING_NOT_EQUAL</B>(actual, expected)</CITE><BR />
<CITE><B>CU_ASSERT_STRING_NOT_EQUAL_FATAL</B>(actual, expected)</CITE>
</CODE>
</TD>
<TD>Assert that strings <I>actual</I> and <I>expected</I> differ</TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_NSTRING_EQUAL</B>(actual, expected, count)</CITE><BR />
<CITE><B>CU_ASSERT_NSTRING_EQUAL_FATAL</B>(actual, expected, count)</CITE>
</CODE>
</TD>
<TD>Assert that 1st count chars of <I>actual</I> and <I>expected</I> are the same</TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_NSTRING_NOT_EQUAL</B>(actual, expected, count)</CITE><BR />
<CITE><B>CU_ASSERT_NSTRING_NOT_EQUAL_FATAL</B>(actual, expected, count)</CITE>
</CODE>
</TD>
<TD>Assert that 1st count chars of <I>actual</I> and <I>expected</I> differ</TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_DOUBLE_EQUAL</B>(actual, expected, granularity)</CITE><BR />
<CITE><B>CU_ASSERT_DOUBLE_EQUAL_FATAL</B>(actual, expected, granularity)</CITE>
</CODE>
</TD>
<TD>
Assert that |<I>actual</I> - <I>expected</I>| <= |<I>granularity</I>|<BR />
<I>Math library must be linked in for this assertion.</I>
</TD>
</TR>
<TR VALIGN="top">
<TD>
<CODE>
<CITE><B>CU_ASSERT_DOUBLE_NOT_EQUAL</B>(actual, expected, granularity)</CITE><BR />
<CITE><B>CU_ASSERT_DOUBLE_NOT_EQUAL_FATAL</B>(actual, expected, granularity)</CITE>
</CODE>
</TD>
<TD>
Assert that |<I>actual</I> - <I>expected</I>| > |<I>granularity</I>|<BR />
<I>Math library must be linked in for this assertion.</I>
</TD>
</TR>
<TR VALIGN="top" ID="pass">
<TD>
<CODE>
<CITE><B>CU_PASS</B>(message)</CITE>
</CODE>
</TD>
<TD>
Register a passing assertion with the specified message. No logical test is performed.
</TD>
</TR>
<TR VALIGN="top" ID="fail">
<TD>
<CODE>
<CITE><B>CU_FAIL</B>(message)</CITE><BR />
<CITE><B>CU_FAIL_FATAL</B>(message)</CITE>
</CODE>
</TD>
<TD>
Register a failed assertion with the specified message. No logical test is performed.
</TD>
</TR>
</TABLE>
<P />
<H3 ID="deprecated">2.3. Depecated v1 Assertions</H3>
The following assertions are deprecated as of version 2. To use these assertions,
user code must be compiled with <CITE>USE_DEPRECATED_CUNIT_NAMES</CITE> defined.
Note that they behave the same as in version 1 (issue a 'return' statement
upon failure).
<P />
<B>#include <<A HREF="headers/CUnit.h">CUnit/CUnit.h</A>></B>
<P />
<TABLE CELLPADDING=5 BORDER=2>
<TR VALIGN="top">
<TD><B>Deprecated Name</B></TD>
<TD><B>Equivalent New Name</B></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT</CODE></TD>
<TD><CODE>CU_ASSERT_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_TRUE</CODE></TD>
<TD><CODE>CU_ASSERT_TRUE_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_FALSE</CODE></TD>
<TD><CODE>CU_ASSERT_FALSE_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_EQUAL</CODE></TD>
<TD><CODE>CU_ASSERT_EQUAL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_NOT_EQUAL</CODE></TD>
<TD><CODE>CU_ASSERT_NOT_EQUAL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_PTR_EQUAL</CODE></TD>
<TD><CODE>CU_ASSERT_PTR_EQUAL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_PTR_NOT_EQUAL</CODE></TD>
<TD><CODE>CU_ASSERT_PTR_NOT_EQUAL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_PTR_NULL</CODE></TD>
<TD><CODE>CU_ASSERT_PTR_NULL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_PTR_NOT_NULL</CODE></TD>
<TD><CODE>CU_ASSERT_PTR_NOT_NULL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_STRING_EQUAL</CODE></TD>
<TD><CODE>CU_ASSERT_STRING_EQUAL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_STRING_NOT_EQUAL</CODE></TD>
<TD><CODE>CU_ASSERT_STRING_NOT_EQUAL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_NSTRING_EQUAL</CODE></TD>
<TD><CODE>CU_ASSERT_NSTRING_EQUAL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_NSTRING_NOT_EQUAL</CODE></TD>
<TD><CODE>CU_ASSERT_NSTRING_NOT_EQUAL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_DOUBLE_EQUAL</CODE></TD>
<TD><CODE>CU_ASSERT_DOUBLE_EQUAL_FATAL</CODE></TD>
</TR>
<TR VALIGN="top">
<TD><CODE>ASSERT_DOUBLE_NOT_EQUAL</CODE></TD>
<TD><CODE>CU_ASSERT_DOUBLE_NOT_EQUAL_FATAL</CODE></TD>
</TR>
</TABLE>
<DIV CLASS="NAVFOOTER">
<HR ALIGN="LEFT" WIDTH="100%">
<TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0">
<TR>
<TD WIDTH="33%" ALIGN="left" VALIGN="top"><A HREF="introduction.html" ACCESSKEY="P">Prev</A></TD>
<TD WIDTH="34%" ALIGN="center" VALIGN="top"><A HREF="index.html" ACCESSKEY="H" >Home</A></TD>
<TD WIDTH="33%" ALIGN="right" VALIGN="top"><A HREF="test_registry.html" ACCESSKEY="N" >Next</A></TD>
</TR>
<TR>
<TD WIDTH="33%" ALIGN="left" VALIGN="top">Introduction</TD>
<TD WIDTH="34%" ALIGN="center" VALIGN="top"> </TD>
<TD WIDTH="33%" ALIGN="right" VALIGN="top">The Test Registry</TD>
</TR>
</TABLE>
</DIV>
</BODY>
</HTML>
