1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
|
<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 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.
<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>
|
