test.h@ 20573

Last change on this file since 20573 was 20573, checked in by vboxsync, 15 years ago
iprt/test.h: Added RTTestSetDefault.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 30.4 KB

Line
1	/** @file
2	* IPRT - Testcase Framework.
3	*/
4
5	/*
6	* Copyright (C) 2009 Sun Microsystems, Inc.
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*
25	* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26	* Clara, CA 95054 USA or visit http://www.sun.com if you need
27	* additional information or have any questions.
28	*/
29
30	#ifndef ___iprt_test_h
31	#define ___iprt_test_h
32
33	#include <iprt/cdefs.h>
34	#include <iprt/types.h>
35	#include <iprt/stdarg.h>
36
37	RT_C_DECLS_BEGIN
38
39	/** @defgroup grp_rt_test RTTest - Testcase Framework.
40	* @ingroup grp_rt
41	* @{
42	*/
43
44	/** A test handle. */
45	typedef struct RTTESTINT *RTTEST;
46	/** A pointer to a test handle. */
47	typedef RTTEST *PRTTEST;
48	/** A const pointer to a test handle. */
49	typedef RTTEST const *PCRTTEST;
50
51	/** A NIL Test handle. */
52	#define NIL_RTTEST ((RTTEST)0)
53
54	/**
55	* Test message importance level.
56	*/
57	typedef enum RTTESTLVL
58	{
59	/** Invalid 0. */
60	RTTESTLVL_INVALID = 0,
61	/** Message should always be printed. */
62	RTTESTLVL_ALWAYS,
63	/** Failure message. */
64	RTTESTLVL_FAILURE,
65	/** Sub-test banner. */
66	RTTESTLVL_SUB_TEST,
67	/** Info message. */
68	RTTESTLVL_INFO,
69	/** Debug message. */
70	RTTESTLVL_DEBUG,
71	/** The last (invalid). */
72	RTTESTLVL_END
73	} RTTESTLVL;
74
75
76	/**
77	* Creates a test instance.
78	*
79	* @returns IPRT status code.
80	* @param pszTest The test name.
81	* @param phTest Where to store the test instance handle.
82	*/
83	RTR3DECL(int) RTTestCreate(const char *pszTest, PRTTEST phTest);
84
85	/**
86	* Destroys a test instance previously created by RTTestCreate.
87	*
88	* @returns IPRT status code.
89	* @param hTest The test handle. NIL_RTTEST is ignored.
90	*/
91	RTR3DECL(int) RTTestDestroy(RTTEST hTest);
92
93	/**
94	* Changes the default test instance for the calling thread.
95	*
96	* @returns IPRT status code.
97	*
98	* @param hNewDefaultTest The new default test. NIL_RTTEST is fine.
99	* @param phOldTest Where to store the old test handle. Optional.
100	*/
101	RTR3DECL(int) RTTestSetDefault(RTTEST hNewDefaultTest, PRTTEST phOldTest);
102
103	/**
104	* Allocate a block of guarded memory.
105	*
106	* @returns IPRT status code.
107	* @param hTest The test handle. If NIL_RTTEST we'll use the one
108	* associated with the calling thread.
109	* @param cb The amount of memory to allocate.
110	* @param cbAlign The alignment of the returned block.
111	* @param fHead Head or tail optimized guard.
112	* @param ppvUser Where to return the pointer to the block.
113	*/
114	RTR3DECL(int) RTTestGuardedAlloc(RTTEST hTest, size_t cb, uint32_t cbAlign, bool fHead, void **ppvUser);
115
116	/**
117	* Allocates a block of guarded memory where the guarded is immediately after
118	* the user memory.
119	*
120	* @returns Pointer to the allocated memory. NULL on failure.
121	* @param hTest The test handle. If NIL_RTTEST we'll use the one
122	* associated with the calling thread.
123	* @param cb The amount of memory to allocate.
124	*/
125	RTR3DECL(void *) RTTestGuardedAllocTail(RTTEST hTest, size_t cb);
126
127	/**
128	* Allocates a block of guarded memory where the guarded is right in front of
129	* the user memory.
130	*
131	* @returns Pointer to the allocated memory. NULL on failure.
132	* @param hTest The test handle. If NIL_RTTEST we'll use the one
133	* associated with the calling thread.
134	* @param cb The amount of memory to allocate.
135	*/
136	RTR3DECL(void *) RTTestGuardedAllocHead(RTTEST hTest, size_t cb);
137
138	/**
139	* Frees a block of guarded memory.
140	*
141	* @returns IPRT status code.
142	* @param hTest The test handle. If NIL_RTTEST we'll use the one
143	* associated with the calling thread.
144	* @param pv The memory. NULL is ignored.
145	*/
146	RTR3DECL(int) RTTestGuardedFree(RTTEST hTest, void *pv);
147
148	/**
149	* Test vprintf making sure the output starts on a new line.
150	*
151	* @returns Number of chars printed.
152	* @param hTest The test handle. If NIL_RTTEST we'll use the one
153	* associated with the calling thread.
154	* @param enmLevel Message importance level.
155	* @param pszFormat The message.
156	* @param va Arguments.
157	*/
158	RTR3DECL(int) RTTestPrintfNlV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va);
159
160	/**
161	* Test printf making sure the output starts on a new line.
162	*
163	* @returns Number of chars printed.
164	* @param hTest The test handle. If NIL_RTTEST we'll use the one
165	* associated with the calling thread.
166	* @param enmLevel Message importance level.
167	* @param pszFormat The message.
168	* @param ... Arguments.
169	*/
170	RTR3DECL(int) RTTestPrintfNl(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...);
171
172	/**
173	* Test vprintf, makes sure lines are prefixed and so forth.
174	*
175	* @returns Number of chars printed.
176	* @param hTest The test handle. If NIL_RTTEST we'll use the one
177	* associated with the calling thread.
178	* @param enmLevel Message importance level.
179	* @param pszFormat The message.
180	* @param va Arguments.
181	*/
182	RTR3DECL(int) RTTestPrintfV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va);
183
184	/**
185	* Test printf, makes sure lines are prefixed and so forth.
186	*
187	* @returns Number of chars printed.
188	* @param hTest The test handle. If NIL_RTTEST we'll use the one
189	* associated with the calling thread.
190	* @param enmLevel Message importance level.
191	* @param pszFormat The message.
192	* @param ... Arguments.
193	*/
194	RTR3DECL(int) RTTestPrintf(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...);
195
196	/**
197	* Prints the test banner.
198	*
199	* @returns Number of chars printed.
200	* @param hTest The test handle. If NIL_RTTEST we'll use the one
201	* associated with the calling thread.
202	*/
203	RTR3DECL(int) RTTestBanner(RTTEST hTest);
204
205	/**
206	* Summaries the test, destroys the test instance and return an exit code.
207	*
208	* @returns Test program exit code.
209	* @param hTest The test handle. If NIL_RTTEST we'll use the one
210	* associated with the calling thread.
211	*/
212	RTR3DECL(int) RTTestSummaryAndDestroy(RTTEST hTest);
213
214	/**
215	* Skips the test, destroys the test instance and return an exit code.
216	*
217	* @returns Test program exit code.
218	* @param hTest The test handle. If NIL_RTTEST we'll use the one
219	* associated with the calling thread.
220	* @param pszReasonFmt Text explaining why, optional (NULL).
221	* @param va Arguments for the reason format string.
222	*/
223	RTR3DECL(int) RTTestSkipAndDestroyV(RTTEST hTest, const char *pszReason, va_list va);
224
225	/**
226	* Skips the test, destroys the test instance and return an exit code.
227	*
228	* @returns Test program exit code.
229	* @param hTest The test handle. If NIL_RTTEST we'll use the one
230	* associated with the calling thread.
231	* @param pszReasonFmt Text explaining why, optional (NULL).
232	* @param va Arguments for the reason format string.
233	*/
234	RTR3DECL(int) RTTestSkipAndDestroy(RTTEST hTest, const char *pszReason, ...);
235
236	/**
237	* Starts a sub-test.
238	*
239	* This will perform an implicit RTTestSubDone() call if that has not been done
240	* since the last RTTestSub call.
241	*
242	* @returns Number of chars printed.
243	* @param hTest The test handle. If NIL_RTTEST we'll use the one
244	* associated with the calling thread.
245	* @param pszSubTest The sub-test name.
246	*/
247	RTR3DECL(int) RTTestSub(RTTEST hTest, const char *pszSubTest);
248
249	/**
250	* Format string version of RTTestSub.
251	*
252	* See RTTestSub for details.
253	*
254	* @returns Number of chars printed.
255	* @param hTest The test handle. If NIL_RTTEST we'll use the one
256	* associated with the calling thread.
257	* @param pszSubTestFmt The sub-test name format string.
258	* @param ... Arguments.
259	*/
260	RTR3DECL(int) RTTestSubF(RTTEST hTest, const char *pszSubTestFmt, ...);
261
262	/**
263	* Format string version of RTTestSub.
264	*
265	* See RTTestSub for details.
266	*
267	* @returns Number of chars printed.
268	* @param hTest The test handle. If NIL_RTTEST we'll use the one
269	* associated with the calling thread.
270	* @param pszSubTestFmt The sub-test name format string.
271	* @param ... Arguments.
272	*/
273	RTR3DECL(int) RTTestSubV(RTTEST hTest, const char *pszSubTestFmt, va_list va);
274
275	/**
276	* Completes a sub-test.
277	*
278	* @returns Number of chars printed.
279	* @param hTest The test handle. If NIL_RTTEST we'll use the one
280	* associated with the calling thread.
281	*/
282	RTR3DECL(int) RTTestSubDone(RTTEST hTest);
283
284	/**
285	* Prints an extended PASSED message, optional.
286	*
287	* This does not conclude the sub-test, it could be used to report the passing
288	* of a sub-sub-to-the-power-of-N-test.
289	*
290	* @returns IPRT status code.
291	* @param hTest The test handle. If NIL_RTTEST we'll use the one
292	* associated with the calling thread.
293	* @param pszFormat The message. No trailing newline.
294	* @param va The arguments.
295	*/
296	RTR3DECL(int) RTTestPassedV(RTTEST hTest, const char *pszFormat, va_list va);
297
298	/**
299	* Prints an extended PASSED message, optional.
300	*
301	* This does not conclude the sub-test, it could be used to report the passing
302	* of a sub-sub-to-the-power-of-N-test.
303	*
304	* @returns IPRT status code.
305	* @param hTest The test handle. If NIL_RTTEST we'll use the one
306	* associated with the calling thread.
307	* @param pszFormat The message. No trailing newline.
308	* @param ... The arguments.
309	*/
310	RTR3DECL(int) RTTestPassed(RTTEST hTest, const char *pszFormat, ...);
311
312
313	/**
314	* Increments the error counter.
315	*
316	* @returns IPRT status code.
317	* @param hTest The test handle. If NIL_RTTEST we'll use the one
318	* associated with the calling thread.
319	*/
320	RTR3DECL(int) RTTestErrorInc(RTTEST hTest);
321
322	/**
323	* Increments the error counter and prints a failure message.
324	*
325	* @returns IPRT status code.
326	* @param hTest The test handle. If NIL_RTTEST we'll use the one
327	* associated with the calling thread.
328	* @param pszFormat The message. No trailing newline.
329	* @param va The arguments.
330	*/
331	RTR3DECL(int) RTTestFailedV(RTTEST hTest, const char *pszFormat, va_list va);
332
333	/**
334	* Increments the error counter and prints a failure message.
335	*
336	* @returns IPRT status code.
337	* @param hTest The test handle. If NIL_RTTEST we'll use the one
338	* associated with the calling thread.
339	* @param pszFormat The message. No trailing newline.
340	* @param ... The arguments.
341	*/
342	RTR3DECL(int) RTTestFailed(RTTEST hTest, const char *pszFormat, ...);
343
344	/**
345	* Same as RTTestPrintfV with RTTESTLVL_FAILURE.
346	*
347	* @returns Number of chars printed.
348	* @param hTest The test handle. If NIL_RTTEST we'll use the one
349	* associated with the calling thread.
350	* @param enmLevel Message importance level.
351	* @param pszFormat The message.
352	* @param va Arguments.
353	*/
354	RTR3DECL(int) RTTestFailureDetailsV(RTTEST hTest, const char *pszFormat, va_list va);
355
356	/**
357	* Same as RTTestPrintf with RTTESTLVL_FAILURE.
358	*
359	* @returns Number of chars printed.
360	* @param hTest The test handle. If NIL_RTTEST we'll use the one
361	* associated with the calling thread.
362	* @param enmLevel Message importance level.
363	* @param pszFormat The message.
364	* @param ... Arguments.
365	*/
366	RTR3DECL(int) RTTestFailureDetails(RTTEST hTest, const char *pszFormat, ...);
367
368
369	/** @def RTTEST_CHECK
370	* Check whether a boolean expression holds true.
371	*
372	* If the expression is false, call RTTestFailed giving the line number and expression.
373	*
374	* @param hTest The test handle.
375	* @param expr The expression to evaluate.
376	*/
377	#define RTTEST_CHECK(hTest, expr) \
378	do { if (!(expr)) { \
379	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
380	} \
381	} while (0)
382	/** @def RTTEST_CHECK_RET
383	* Check whether a boolean expression holds true, returns on false.
384	*
385	* If the expression is false, call RTTestFailed giving the line number and expression.
386	*
387	* @param hTest The test handle.
388	* @param expr The expression to evaluate.
389	* @param rcRet What to return on failure.
390	*/
391	#define RTTEST_CHECK_RET(hTest, expr, rcRet) \
392	do { if (!(expr)) { \
393	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
394	return (rcRet); \
395	} \
396	} while (0)
397	/** @def RTTEST_CHECK_RETV
398	* Check whether a boolean expression holds true, returns void on false.
399	*
400	* If the expression is false, call RTTestFailed giving the line number and expression.
401	*
402	* @param hTest The test handle.
403	* @param expr The expression to evaluate.
404	*/
405	#define RTTEST_CHECK_RETV(hTest, expr) \
406	do { if (!(expr)) { \
407	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
408	return; \
409	} \
410	} while (0)
411
412
413	/** @def RTTEST_CHECK_MSG
414	* Check whether a boolean expression holds true.
415	*
416	* If the expression is false, call RTTestFailed giving the line number and expression.
417	*
418	* @param hTest The test handle.
419	* @param expr The expression to evaluate.
420	* @param DetailsArgs Argument list for RTTestFailureDetails, including
421	* parenthesis.
422	*/
423	#define RTTEST_CHECK_MSG(hTest, expr, DetailsArgs) \
424	do { if (!(expr)) { \
425	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
426	RTTestFailureDetails DetailsArgs; \
427	} \
428	} while (0)
429	/** @def RTTEST_CHECK_MSG_RET
430	* Check whether a boolean expression holds true, returns on false.
431	*
432	* If the expression is false, call RTTestFailed giving the line number and expression.
433	*
434	* @param hTest The test handle.
435	* @param expr The expression to evaluate.
436	* @param DetailsArgs Argument list for RTTestFailureDetails, including
437	* parenthesis.
438	* @param rcRet What to return on failure.
439	*/
440	#define RTTEST_CHECK_MSG_RET(hTest, expr, DetailsArgs, rcRet) \
441	do { if (!(expr)) { \
442	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
443	RTTestFailureDetails DetailsArgs; \
444	return (rcRet); \
445	} \
446	} while (0)
447	/** @def RTTEST_CHECK_MSG_RET
448	* Check whether a boolean expression holds true, returns void on false.
449	*
450	* If the expression is false, call RTTestFailed giving the line number and expression.
451	*
452	* @param hTest The test handle.
453	* @param expr The expression to evaluate.
454	* @param DetailsArgs Argument list for RTTestFailureDetails, including
455	* parenthesis.
456	*/
457	#define RTTEST_CHECK_MSG_RETV(hTest, expr, DetailsArgs) \
458	do { if (!(expr)) { \
459	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
460	RTTestFailureDetails DetailsArgs; \
461	return; \
462	} \
463	} while (0)
464
465
466	/** @def RTTEST_CHECK_RC
467	* Check whether an expression returns a specific IPRT style status code.
468	*
469	* If a different status code is return, call RTTestFailed giving the line
470	* number, expression, actual and expected status codes.
471	*
472	* @param hTest The test handle.
473	* @param rcExpr The expression resulting an IPRT status code.
474	* @param rcExpect The expected return code. This may be referenced
475	* more than once by the macro.
476	*/
477	#define RTTEST_CHECK_RC(hTest, rcExpr, rcExpect) \
478	do { \
479	int rcCheck = (rcExpr); \
480	if (rcCheck != (rcExpect)) { \
481	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
482	} \
483	} while (0)
484	/** @def RTTEST_CHECK_RC_RET
485	* Check whether an expression returns a specific IPRT style status code.
486	*
487	* If a different status code is return, call RTTestFailed giving the line
488	* number, expression, actual and expected status codes, then return.
489	*
490	* @param hTest The test handle.
491	* @param rcExpr The expression resulting an IPRT status code.
492	* @param rcExpect The expected return code. This may be referenced
493	* more than once by the macro.
494	* @param rcRet The return code.
495	*/
496	#define RTTEST_CHECK_RC_RET(hTest, rcExpr, rcExpect, rcRet) \
497	do { \
498	int rcCheck = (rcExpr); \
499	if (rcCheck != (rcExpect)) { \
500	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
501	return (rcRet); \
502	} \
503	} while (0)
504	/** @def RTTEST_CHECK_RC_RETV
505	* Check whether an expression returns a specific IPRT style status code.
506	*
507	* If a different status code is return, call RTTestFailed giving the line
508	* number, expression, actual and expected status codes, then return.
509	*
510	* @param hTest The test handle.
511	* @param rcExpr The expression resulting an IPRT status code.
512	* @param rcExpect The expected return code. This may be referenced
513	* more than once by the macro.
514	*/
515	#define RTTEST_CHECK_RC_RETV(hTest, rcExpr, rcExpect) \
516	do { \
517	int rcCheck = (rcExpr); \
518	if (rcCheck != (rcExpect)) { \
519	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
520	return; \
521	} \
522	} while (0)
523
524
525	/** @def RTTEST_CHECK_RC_OK
526	* Check whether a IPRT style status code indicates success.
527	*
528	* If the status indicates failure, call RTTestFailed giving the line number,
529	* expression and status code.
530	*
531	* @param hTest The test handle.
532	* @param rcExpr The expression resulting an IPRT status code.
533	*/
534	#define RTTEST_CHECK_RC_OK(hTest, rcExpr) \
535	do { \
536	int rcCheck = (rcExpr); \
537	if (RT_FAILURE(rcCheck)) { \
538	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rc); \
539	} \
540	} while (0)
541	/** @def RTTEST_CHECK_RC_OK_RET
542	* Check whether a IPRT style status code indicates success.
543	*
544	* If the status indicates failure, call RTTestFailed giving the line number,
545	* expression and status code, then return with the specified value.
546	*
547	* @param hTest The test handle.
548	* @param rcExpr The expression resulting an IPRT status code.
549	* @param rcRet The return code.
550	*/
551	#define RTTEST_CHECK_RC_OK_RET(hTest, rcExpr, rcRet) \
552	do { \
553	int rcCheck = (rcExpr); \
554	if (RT_FAILURE(rcCheck)) { \
555	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rc); \
556	return (rcRet); \
557	} \
558	} while (0)
559	/** @def RTTEST_CHECK_RC_OK_RETV
560	* Check whether a IPRT style status code indicates success.
561	*
562	* If the status indicates failure, call RTTestFailed giving the line number,
563	* expression and status code, then return.
564	*
565	* @param hTest The test handle.
566	* @param rcExpr The expression resulting an IPRT status code.
567	*/
568	#define RTTEST_CHECK_RC_OK_RETV(hTest, rcExpr) \
569	do { \
570	int rcCheck = (rcExpr); \
571	if (RT_FAILURE(rcCheck)) { \
572	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rc); \
573	return; \
574	} \
575	} while (0)
576
577
578
579
580	/** @name Implicit Test Handle API Variation
581	* The test handle is retrieved from the test TLS entry of the calling thread.
582	* @{
583	*/
584
585	/**
586	* Test vprintf, makes sure lines are prefixed and so forth.
587	*
588	* @returns Number of chars printed.
589	* @param enmLevel Message importance level.
590	* @param pszFormat The message.
591	* @param va Arguments.
592	*/
593	RTR3DECL(int) RTTestIPrintfV(RTTESTLVL enmLevel, const char *pszFormat, va_list va);
594
595	/**
596	* Test printf, makes sure lines are prefixed and so forth.
597	*
598	* @returns Number of chars printed.
599	* @param enmLevel Message importance level.
600	* @param pszFormat The message.
601	* @param ... Arguments.
602	*/
603	RTR3DECL(int) RTTestIPrintf(RTTESTLVL enmLevel, const char *pszFormat, ...);
604
605	/**
606	* Starts a sub-test.
607	*
608	* This will perform an implicit RTTestSubDone() call if that has not been done
609	* since the last RTTestSub call.
610	*
611	* @returns Number of chars printed.
612	* @param pszSubTest The sub-test name.
613	*/
614	RTR3DECL(int) RTTestISub(const char *pszSubTest);
615
616	/**
617	* Format string version of RTTestSub.
618	*
619	* See RTTestSub for details.
620	*
621	* @returns Number of chars printed.
622	* @param pszSubTestFmt The sub-test name format string.
623	* @param ... Arguments.
624	*/
625	RTR3DECL(int) RTTestISubF(const char *pszSubTestFmt, ...);
626
627	/**
628	* Format string version of RTTestSub.
629	*
630	* See RTTestSub for details.
631	*
632	* @returns Number of chars printed.
633	* @param pszSubTestFmt The sub-test name format string.
634	* @param ... Arguments.
635	*/
636	RTR3DECL(int) RTTestISubV(const char *pszSubTestFmt, va_list va);
637
638	/**
639	* Completes a sub-test.
640	*
641	* @returns Number of chars printed.
642	*/
643	RTR3DECL(int) RTTestISubDone(void);
644
645	/**
646	* Prints an extended PASSED message, optional.
647	*
648	* This does not conclude the sub-test, it could be used to report the passing
649	* of a sub-sub-to-the-power-of-N-test.
650	*
651	* @returns IPRT status code.
652	* @param pszFormat The message. No trailing newline.
653	* @param va The arguments.
654	*/
655	RTR3DECL(int) RTTestIPassedV(const char *pszFormat, va_list va);
656
657	/**
658	* Prints an extended PASSED message, optional.
659	*
660	* This does not conclude the sub-test, it could be used to report the passing
661	* of a sub-sub-to-the-power-of-N-test.
662	*
663	* @returns IPRT status code.
664	* @param pszFormat The message. No trailing newline.
665	* @param ... The arguments.
666	*/
667	RTR3DECL(int) RTTestIPassed(const char *pszFormat, ...);
668
669	/**
670	* Increments the error counter.
671	*
672	* @returns IPRT status code.
673	*/
674	RTR3DECL(int) RTTestIErrorInc(void);
675
676	/**
677	* Increments the error counter and prints a failure message.
678	*
679	* @returns IPRT status code.
680	* @param pszFormat The message. No trailing newline.
681	* @param va The arguments.
682	*/
683	RTR3DECL(int) RTTestIFailedV(const char *pszFormat, va_list va);
684
685	/**
686	* Increments the error counter and prints a failure message.
687	*
688	* @returns IPRT status code.
689	* @param pszFormat The message. No trailing newline.
690	* @param ... The arguments.
691	*/
692	RTR3DECL(int) RTTestIFailed(const char *pszFormat, ...);
693
694	/**
695	* Same as RTTestIPrintfV with RTTESTLVL_FAILURE.
696	*
697	* @returns Number of chars printed.
698	* @param pszFormat The message.
699	* @param va Arguments.
700	*/
701	RTR3DECL(int) RTTestIFailureDetailsV(const char *pszFormat, va_list va);
702
703	/**
704	* Same as RTTestIPrintf with RTTESTLVL_FAILURE.
705	*
706	* @returns Number of chars printed.
707	* @param pszFormat The message.
708	* @param ... Arguments.
709	*/
710	RTR3DECL(int) RTTestIFailureDetails(const char *pszFormat, ...);
711
712
713	/** @def RTTESTI_CHECK
714	* Check whether a boolean expression holds true.
715	*
716	* If the expression is false, call RTTestIFailed giving the line number and
717	* expression.
718	*
719	* @param expr The expression to evaluate.
720	*/
721	#define RTTESTI_CHECK(expr) \
722	do { if (!(expr)) { \
723	RTTestIFailed("line %u: %s", __LINE__, #expr); \
724	} \
725	} while (0)
726	/** @def RTTESTI_CHECK_RET
727	* Check whether a boolean expression holds true, returns on false.
728	*
729	* If the expression is false, call RTTestIFailed giving the line number and
730	* expression.
731	*
732	* @param expr The expression to evaluate.
733	* @param rcRet What to return on failure.
734	*/
735	#define RTTESTI_CHECK_RET(expr, rcRet) \
736	do { if (!(expr)) { \
737	RTTestIFailed("line %u: %s", __LINE__, #expr); \
738	return (rcRet); \
739	} \
740	} while (0)
741	/** @def RTTESTI_CHECK_RETV
742	* Check whether a boolean expression holds true, returns void on false.
743	*
744	* If the expression is false, call RTTestIFailed giving the line number and
745	* expression.
746	*
747	* @param expr The expression to evaluate.
748	*/
749	#define RTTESTI_CHECK_RETV(expr) \
750	do { if (!(expr)) { \
751	RTTestIFailed("line %u: %s", __LINE__, #expr); \
752	return; \
753	} \
754	} while (0)
755
756
757	/** @def RTTESTI_CHECK_MSG
758	* Check whether a boolean expression holds true.
759	*
760	* If the expression is false, call RTTestIFailed giving the line number and
761	* expression.
762	*
763	* @param expr The expression to evaluate.
764	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
765	* parenthesis.
766	*/
767	#define RTTESTI_CHECK_MSG(expr, DetailsArgs) \
768	do { if (!(expr)) { \
769	RTTestIFailed("line %u: %s", __LINE__, #expr); \
770	RTTestIFailureDetails DetailsArgs; \
771	} \
772	} while (0)
773	/** @def RTTESTI_CHECK_MSG_RET
774	* Check whether a boolean expression holds true, returns on false.
775	*
776	* If the expression is false, call RTTestIFailed giving the line number and
777	* expression.
778	*
779	* @param expr The expression to evaluate.
780	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
781	* parenthesis.
782	* @param rcRet What to return on failure.
783	*/
784	#define RTTESTI_CHECK_MSG_RET(expr, DetailsArgs, rcRet) \
785	do { if (!(expr)) { \
786	RTTestIFailed("line %u: %s", __LINE__, #expr); \
787	RTTestIFailureDetails DetailsArgs; \
788	return (rcRet); \
789	} \
790	} while (0)
791	/** @def RTTESTI_CHECK_MSG_RET
792	* Check whether a boolean expression holds true, returns void on false.
793	*
794	* If the expression is false, call RTTestIFailed giving the line number and
795	* expression.
796	*
797	* @param expr The expression to evaluate.
798	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
799	* parenthesis.
800	*/
801	#define RTTESTI_CHECK_MSG_RETV(expr, DetailsArgs) \
802	do { if (!(expr)) { \
803	RTTestIFailed("line %u: %s", __LINE__, #expr); \
804	RTTestIFailureDetails DetailsArgs; \
805	return; \
806	} \
807	} while (0)
808
809
810	/** @def RTTESTI_CHECK_RC
811	* Check whether an expression returns a specific IPRT style status code.
812	*
813	* If a different status code is return, call RTTestIFailed giving the line
814	* number, expression, actual and expected status codes.
815	*
816	* @param rcExpr The expression resulting an IPRT status code.
817	* @param rcExpect The expected return code. This may be referenced
818	* more than once by the macro.
819	*/
820	#define RTTESTI_CHECK_RC(rcExpr, rcExpect) \
821	do { \
822	int rcCheck = (rcExpr); \
823	if (rcCheck != (rcExpect)) { \
824	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
825	} \
826	} while (0)
827	/** @def RTTESTI_CHECK_RC_RET
828	* Check whether an expression returns a specific IPRT style status code.
829	*
830	* If a different status code is return, call RTTestIFailed giving the line
831	* number, expression, actual and expected status codes, then return.
832	*
833	* @param rcExpr The expression resulting an IPRT status code.
834	* @param rcExpect The expected return code. This may be referenced
835	* more than once by the macro.
836	* @param rcRet The return code.
837	*/
838	#define RTTESTI_CHECK_RC_RET(rcExpr, rcExpect, rcRet) \
839	do { \
840	int rcCheck = (rcExpr); \
841	if (rcCheck != (rcExpect)) { \
842	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
843	return (rcRet); \
844	} \
845	} while (0)
846	/** @def RTTESTI_CHECK_RC_RETV
847	* Check whether an expression returns a specific IPRT style status code.
848	*
849	* If a different status code is return, call RTTestIFailed giving the line
850	* number, expression, actual and expected status codes, then return.
851	*
852	* @param rcExpr The expression resulting an IPRT status code.
853	* @param rcExpect The expected return code. This may be referenced
854	* more than once by the macro.
855	*/
856	#define RTTESTI_CHECK_RC_RETV(rcExpr, rcExpect) \
857	do { \
858	int rcCheck = (rcExpr); \
859	if (rcCheck != (rcExpect)) { \
860	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
861	return; \
862	} \
863	} while (0)
864
865
866	/** @def RTTESTI_CHECK_RC_OK
867	* Check whether a IPRT style status code indicates success.
868	*
869	* If the status indicates failure, call RTTestIFailed giving the line number,
870	* expression and status code.
871	*
872	* @param rcExpr The expression resulting an IPRT status code.
873	*/
874	#define RTTESTI_CHECK_RC_OK(rcExpr) \
875	do { \
876	int rcCheck = (rcExpr); \
877	if (RT_FAILURE(rcCheck)) { \
878	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
879	} \
880	} while (0)
881	/** @def RTTESTI_CHECK_RC_OK_RET
882	* Check whether a IPRT style status code indicates success.
883	*
884	* If the status indicates failure, call RTTestIFailed giving the line number,
885	* expression and status code, then return with the specified value.
886	*
887	* @param rcExpr The expression resulting an IPRT status code.
888	* @param rcRet The return code.
889	*/
890	#define RTTESTI_CHECK_RC_OK_RET(rcExpr, rcRet) \
891	do { \
892	int rcCheck = (rcExpr); \
893	if (RT_FAILURE(rcCheck)) { \
894	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
895	return (rcRet); \
896	} \
897	} while (0)
898	/** @def RTTESTI_CHECK_RC_OK_RETV
899	* Check whether a IPRT style status code indicates success.
900	*
901	* If the status indicates failure, call RTTestIFailed giving the line number,
902	* expression and status code, then return.
903	*
904	* @param rcExpr The expression resulting an IPRT status code.
905	*/
906	#define RTTESTI_CHECK_RC_OK_RETV(rcExpr) \
907	do { \
908	int rcCheck = (rcExpr); \
909	if (RT_FAILURE(rcCheck)) { \
910	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
911	return; \
912	} \
913	} while (0)
914
915	/** @} */
916
917
918	/** @} */
919
920	RT_C_DECLS_END
921
922	#endif
923

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/test.h@ 20573

Download in other formats: