test.h@ 25003

Last change on this file since 25003 was 20605, checked in by vboxsync, 16 years ago
IPRT: Added RTTestInitAndCreate - a combination of RTR3Init and RTTestCreate.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 31.0 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 *pszReason, 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 va Arguments for the reason format string.
256	*/
257	RTR3DECL(int) RTTestSkipAndDestroy(RTTEST hTest, const char *pszReason, ...);
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 ... 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	* Increments the error counter and prints a failure message.
347	*
348	* @returns IPRT status code.
349	* @param hTest The test handle. If NIL_RTTEST we'll use the one
350	* associated with the calling thread.
351	* @param pszFormat The message. No trailing newline.
352	* @param va The arguments.
353	*/
354	RTR3DECL(int) RTTestFailedV(RTTEST hTest, const char *pszFormat, va_list va);
355
356	/**
357	* Increments the error counter and prints a failure message.
358	*
359	* @returns IPRT status code.
360	* @param hTest The test handle. If NIL_RTTEST we'll use the one
361	* associated with the calling thread.
362	* @param pszFormat The message. No trailing newline.
363	* @param ... The arguments.
364	*/
365	RTR3DECL(int) RTTestFailed(RTTEST hTest, const char *pszFormat, ...);
366
367	/**
368	* Same as RTTestPrintfV with RTTESTLVL_FAILURE.
369	*
370	* @returns Number of chars printed.
371	* @param hTest The test handle. If NIL_RTTEST we'll use the one
372	* associated with the calling thread.
373	* @param enmLevel Message importance level.
374	* @param pszFormat The message.
375	* @param va Arguments.
376	*/
377	RTR3DECL(int) RTTestFailureDetailsV(RTTEST hTest, const char *pszFormat, va_list va);
378
379	/**
380	* Same as RTTestPrintf with RTTESTLVL_FAILURE.
381	*
382	* @returns Number of chars printed.
383	* @param hTest The test handle. If NIL_RTTEST we'll use the one
384	* associated with the calling thread.
385	* @param enmLevel Message importance level.
386	* @param pszFormat The message.
387	* @param ... Arguments.
388	*/
389	RTR3DECL(int) RTTestFailureDetails(RTTEST hTest, const char *pszFormat, ...);
390
391
392	/** @def RTTEST_CHECK
393	* Check whether a boolean expression holds true.
394	*
395	* If the expression is false, call RTTestFailed giving the line number and expression.
396	*
397	* @param hTest The test handle.
398	* @param expr The expression to evaluate.
399	*/
400	#define RTTEST_CHECK(hTest, expr) \
401	do { if (!(expr)) { \
402	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
403	} \
404	} while (0)
405	/** @def RTTEST_CHECK_RET
406	* Check whether a boolean expression holds true, returns on false.
407	*
408	* If the expression is false, call RTTestFailed giving the line number and expression.
409	*
410	* @param hTest The test handle.
411	* @param expr The expression to evaluate.
412	* @param rcRet What to return on failure.
413	*/
414	#define RTTEST_CHECK_RET(hTest, expr, rcRet) \
415	do { if (!(expr)) { \
416	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
417	return (rcRet); \
418	} \
419	} while (0)
420	/** @def RTTEST_CHECK_RETV
421	* Check whether a boolean expression holds true, returns void on false.
422	*
423	* If the expression is false, call RTTestFailed giving the line number and expression.
424	*
425	* @param hTest The test handle.
426	* @param expr The expression to evaluate.
427	*/
428	#define RTTEST_CHECK_RETV(hTest, expr) \
429	do { if (!(expr)) { \
430	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
431	return; \
432	} \
433	} while (0)
434
435
436	/** @def RTTEST_CHECK_MSG
437	* Check whether a boolean expression holds true.
438	*
439	* If the expression is false, call RTTestFailed giving the line number and expression.
440	*
441	* @param hTest The test handle.
442	* @param expr The expression to evaluate.
443	* @param DetailsArgs Argument list for RTTestFailureDetails, including
444	* parenthesis.
445	*/
446	#define RTTEST_CHECK_MSG(hTest, expr, DetailsArgs) \
447	do { if (!(expr)) { \
448	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
449	RTTestFailureDetails DetailsArgs; \
450	} \
451	} while (0)
452	/** @def RTTEST_CHECK_MSG_RET
453	* Check whether a boolean expression holds true, returns on false.
454	*
455	* If the expression is false, call RTTestFailed giving the line number and expression.
456	*
457	* @param hTest The test handle.
458	* @param expr The expression to evaluate.
459	* @param DetailsArgs Argument list for RTTestFailureDetails, including
460	* parenthesis.
461	* @param rcRet What to return on failure.
462	*/
463	#define RTTEST_CHECK_MSG_RET(hTest, expr, DetailsArgs, rcRet) \
464	do { if (!(expr)) { \
465	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
466	RTTestFailureDetails DetailsArgs; \
467	return (rcRet); \
468	} \
469	} while (0)
470	/** @def RTTEST_CHECK_MSG_RET
471	* Check whether a boolean expression holds true, returns void on false.
472	*
473	* If the expression is false, call RTTestFailed giving the line number and expression.
474	*
475	* @param hTest The test handle.
476	* @param expr The expression to evaluate.
477	* @param DetailsArgs Argument list for RTTestFailureDetails, including
478	* parenthesis.
479	*/
480	#define RTTEST_CHECK_MSG_RETV(hTest, expr, DetailsArgs) \
481	do { if (!(expr)) { \
482	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
483	RTTestFailureDetails DetailsArgs; \
484	return; \
485	} \
486	} while (0)
487
488
489	/** @def RTTEST_CHECK_RC
490	* Check whether an expression returns a specific IPRT style status code.
491	*
492	* If a different status code is return, call RTTestFailed giving the line
493	* number, expression, actual and expected status codes.
494	*
495	* @param hTest The test handle.
496	* @param rcExpr The expression resulting an IPRT status code.
497	* @param rcExpect The expected return code. This may be referenced
498	* more than once by the macro.
499	*/
500	#define RTTEST_CHECK_RC(hTest, rcExpr, rcExpect) \
501	do { \
502	int rcCheck = (rcExpr); \
503	if (rcCheck != (rcExpect)) { \
504	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
505	} \
506	} while (0)
507	/** @def RTTEST_CHECK_RC_RET
508	* Check whether an expression returns a specific IPRT style status code.
509	*
510	* If a different status code is return, call RTTestFailed giving the line
511	* number, expression, actual and expected status codes, then return.
512	*
513	* @param hTest The test handle.
514	* @param rcExpr The expression resulting an IPRT status code.
515	* @param rcExpect The expected return code. This may be referenced
516	* more than once by the macro.
517	* @param rcRet The return code.
518	*/
519	#define RTTEST_CHECK_RC_RET(hTest, rcExpr, rcExpect, rcRet) \
520	do { \
521	int rcCheck = (rcExpr); \
522	if (rcCheck != (rcExpect)) { \
523	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
524	return (rcRet); \
525	} \
526	} while (0)
527	/** @def RTTEST_CHECK_RC_RETV
528	* Check whether an expression returns a specific IPRT style status code.
529	*
530	* If a different status code is return, call RTTestFailed giving the line
531	* number, expression, actual and expected status codes, then return.
532	*
533	* @param hTest The test handle.
534	* @param rcExpr The expression resulting an IPRT status code.
535	* @param rcExpect The expected return code. This may be referenced
536	* more than once by the macro.
537	*/
538	#define RTTEST_CHECK_RC_RETV(hTest, rcExpr, rcExpect) \
539	do { \
540	int rcCheck = (rcExpr); \
541	if (rcCheck != (rcExpect)) { \
542	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
543	return; \
544	} \
545	} while (0)
546
547
548	/** @def RTTEST_CHECK_RC_OK
549	* Check whether a IPRT style status code indicates success.
550	*
551	* If the status indicates failure, call RTTestFailed giving the line number,
552	* expression and status code.
553	*
554	* @param hTest The test handle.
555	* @param rcExpr The expression resulting an IPRT status code.
556	*/
557	#define RTTEST_CHECK_RC_OK(hTest, rcExpr) \
558	do { \
559	int rcCheck = (rcExpr); \
560	if (RT_FAILURE(rcCheck)) { \
561	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rc); \
562	} \
563	} while (0)
564	/** @def RTTEST_CHECK_RC_OK_RET
565	* Check whether a IPRT style status code indicates success.
566	*
567	* If the status indicates failure, call RTTestFailed giving the line number,
568	* expression and status code, then return with the specified value.
569	*
570	* @param hTest The test handle.
571	* @param rcExpr The expression resulting an IPRT status code.
572	* @param rcRet The return code.
573	*/
574	#define RTTEST_CHECK_RC_OK_RET(hTest, rcExpr, rcRet) \
575	do { \
576	int rcCheck = (rcExpr); \
577	if (RT_FAILURE(rcCheck)) { \
578	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rc); \
579	return (rcRet); \
580	} \
581	} while (0)
582	/** @def RTTEST_CHECK_RC_OK_RETV
583	* Check whether a IPRT style status code indicates success.
584	*
585	* If the status indicates failure, call RTTestFailed giving the line number,
586	* expression and status code, then return.
587	*
588	* @param hTest The test handle.
589	* @param rcExpr The expression resulting an IPRT status code.
590	*/
591	#define RTTEST_CHECK_RC_OK_RETV(hTest, rcExpr) \
592	do { \
593	int rcCheck = (rcExpr); \
594	if (RT_FAILURE(rcCheck)) { \
595	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rc); \
596	return; \
597	} \
598	} while (0)
599
600
601
602
603	/** @name Implicit Test Handle API Variation
604	* The test handle is retrieved from the test TLS entry of the calling thread.
605	* @{
606	*/
607
608	/**
609	* Test vprintf, makes sure lines are prefixed and so forth.
610	*
611	* @returns Number of chars printed.
612	* @param enmLevel Message importance level.
613	* @param pszFormat The message.
614	* @param va Arguments.
615	*/
616	RTR3DECL(int) RTTestIPrintfV(RTTESTLVL enmLevel, const char *pszFormat, va_list va);
617
618	/**
619	* Test printf, makes sure lines are prefixed and so forth.
620	*
621	* @returns Number of chars printed.
622	* @param enmLevel Message importance level.
623	* @param pszFormat The message.
624	* @param ... Arguments.
625	*/
626	RTR3DECL(int) RTTestIPrintf(RTTESTLVL enmLevel, const char *pszFormat, ...);
627
628	/**
629	* Starts a sub-test.
630	*
631	* This will perform an implicit RTTestSubDone() call if that has not been done
632	* since the last RTTestSub call.
633	*
634	* @returns Number of chars printed.
635	* @param pszSubTest The sub-test name.
636	*/
637	RTR3DECL(int) RTTestISub(const char *pszSubTest);
638
639	/**
640	* Format string version of RTTestSub.
641	*
642	* See RTTestSub for details.
643	*
644	* @returns Number of chars printed.
645	* @param pszSubTestFmt The sub-test name format string.
646	* @param ... Arguments.
647	*/
648	RTR3DECL(int) RTTestISubF(const char *pszSubTestFmt, ...);
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) RTTestISubV(const char *pszSubTestFmt, va_list va);
660
661	/**
662	* Completes a sub-test.
663	*
664	* @returns Number of chars printed.
665	*/
666	RTR3DECL(int) RTTestISubDone(void);
667
668	/**
669	* Prints an extended PASSED message, optional.
670	*
671	* This does not conclude the sub-test, it could be used to report the passing
672	* of a sub-sub-to-the-power-of-N-test.
673	*
674	* @returns IPRT status code.
675	* @param pszFormat The message. No trailing newline.
676	* @param va The arguments.
677	*/
678	RTR3DECL(int) RTTestIPassedV(const char *pszFormat, va_list va);
679
680	/**
681	* Prints an extended PASSED message, optional.
682	*
683	* This does not conclude the sub-test, it could be used to report the passing
684	* of a sub-sub-to-the-power-of-N-test.
685	*
686	* @returns IPRT status code.
687	* @param pszFormat The message. No trailing newline.
688	* @param ... The arguments.
689	*/
690	RTR3DECL(int) RTTestIPassed(const char *pszFormat, ...);
691
692	/**
693	* Increments the error counter.
694	*
695	* @returns IPRT status code.
696	*/
697	RTR3DECL(int) RTTestIErrorInc(void);
698
699	/**
700	* Increments the error counter and prints a failure message.
701	*
702	* @returns IPRT status code.
703	* @param pszFormat The message. No trailing newline.
704	* @param va The arguments.
705	*/
706	RTR3DECL(int) RTTestIFailedV(const char *pszFormat, va_list va);
707
708	/**
709	* Increments the error counter and prints a failure message.
710	*
711	* @returns IPRT status code.
712	* @param pszFormat The message. No trailing newline.
713	* @param ... The arguments.
714	*/
715	RTR3DECL(int) RTTestIFailed(const char *pszFormat, ...);
716
717	/**
718	* Same as RTTestIPrintfV with RTTESTLVL_FAILURE.
719	*
720	* @returns Number of chars printed.
721	* @param pszFormat The message.
722	* @param va Arguments.
723	*/
724	RTR3DECL(int) RTTestIFailureDetailsV(const char *pszFormat, va_list va);
725
726	/**
727	* Same as RTTestIPrintf with RTTESTLVL_FAILURE.
728	*
729	* @returns Number of chars printed.
730	* @param pszFormat The message.
731	* @param ... Arguments.
732	*/
733	RTR3DECL(int) RTTestIFailureDetails(const char *pszFormat, ...);
734
735
736	/** @def RTTESTI_CHECK
737	* Check whether a boolean expression holds true.
738	*
739	* If the expression is false, call RTTestIFailed giving the line number and
740	* expression.
741	*
742	* @param expr The expression to evaluate.
743	*/
744	#define RTTESTI_CHECK(expr) \
745	do { if (!(expr)) { \
746	RTTestIFailed("line %u: %s", __LINE__, #expr); \
747	} \
748	} while (0)
749	/** @def RTTESTI_CHECK_RET
750	* Check whether a boolean expression holds true, returns on false.
751	*
752	* If the expression is false, call RTTestIFailed giving the line number and
753	* expression.
754	*
755	* @param expr The expression to evaluate.
756	* @param rcRet What to return on failure.
757	*/
758	#define RTTESTI_CHECK_RET(expr, rcRet) \
759	do { if (!(expr)) { \
760	RTTestIFailed("line %u: %s", __LINE__, #expr); \
761	return (rcRet); \
762	} \
763	} while (0)
764	/** @def RTTESTI_CHECK_RETV
765	* Check whether a boolean expression holds true, returns void on false.
766	*
767	* If the expression is false, call RTTestIFailed giving the line number and
768	* expression.
769	*
770	* @param expr The expression to evaluate.
771	*/
772	#define RTTESTI_CHECK_RETV(expr) \
773	do { if (!(expr)) { \
774	RTTestIFailed("line %u: %s", __LINE__, #expr); \
775	return; \
776	} \
777	} while (0)
778
779
780	/** @def RTTESTI_CHECK_MSG
781	* Check whether a boolean expression holds true.
782	*
783	* If the expression is false, call RTTestIFailed giving the line number and
784	* expression.
785	*
786	* @param expr The expression to evaluate.
787	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
788	* parenthesis.
789	*/
790	#define RTTESTI_CHECK_MSG(expr, DetailsArgs) \
791	do { if (!(expr)) { \
792	RTTestIFailed("line %u: %s", __LINE__, #expr); \
793	RTTestIFailureDetails DetailsArgs; \
794	} \
795	} while (0)
796	/** @def RTTESTI_CHECK_MSG_RET
797	* Check whether a boolean expression holds true, returns on false.
798	*
799	* If the expression is false, call RTTestIFailed giving the line number and
800	* expression.
801	*
802	* @param expr The expression to evaluate.
803	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
804	* parenthesis.
805	* @param rcRet What to return on failure.
806	*/
807	#define RTTESTI_CHECK_MSG_RET(expr, DetailsArgs, rcRet) \
808	do { if (!(expr)) { \
809	RTTestIFailed("line %u: %s", __LINE__, #expr); \
810	RTTestIFailureDetails DetailsArgs; \
811	return (rcRet); \
812	} \
813	} while (0)
814	/** @def RTTESTI_CHECK_MSG_RET
815	* Check whether a boolean expression holds true, returns void 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	*/
824	#define RTTESTI_CHECK_MSG_RETV(expr, DetailsArgs) \
825	do { if (!(expr)) { \
826	RTTestIFailed("line %u: %s", __LINE__, #expr); \
827	RTTestIFailureDetails DetailsArgs; \
828	return; \
829	} \
830	} while (0)
831
832
833	/** @def RTTESTI_CHECK_RC
834	* Check whether an expression returns a specific IPRT style status code.
835	*
836	* If a different status code is return, call RTTestIFailed giving the line
837	* number, expression, actual and expected status codes.
838	*
839	* @param rcExpr The expression resulting an IPRT status code.
840	* @param rcExpect The expected return code. This may be referenced
841	* more than once by the macro.
842	*/
843	#define RTTESTI_CHECK_RC(rcExpr, rcExpect) \
844	do { \
845	int rcCheck = (rcExpr); \
846	if (rcCheck != (rcExpect)) { \
847	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
848	} \
849	} while (0)
850	/** @def RTTESTI_CHECK_RC_RET
851	* Check whether an expression returns a specific IPRT style status code.
852	*
853	* If a different status code is return, call RTTestIFailed giving the line
854	* number, expression, actual and expected status codes, then return.
855	*
856	* @param rcExpr The expression resulting an IPRT status code.
857	* @param rcExpect The expected return code. This may be referenced
858	* more than once by the macro.
859	* @param rcRet The return code.
860	*/
861	#define RTTESTI_CHECK_RC_RET(rcExpr, rcExpect, rcRet) \
862	do { \
863	int rcCheck = (rcExpr); \
864	if (rcCheck != (rcExpect)) { \
865	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
866	return (rcRet); \
867	} \
868	} while (0)
869	/** @def RTTESTI_CHECK_RC_RETV
870	* Check whether an expression returns a specific IPRT style status code.
871	*
872	* If a different status code is return, call RTTestIFailed giving the line
873	* number, expression, actual and expected status codes, then return.
874	*
875	* @param rcExpr The expression resulting an IPRT status code.
876	* @param rcExpect The expected return code. This may be referenced
877	* more than once by the macro.
878	*/
879	#define RTTESTI_CHECK_RC_RETV(rcExpr, rcExpect) \
880	do { \
881	int rcCheck = (rcExpr); \
882	if (rcCheck != (rcExpect)) { \
883	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
884	return; \
885	} \
886	} while (0)
887
888
889	/** @def RTTESTI_CHECK_RC_OK
890	* Check whether a IPRT style status code indicates success.
891	*
892	* If the status indicates failure, call RTTestIFailed giving the line number,
893	* expression and status code.
894	*
895	* @param rcExpr The expression resulting an IPRT status code.
896	*/
897	#define RTTESTI_CHECK_RC_OK(rcExpr) \
898	do { \
899	int rcCheck = (rcExpr); \
900	if (RT_FAILURE(rcCheck)) { \
901	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
902	} \
903	} while (0)
904	/** @def RTTESTI_CHECK_RC_OK_RET
905	* Check whether a IPRT style status code indicates success.
906	*
907	* If the status indicates failure, call RTTestIFailed giving the line number,
908	* expression and status code, then return with the specified value.
909	*
910	* @param rcExpr The expression resulting an IPRT status code.
911	* @param rcRet The return code.
912	*/
913	#define RTTESTI_CHECK_RC_OK_RET(rcExpr, rcRet) \
914	do { \
915	int rcCheck = (rcExpr); \
916	if (RT_FAILURE(rcCheck)) { \
917	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
918	return (rcRet); \
919	} \
920	} while (0)
921	/** @def RTTESTI_CHECK_RC_OK_RETV
922	* Check whether a IPRT style status code indicates success.
923	*
924	* If the status indicates failure, call RTTestIFailed giving the line number,
925	* expression and status code, then return.
926	*
927	* @param rcExpr The expression resulting an IPRT status code.
928	*/
929	#define RTTESTI_CHECK_RC_OK_RETV(rcExpr) \
930	do { \
931	int rcCheck = (rcExpr); \
932	if (RT_FAILURE(rcCheck)) { \
933	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
934	return; \
935	} \
936	} while (0)
937
938	/** @} */
939
940
941	/** @} */
942
943	RT_C_DECLS_END
944
945	#endif
946

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

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

Download in other formats: