test.h@ 25645

Last change on this file since 25645 was 25645, checked in by vboxsync, 15 years ago
IPRT,DoxyFile.Core: Mopped up the errors in the IPRT doxygen run.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 31.9 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	* Initializes IPRT and creates a test instance.
87	*
88	* Typical usage is:
89	* @code
90	int main(int argc, char **argv)
91	{
92	RTTEST hTest;
93	int rc = RTTestInitAndCreate("tstSomething", &hTest);
94	if (rc)
95	return rc;
96	...
97	}
98	@endcode
99	*
100	* @returns 0 on success. On failure an error message is printed and
101	* a suitable exit code is return.
102	*
103	* @param pszTest The test name.
104	* @param phTest Where to store the test instance handle.
105	*/
106	RTR3DECL(int) RTTestInitAndCreate(const char *pszTest, PRTTEST phTest);
107
108	/**
109	* Destroys a test instance previously created by RTTestCreate.
110	*
111	* @returns IPRT status code.
112	* @param hTest The test handle. NIL_RTTEST is ignored.
113	*/
114	RTR3DECL(int) RTTestDestroy(RTTEST hTest);
115
116	/**
117	* Changes the default test instance for the calling thread.
118	*
119	* @returns IPRT status code.
120	*
121	* @param hNewDefaultTest The new default test. NIL_RTTEST is fine.
122	* @param phOldTest Where to store the old test handle. Optional.
123	*/
124	RTR3DECL(int) RTTestSetDefault(RTTEST hNewDefaultTest, PRTTEST phOldTest);
125
126	/**
127	* Allocate a block of guarded memory.
128	*
129	* @returns IPRT status code.
130	* @param hTest The test handle. If NIL_RTTEST we'll use the one
131	* associated with the calling thread.
132	* @param cb The amount of memory to allocate.
133	* @param cbAlign The alignment of the returned block.
134	* @param fHead Head or tail optimized guard.
135	* @param ppvUser Where to return the pointer to the block.
136	*/
137	RTR3DECL(int) RTTestGuardedAlloc(RTTEST hTest, size_t cb, uint32_t cbAlign, bool fHead, void **ppvUser);
138
139	/**
140	* Allocates a block of guarded memory where the guarded is immediately after
141	* the user memory.
142	*
143	* @returns Pointer to the allocated memory. NULL on failure.
144	* @param hTest The test handle. If NIL_RTTEST we'll use the one
145	* associated with the calling thread.
146	* @param cb The amount of memory to allocate.
147	*/
148	RTR3DECL(void *) RTTestGuardedAllocTail(RTTEST hTest, size_t cb);
149
150	/**
151	* Allocates a block of guarded memory where the guarded is right in front of
152	* the user memory.
153	*
154	* @returns Pointer to the allocated memory. NULL on failure.
155	* @param hTest The test handle. If NIL_RTTEST we'll use the one
156	* associated with the calling thread.
157	* @param cb The amount of memory to allocate.
158	*/
159	RTR3DECL(void *) RTTestGuardedAllocHead(RTTEST hTest, size_t cb);
160
161	/**
162	* Frees a block of guarded memory.
163	*
164	* @returns IPRT status code.
165	* @param hTest The test handle. If NIL_RTTEST we'll use the one
166	* associated with the calling thread.
167	* @param pv The memory. NULL is ignored.
168	*/
169	RTR3DECL(int) RTTestGuardedFree(RTTEST hTest, void *pv);
170
171	/**
172	* Test vprintf making sure the output starts on a new line.
173	*
174	* @returns Number of chars printed.
175	* @param hTest The test handle. If NIL_RTTEST we'll use the one
176	* associated with the calling thread.
177	* @param enmLevel Message importance level.
178	* @param pszFormat The message.
179	* @param va Arguments.
180	*/
181	RTR3DECL(int) RTTestPrintfNlV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va);
182
183	/**
184	* Test printf making sure the output starts on a new line.
185	*
186	* @returns Number of chars printed.
187	* @param hTest The test handle. If NIL_RTTEST we'll use the one
188	* associated with the calling thread.
189	* @param enmLevel Message importance level.
190	* @param pszFormat The message.
191	* @param ... Arguments.
192	*/
193	RTR3DECL(int) RTTestPrintfNl(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...);
194
195	/**
196	* Test vprintf, makes sure lines are prefixed and so forth.
197	*
198	* @returns Number of chars printed.
199	* @param hTest The test handle. If NIL_RTTEST we'll use the one
200	* associated with the calling thread.
201	* @param enmLevel Message importance level.
202	* @param pszFormat The message.
203	* @param va Arguments.
204	*/
205	RTR3DECL(int) RTTestPrintfV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va);
206
207	/**
208	* Test printf, makes sure lines are prefixed and so forth.
209	*
210	* @returns Number of chars printed.
211	* @param hTest The test handle. If NIL_RTTEST we'll use the one
212	* associated with the calling thread.
213	* @param enmLevel Message importance level.
214	* @param pszFormat The message.
215	* @param ... Arguments.
216	*/
217	RTR3DECL(int) RTTestPrintf(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...);
218
219	/**
220	* Prints the test banner.
221	*
222	* @returns Number of chars printed.
223	* @param hTest The test handle. If NIL_RTTEST we'll use the one
224	* associated with the calling thread.
225	*/
226	RTR3DECL(int) RTTestBanner(RTTEST hTest);
227
228	/**
229	* Summaries the test, destroys the test instance and return an exit code.
230	*
231	* @returns Test program exit code.
232	* @param hTest The test handle. If NIL_RTTEST we'll use the one
233	* associated with the calling thread.
234	*/
235	RTR3DECL(int) RTTestSummaryAndDestroy(RTTEST hTest);
236
237	/**
238	* Skips the test, destroys the test instance and return an exit code.
239	*
240	* @returns Test program exit code.
241	* @param hTest The test handle. If NIL_RTTEST we'll use the one
242	* associated with the calling thread.
243	* @param pszReasonFmt Text explaining why, optional (NULL).
244	* @param va Arguments for the reason format string.
245	*/
246	RTR3DECL(int) RTTestSkipAndDestroyV(RTTEST hTest, const char *pszReasonFmt, va_list va);
247
248	/**
249	* Skips the test, destroys the test instance and return an exit code.
250	*
251	* @returns Test program exit code.
252	* @param hTest The test handle. If NIL_RTTEST we'll use the one
253	* associated with the calling thread.
254	* @param pszReasonFmt Text explaining why, optional (NULL).
255	* @param ... Arguments for the reason format string.
256	*/
257	RTR3DECL(int) RTTestSkipAndDestroy(RTTEST hTest, const char *pszReasonFmt, ...);
258
259	/**
260	* Starts a sub-test.
261	*
262	* This will perform an implicit RTTestSubDone() call if that has not been done
263	* since the last RTTestSub call.
264	*
265	* @returns Number of chars printed.
266	* @param hTest The test handle. If NIL_RTTEST we'll use the one
267	* associated with the calling thread.
268	* @param pszSubTest The sub-test name.
269	*/
270	RTR3DECL(int) RTTestSub(RTTEST hTest, const char *pszSubTest);
271
272	/**
273	* Format string version of RTTestSub.
274	*
275	* See RTTestSub for details.
276	*
277	* @returns Number of chars printed.
278	* @param hTest The test handle. If NIL_RTTEST we'll use the one
279	* associated with the calling thread.
280	* @param pszSubTestFmt The sub-test name format string.
281	* @param ... Arguments.
282	*/
283	RTR3DECL(int) RTTestSubF(RTTEST hTest, const char *pszSubTestFmt, ...);
284
285	/**
286	* Format string version of RTTestSub.
287	*
288	* See RTTestSub for details.
289	*
290	* @returns Number of chars printed.
291	* @param hTest The test handle. If NIL_RTTEST we'll use the one
292	* associated with the calling thread.
293	* @param pszSubTestFmt The sub-test name format string.
294	* @param va Arguments.
295	*/
296	RTR3DECL(int) RTTestSubV(RTTEST hTest, const char *pszSubTestFmt, va_list va);
297
298	/**
299	* Completes a sub-test.
300	*
301	* @returns Number of chars printed.
302	* @param hTest The test handle. If NIL_RTTEST we'll use the one
303	* associated with the calling thread.
304	*/
305	RTR3DECL(int) RTTestSubDone(RTTEST hTest);
306
307	/**
308	* Prints an extended PASSED message, optional.
309	*
310	* This does not conclude the sub-test, it could be used to report the passing
311	* of a sub-sub-to-the-power-of-N-test.
312	*
313	* @returns IPRT status code.
314	* @param hTest The test handle. If NIL_RTTEST we'll use the one
315	* associated with the calling thread.
316	* @param pszFormat The message. No trailing newline.
317	* @param va The arguments.
318	*/
319	RTR3DECL(int) RTTestPassedV(RTTEST hTest, const char *pszFormat, va_list va);
320
321	/**
322	* Prints an extended PASSED message, optional.
323	*
324	* This does not conclude the sub-test, it could be used to report the passing
325	* of a sub-sub-to-the-power-of-N-test.
326	*
327	* @returns IPRT status code.
328	* @param hTest The test handle. If NIL_RTTEST we'll use the one
329	* associated with the calling thread.
330	* @param pszFormat The message. No trailing newline.
331	* @param ... The arguments.
332	*/
333	RTR3DECL(int) RTTestPassed(RTTEST hTest, const char *pszFormat, ...);
334
335
336	/**
337	* Increments the error counter.
338	*
339	* @returns IPRT status code.
340	* @param hTest The test handle. If NIL_RTTEST we'll use the one
341	* associated with the calling thread.
342	*/
343	RTR3DECL(int) RTTestErrorInc(RTTEST hTest);
344
345	/**
346	* Get the current error count.
347	*
348	* @returns The error counter, UINT32_MAX if no valid test handle.
349	* @param hTest The test handle. If NIL_RTTEST we'll use the one
350	* associated with the calling thread.
351	*/
352	RTR3DECL(uint32_t) RTTestErrorCount(RTTEST hTest);
353
354	/**
355	* Increments the error counter and prints a failure message.
356	*
357	* @returns IPRT status code.
358	* @param hTest The test handle. If NIL_RTTEST we'll use the one
359	* associated with the calling thread.
360	* @param pszFormat The message. No trailing newline.
361	* @param va The arguments.
362	*/
363	RTR3DECL(int) RTTestFailedV(RTTEST hTest, const char *pszFormat, va_list va);
364
365	/**
366	* Increments the error counter and prints a failure message.
367	*
368	* @returns IPRT status code.
369	* @param hTest The test handle. If NIL_RTTEST we'll use the one
370	* associated with the calling thread.
371	* @param pszFormat The message. No trailing newline.
372	* @param ... The arguments.
373	*/
374	RTR3DECL(int) RTTestFailed(RTTEST hTest, const char *pszFormat, ...);
375
376	/**
377	* Same as RTTestPrintfV with RTTESTLVL_FAILURE.
378	*
379	* @returns Number of chars printed.
380	* @param hTest The test handle. If NIL_RTTEST we'll use the one
381	* associated with the calling thread.
382	* @param pszFormat The message.
383	* @param va Arguments.
384	*/
385	RTR3DECL(int) RTTestFailureDetailsV(RTTEST hTest, const char *pszFormat, va_list va);
386
387	/**
388	* Same as RTTestPrintf with RTTESTLVL_FAILURE.
389	*
390	* @returns Number of chars printed.
391	* @param hTest The test handle. If NIL_RTTEST we'll use the one
392	* associated with the calling thread.
393	* @param pszFormat The message.
394	* @param ... Arguments.
395	*/
396	RTR3DECL(int) RTTestFailureDetails(RTTEST hTest, const char *pszFormat, ...);
397
398
399	/** @def RTTEST_CHECK
400	* Check whether a boolean expression holds true.
401	*
402	* If the expression is false, call RTTestFailed giving the line number and expression.
403	*
404	* @param hTest The test handle.
405	* @param expr The expression to evaluate.
406	*/
407	#define RTTEST_CHECK(hTest, expr) \
408	do { if (!(expr)) { \
409	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
410	} \
411	} while (0)
412	/** @def RTTEST_CHECK_RET
413	* Check whether a boolean expression holds true, returns on false.
414	*
415	* If the expression is false, call RTTestFailed giving the line number and expression.
416	*
417	* @param hTest The test handle.
418	* @param expr The expression to evaluate.
419	* @param rcRet What to return on failure.
420	*/
421	#define RTTEST_CHECK_RET(hTest, expr, rcRet) \
422	do { if (!(expr)) { \
423	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
424	return (rcRet); \
425	} \
426	} while (0)
427	/** @def RTTEST_CHECK_RETV
428	* Check whether a boolean expression holds true, returns void on false.
429	*
430	* If the expression is false, call RTTestFailed giving the line number and expression.
431	*
432	* @param hTest The test handle.
433	* @param expr The expression to evaluate.
434	*/
435	#define RTTEST_CHECK_RETV(hTest, expr) \
436	do { if (!(expr)) { \
437	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
438	return; \
439	} \
440	} while (0)
441
442
443	/** @def RTTEST_CHECK_MSG
444	* Check whether a boolean expression holds true.
445	*
446	* If the expression is false, call RTTestFailed giving the line number and expression.
447	*
448	* @param hTest The test handle.
449	* @param expr The expression to evaluate.
450	* @param DetailsArgs Argument list for RTTestFailureDetails, including
451	* parenthesis.
452	*/
453	#define RTTEST_CHECK_MSG(hTest, expr, DetailsArgs) \
454	do { if (!(expr)) { \
455	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
456	RTTestFailureDetails DetailsArgs; \
457	} \
458	} while (0)
459	/** @def RTTEST_CHECK_MSG_RET
460	* Check whether a boolean expression holds true, returns on false.
461	*
462	* If the expression is false, call RTTestFailed giving the line number and expression.
463	*
464	* @param hTest The test handle.
465	* @param expr The expression to evaluate.
466	* @param DetailsArgs Argument list for RTTestFailureDetails, including
467	* parenthesis.
468	* @param rcRet What to return on failure.
469	*/
470	#define RTTEST_CHECK_MSG_RET(hTest, expr, DetailsArgs, rcRet) \
471	do { if (!(expr)) { \
472	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
473	RTTestFailureDetails DetailsArgs; \
474	return (rcRet); \
475	} \
476	} while (0)
477	/** @def RTTEST_CHECK_MSG_RET
478	* Check whether a boolean expression holds true, returns void on false.
479	*
480	* If the expression is false, call RTTestFailed giving the line number and expression.
481	*
482	* @param hTest The test handle.
483	* @param expr The expression to evaluate.
484	* @param DetailsArgs Argument list for RTTestFailureDetails, including
485	* parenthesis.
486	*/
487	#define RTTEST_CHECK_MSG_RETV(hTest, expr, DetailsArgs) \
488	do { if (!(expr)) { \
489	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
490	RTTestFailureDetails DetailsArgs; \
491	return; \
492	} \
493	} while (0)
494
495
496	/** @def RTTEST_CHECK_RC
497	* Check whether an expression returns a specific IPRT style status code.
498	*
499	* If a different status code is return, call RTTestFailed giving the line
500	* number, expression, actual and expected status codes.
501	*
502	* @param hTest The test handle.
503	* @param rcExpr The expression resulting in an IPRT status code.
504	* @param rcExpect The expected return code. This may be referenced
505	* more than once by the macro.
506	*/
507	#define RTTEST_CHECK_RC(hTest, rcExpr, rcExpect) \
508	do { \
509	int rcCheck = (rcExpr); \
510	if (rcCheck != (rcExpect)) { \
511	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
512	} \
513	} while (0)
514	/** @def RTTEST_CHECK_RC_RET
515	* Check whether an expression returns a specific IPRT style status code.
516	*
517	* If a different status code is return, call RTTestFailed giving the line
518	* number, expression, actual and expected status codes, then return.
519	*
520	* @param hTest The test handle.
521	* @param rcExpr The expression resulting in an IPRT status code.
522	* This will be assigned to a local rcCheck variable
523	* that can be used as return value.
524	* @param rcExpect The expected return code. This may be referenced
525	* more than once by the macro.
526	* @param rcRet The return code.
527	*/
528	#define RTTEST_CHECK_RC_RET(hTest, rcExpr, rcExpect, rcRet) \
529	do { \
530	int rcCheck = (rcExpr); \
531	if (rcCheck != (rcExpect)) { \
532	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
533	return (rcRet); \
534	} \
535	} while (0)
536	/** @def RTTEST_CHECK_RC_RETV
537	* Check whether an expression returns a specific IPRT style status code.
538	*
539	* If a different status code is return, call RTTestFailed giving the line
540	* number, expression, actual and expected status codes, then return.
541	*
542	* @param hTest The test handle.
543	* @param rcExpr The expression resulting in an IPRT status code.
544	* @param rcExpect The expected return code. This may be referenced
545	* more than once by the macro.
546	*/
547	#define RTTEST_CHECK_RC_RETV(hTest, rcExpr, rcExpect) \
548	do { \
549	int rcCheck = (rcExpr); \
550	if (rcCheck != (rcExpect)) { \
551	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
552	return; \
553	} \
554	} while (0)
555
556
557	/** @def RTTEST_CHECK_RC_OK
558	* Check whether a IPRT style status code indicates success.
559	*
560	* If the status indicates failure, call RTTestFailed giving the line number,
561	* expression and status code.
562	*
563	* @param hTest The test handle.
564	* @param rcExpr The expression resulting in an IPRT status code.
565	*/
566	#define RTTEST_CHECK_RC_OK(hTest, rcExpr) \
567	do { \
568	int rcCheck = (rcExpr); \
569	if (RT_FAILURE(rcCheck)) { \
570	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
571	} \
572	} while (0)
573	/** @def RTTEST_CHECK_RC_OK_RET
574	* Check whether a IPRT style status code indicates success.
575	*
576	* If the status indicates failure, call RTTestFailed giving the line number,
577	* expression and status code, then return with the specified value.
578	*
579	* @param hTest The test handle.
580	* @param rcExpr The expression resulting in an IPRT status code.
581	* This will be assigned to a local rcCheck variable
582	* that can be used as return value.
583	* @param rcRet The return code.
584	*/
585	#define RTTEST_CHECK_RC_OK_RET(hTest, rcExpr, rcRet) \
586	do { \
587	int rcCheck = (rcExpr); \
588	if (RT_FAILURE(rcCheck)) { \
589	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
590	return (rcRet); \
591	} \
592	} while (0)
593	/** @def RTTEST_CHECK_RC_OK_RETV
594	* Check whether a IPRT style status code indicates success.
595	*
596	* If the status indicates failure, call RTTestFailed giving the line number,
597	* expression and status code, then return.
598	*
599	* @param hTest The test handle.
600	* @param rcExpr The expression resulting in an IPRT status code.
601	*/
602	#define RTTEST_CHECK_RC_OK_RETV(hTest, rcExpr) \
603	do { \
604	int rcCheck = (rcExpr); \
605	if (RT_FAILURE(rcCheck)) { \
606	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
607	return; \
608	} \
609	} while (0)
610
611
612
613
614	/** @name Implicit Test Handle API Variation
615	* The test handle is retrieved from the test TLS entry of the calling thread.
616	* @{
617	*/
618
619	/**
620	* Test vprintf, makes sure lines are prefixed and so forth.
621	*
622	* @returns Number of chars printed.
623	* @param enmLevel Message importance level.
624	* @param pszFormat The message.
625	* @param va Arguments.
626	*/
627	RTR3DECL(int) RTTestIPrintfV(RTTESTLVL enmLevel, const char *pszFormat, va_list va);
628
629	/**
630	* Test printf, makes sure lines are prefixed and so forth.
631	*
632	* @returns Number of chars printed.
633	* @param enmLevel Message importance level.
634	* @param pszFormat The message.
635	* @param ... Arguments.
636	*/
637	RTR3DECL(int) RTTestIPrintf(RTTESTLVL enmLevel, const char *pszFormat, ...);
638
639	/**
640	* Starts a sub-test.
641	*
642	* This will perform an implicit RTTestSubDone() call if that has not been done
643	* since the last RTTestSub call.
644	*
645	* @returns Number of chars printed.
646	* @param pszSubTest The sub-test name.
647	*/
648	RTR3DECL(int) RTTestISub(const char *pszSubTest);
649
650	/**
651	* Format string version of RTTestSub.
652	*
653	* See RTTestSub for details.
654	*
655	* @returns Number of chars printed.
656	* @param pszSubTestFmt The sub-test name format string.
657	* @param ... Arguments.
658	*/
659	RTR3DECL(int) RTTestISubF(const char *pszSubTestFmt, ...);
660
661	/**
662	* Format string version of RTTestSub.
663	*
664	* See RTTestSub for details.
665	*
666	* @returns Number of chars printed.
667	* @param pszSubTestFmt The sub-test name format string.
668	* @param va Arguments.
669	*/
670	RTR3DECL(int) RTTestISubV(const char *pszSubTestFmt, va_list va);
671
672	/**
673	* Completes a sub-test.
674	*
675	* @returns Number of chars printed.
676	*/
677	RTR3DECL(int) RTTestISubDone(void);
678
679	/**
680	* Prints an extended PASSED message, optional.
681	*
682	* This does not conclude the sub-test, it could be used to report the passing
683	* of a sub-sub-to-the-power-of-N-test.
684	*
685	* @returns IPRT status code.
686	* @param pszFormat The message. No trailing newline.
687	* @param va The arguments.
688	*/
689	RTR3DECL(int) RTTestIPassedV(const char *pszFormat, va_list va);
690
691	/**
692	* Prints an extended PASSED message, optional.
693	*
694	* This does not conclude the sub-test, it could be used to report the passing
695	* of a sub-sub-to-the-power-of-N-test.
696	*
697	* @returns IPRT status code.
698	* @param pszFormat The message. No trailing newline.
699	* @param ... The arguments.
700	*/
701	RTR3DECL(int) RTTestIPassed(const char *pszFormat, ...);
702
703	/**
704	* Increments the error counter.
705	*
706	* @returns IPRT status code.
707	*/
708	RTR3DECL(int) RTTestIErrorInc(void);
709
710	/**
711	* Get the current error count.
712	*
713	* @returns The error counter, UINT32_MAX if no valid test handle.
714	*/
715	RTR3DECL(uint32_t) RTTestIErrorCount(void);
716
717	/**
718	* Increments the error counter and prints a failure message.
719	*
720	* @returns IPRT status code.
721	* @param pszFormat The message. No trailing newline.
722	* @param va The arguments.
723	*/
724	RTR3DECL(int) RTTestIFailedV(const char *pszFormat, va_list va);
725
726	/**
727	* Increments the error counter and prints a failure message.
728	*
729	* @returns IPRT status code.
730	* @param pszFormat The message. No trailing newline.
731	* @param ... The arguments.
732	*/
733	RTR3DECL(int) RTTestIFailed(const char *pszFormat, ...);
734
735	/**
736	* Same as RTTestIPrintfV with RTTESTLVL_FAILURE.
737	*
738	* @returns Number of chars printed.
739	* @param pszFormat The message.
740	* @param va Arguments.
741	*/
742	RTR3DECL(int) RTTestIFailureDetailsV(const char *pszFormat, va_list va);
743
744	/**
745	* Same as RTTestIPrintf with RTTESTLVL_FAILURE.
746	*
747	* @returns Number of chars printed.
748	* @param pszFormat The message.
749	* @param ... Arguments.
750	*/
751	RTR3DECL(int) RTTestIFailureDetails(const char *pszFormat, ...);
752
753
754	/** @def RTTESTI_CHECK
755	* Check whether a boolean expression holds true.
756	*
757	* If the expression is false, call RTTestIFailed giving the line number and
758	* expression.
759	*
760	* @param expr The expression to evaluate.
761	*/
762	#define RTTESTI_CHECK(expr) \
763	do { if (!(expr)) { \
764	RTTestIFailed("line %u: %s", __LINE__, #expr); \
765	} \
766	} while (0)
767	/** @def RTTESTI_CHECK_RET
768	* Check whether a boolean expression holds true, returns on false.
769	*
770	* If the expression is false, call RTTestIFailed giving the line number and
771	* expression.
772	*
773	* @param expr The expression to evaluate.
774	* @param rcRet What to return on failure.
775	*/
776	#define RTTESTI_CHECK_RET(expr, rcRet) \
777	do { if (!(expr)) { \
778	RTTestIFailed("line %u: %s", __LINE__, #expr); \
779	return (rcRet); \
780	} \
781	} while (0)
782	/** @def RTTESTI_CHECK_RETV
783	* Check whether a boolean expression holds true, returns void on false.
784	*
785	* If the expression is false, call RTTestIFailed giving the line number and
786	* expression.
787	*
788	* @param expr The expression to evaluate.
789	*/
790	#define RTTESTI_CHECK_RETV(expr) \
791	do { if (!(expr)) { \
792	RTTestIFailed("line %u: %s", __LINE__, #expr); \
793	return; \
794	} \
795	} while (0)
796
797
798	/** @def RTTESTI_CHECK_MSG
799	* Check whether a boolean expression holds true.
800	*
801	* If the expression is false, call RTTestIFailed giving the line number and
802	* expression.
803	*
804	* @param expr The expression to evaluate.
805	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
806	* parenthesis.
807	*/
808	#define RTTESTI_CHECK_MSG(expr, DetailsArgs) \
809	do { if (!(expr)) { \
810	RTTestIFailed("line %u: %s", __LINE__, #expr); \
811	RTTestIFailureDetails DetailsArgs; \
812	} \
813	} while (0)
814	/** @def RTTESTI_CHECK_MSG_RET
815	* Check whether a boolean expression holds true, returns on false.
816	*
817	* If the expression is false, call RTTestIFailed giving the line number and
818	* expression.
819	*
820	* @param expr The expression to evaluate.
821	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
822	* parenthesis.
823	* @param rcRet What to return on failure.
824	*/
825	#define RTTESTI_CHECK_MSG_RET(expr, DetailsArgs, rcRet) \
826	do { if (!(expr)) { \
827	RTTestIFailed("line %u: %s", __LINE__, #expr); \
828	RTTestIFailureDetails DetailsArgs; \
829	return (rcRet); \
830	} \
831	} while (0)
832	/** @def RTTESTI_CHECK_MSG_RET
833	* Check whether a boolean expression holds true, returns void on false.
834	*
835	* If the expression is false, call RTTestIFailed giving the line number and
836	* expression.
837	*
838	* @param expr The expression to evaluate.
839	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
840	* parenthesis.
841	*/
842	#define RTTESTI_CHECK_MSG_RETV(expr, DetailsArgs) \
843	do { if (!(expr)) { \
844	RTTestIFailed("line %u: %s", __LINE__, #expr); \
845	RTTestIFailureDetails DetailsArgs; \
846	return; \
847	} \
848	} while (0)
849
850
851	/** @def RTTESTI_CHECK_RC
852	* Check whether an expression returns a specific IPRT style status code.
853	*
854	* If a different status code is return, call RTTestIFailed giving the line
855	* number, expression, actual and expected status codes.
856	*
857	* @param rcExpr The expression resulting in an IPRT status code.
858	* @param rcExpect The expected return code. This may be referenced
859	* more than once by the macro.
860	*/
861	#define RTTESTI_CHECK_RC(rcExpr, rcExpect) \
862	do { \
863	int rcCheck = (rcExpr); \
864	if (rcCheck != (rcExpect)) { \
865	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
866	} \
867	} while (0)
868	/** @def RTTESTI_CHECK_RC_RET
869	* Check whether an expression returns a specific IPRT style status code.
870	*
871	* If a different status code is return, call RTTestIFailed giving the line
872	* number, expression, actual and expected status codes, then return.
873	*
874	* @param rcExpr The expression resulting in an IPRT status code.
875	* This will be assigned to a local rcCheck variable
876	* that can be used as return value.
877	* @param rcExpect The expected return code. This may be referenced
878	* more than once by the macro.
879	* @param rcRet The return code.
880	*/
881	#define RTTESTI_CHECK_RC_RET(rcExpr, rcExpect, rcRet) \
882	do { \
883	int rcCheck = (rcExpr); \
884	if (rcCheck != (rcExpect)) { \
885	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
886	return (rcRet); \
887	} \
888	} while (0)
889	/** @def RTTESTI_CHECK_RC_RETV
890	* Check whether an expression returns a specific IPRT style status code.
891	*
892	* If a different status code is return, call RTTestIFailed giving the line
893	* number, expression, actual and expected status codes, then return.
894	*
895	* @param rcExpr The expression resulting in an IPRT status code.
896	* @param rcExpect The expected return code. This may be referenced
897	* more than once by the macro.
898	*/
899	#define RTTESTI_CHECK_RC_RETV(rcExpr, rcExpect) \
900	do { \
901	int rcCheck = (rcExpr); \
902	if (rcCheck != (rcExpect)) { \
903	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
904	return; \
905	} \
906	} while (0)
907
908
909	/** @def RTTESTI_CHECK_RC_OK
910	* Check whether a IPRT style status code indicates success.
911	*
912	* If the status indicates failure, call RTTestIFailed giving the line number,
913	* expression and status code.
914	*
915	* @param rcExpr The expression resulting in an IPRT status code.
916	*/
917	#define RTTESTI_CHECK_RC_OK(rcExpr) \
918	do { \
919	int rcCheck = (rcExpr); \
920	if (RT_FAILURE(rcCheck)) { \
921	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
922	} \
923	} while (0)
924	/** @def RTTESTI_CHECK_RC_OK_RET
925	* Check whether a IPRT style status code indicates success.
926	*
927	* If the status indicates failure, call RTTestIFailed giving the line number,
928	* expression and status code, then return with the specified value.
929	*
930	* @param rcExpr The expression resulting in an IPRT status code.
931	* This will be assigned to a local rcCheck variable
932	* that can be used as return value.
933	* @param rcRet The return code.
934	*/
935	#define RTTESTI_CHECK_RC_OK_RET(rcExpr, rcRet) \
936	do { \
937	int rcCheck = (rcExpr); \
938	if (RT_FAILURE(rcCheck)) { \
939	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
940	return (rcRet); \
941	} \
942	} while (0)
943	/** @def RTTESTI_CHECK_RC_OK_RETV
944	* Check whether a IPRT style status code indicates success.
945	*
946	* If the status indicates failure, call RTTestIFailed giving the line number,
947	* expression and status code, then return.
948	*
949	* @param rcExpr The expression resulting in an IPRT status code.
950	*/
951	#define RTTESTI_CHECK_RC_OK_RETV(rcExpr) \
952	do { \
953	int rcCheck = (rcExpr); \
954	if (RT_FAILURE(rcCheck)) { \
955	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
956	return; \
957	} \
958	} while (0)
959
960	/** @} */
961
962
963	/** @} */
964
965	RT_C_DECLS_END
966
967	#endif
968

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

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

Download in other formats: