test.h@ 47572

Last change on this file since 47572 was 46298, checked in by vboxsync, 12 years ago
RTTest: Added some new features/APIs for forwarding bootsector test results.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 46.4 KB

Line
1	/** @file
2	* IPRT - Testcase Framework.
3	*/
4
5	/*
6	* Copyright (C) 2009-2013 Oracle Corporation
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
26	#ifndef ___iprt_test_h
27	#define ___iprt_test_h
28
29	#include <iprt/cdefs.h>
30	#include <iprt/types.h>
31	#include <iprt/stdarg.h>
32	#include <iprt/assert.h>
33
34	RT_C_DECLS_BEGIN
35
36	/** @defgroup grp_rt_test RTTest - Testcase Framework.
37	* @ingroup grp_rt
38	* @{
39	*/
40
41	/** A test handle. */
42	typedef R3PTRTYPE(struct RTTESTINT *) RTTEST;
43	/** A pointer to a test handle. */
44	typedef RTTEST *PRTTEST;
45	/** A const pointer to a test handle. */
46	typedef RTTEST const *PCRTTEST;
47
48	/** A NIL Test handle. */
49	#define NIL_RTTEST ((RTTEST)0)
50
51	/**
52	* Test message importance level.
53	*/
54	typedef enum RTTESTLVL
55	{
56	/** Invalid 0. */
57	RTTESTLVL_INVALID = 0,
58	/** Message should always be printed. */
59	RTTESTLVL_ALWAYS,
60	/** Failure message. */
61	RTTESTLVL_FAILURE,
62	/** Sub-test banner. */
63	RTTESTLVL_SUB_TEST,
64	/** Info message. */
65	RTTESTLVL_INFO,
66	/** Debug message. */
67	RTTESTLVL_DEBUG,
68	/** The last (invalid). */
69	RTTESTLVL_END
70	} RTTESTLVL;
71
72
73	/**
74	* Creates a test instance.
75	*
76	* @returns IPRT status code.
77	* @param pszTest The test name.
78	* @param phTest Where to store the test instance handle.
79	*/
80	RTR3DECL(int) RTTestCreate(const char *pszTest, PRTTEST phTest);
81
82	/** @name RTTEST_C_XXX - Flags for RTTestCreateEx.
83	* @{ */
84	/** Whether to check the IPRT_TEST_XXX variables when constructing the
85	* instance. The following environment variables get checks:
86	*
87	* - IPRT_TEST_MAX_LEVEL: String value indicating which level.
88	* The env. var. is applied if the program specified the default level
89	* (by passing RTTESTLVL_INVALID).
90	*
91	* - IPRT_TEST_PIPE: The native pipe/fifo handle to write XML
92	* results to.
93	* The env. var. is applied if iNativeTestPipe is -1.
94	*
95	* - IPRT_TEST_FILE: Path to file/named-pipe/fifo/whatever to
96	* write XML results to.
97	* The env. var. is applied if the program specified a NULL path, it is
98	* not applied if the program hands us an empty string.
99	*
100	* - IPRT_TEST_OMIT_TOP_TEST: If present, this makes the XML output omit
101	* the top level test element.
102	* The env. var is applied when present.
103	*
104	*/
105	#define RTTEST_C_USE_ENV RT_BIT(0)
106	/** Whether to omit the top test in the XML. */
107	#define RTTEST_C_XML_OMIT_TOP_TEST RT_BIT(1)
108	/** Whether to delay the top test XML element until testing commences. */
109	#define RTTEST_C_XML_DELAY_TOP_TEST RT_BIT(2)
110	/** Whether to try install the test instance in the test TLS slot. Setting
111	* this flag is incompatible with using the RTTestIXxxx variant of the API. */
112	#define RTTEST_C_NO_TLS RT_BIT(3)
113	/** Mask containing the valid bits. */
114	#define RTTEST_C_VALID_MASK UINT32_C(0x0000000f)
115	/** @} */
116
117
118	/**
119	* Creates a test instance.
120	*
121	* @returns IPRT status code.
122	* @param pszTest The test name.
123	* @param pszXmlFile The XML output file/pipe/whatever.
124	* @param fFlags Flags, see RTTEST_C_XXX.
125	* @param enmMaxLevel The max message level. Use RTTESTLVL_INVALID for
126	* the default output level or one from the
127	* environment. If specified, the environment variable
128	* will not be able to override it.
129	* @param iNativeTestPipe Native handle to a test pipe. -1 if not interested.
130	* @param pszXmlFile The XML output file name. If NULL the environment
131	* may be used. To selectively avoid that, pass an
132	* empty string.
133	* @param phTest Where to store the test instance handle.
134	*
135	* @note At the moment, we don't fail if @a pszXmlFile or @a iNativeTestPipe
136	* fails to open. This may change later.
137	*/
138	RTR3DECL(int) RTTestCreateEx(const char *pszTest, uint32_t fFlags, RTTESTLVL enmMaxLevel,
139	RTHCINTPTR iNativeTestPipe, const char *pszXmlFile, PRTTEST phTest);
140
141	/**
142	* Initializes IPRT and creates a test instance.
143	*
144	* Typical usage is:
145	* @code
146	int main(int argc, char **argv)
147	{
148	RTTEST hTest;
149	int rc = RTTestInitAndCreate("tstSomething", &hTest);
150	if (rc)
151	return rc;
152	...
153	}
154	@endcode
155	*
156	* @returns RTEXITCODE_SUCCESS on success. On failure an error message is
157	* printed and a suitable exit code is return.
158	*
159	* @param pszTest The test name.
160	* @param phTest Where to store the test instance handle.
161	*/
162	RTR3DECL(RTEXITCODE) RTTestInitAndCreate(const char *pszTest, PRTTEST phTest);
163
164	/**
165	* Variant of RTTestInitAndCreate that includes IPRT init flags and argument
166	* vectors.
167	*
168	* @returns RTEXITCODE_SUCCESS on success. On failure an error message is
169	* printed and a suitable exit code is return.
170	*
171	* @param cArgs Pointer to the argument count.
172	* @param ppapszArgs Pointer to the argument vector pointer.
173	* @param fRtInit Flags, see RTR3INIT_XXX.
174	* @param pszTest The test name.
175	* @param phTest Where to store the test instance handle.
176	*/
177	RTR3DECL(RTEXITCODE) RTTestInitExAndCreate(int cArgs, char **papszArgs, uint32_t fRtInit, const char pszTest, PRTTEST phTest);
178
179	/**
180	* Destroys a test instance previously created by RTTestCreate.
181	*
182	* @returns IPRT status code.
183	* @param hTest The test handle. NIL_RTTEST is ignored.
184	*/
185	RTR3DECL(int) RTTestDestroy(RTTEST hTest);
186
187	/**
188	* Changes the default test instance for the calling thread.
189	*
190	* @returns IPRT status code.
191	*
192	* @param hNewDefaultTest The new default test. NIL_RTTEST is fine.
193	* @param phOldTest Where to store the old test handle. Optional.
194	*/
195	RTR3DECL(int) RTTestSetDefault(RTTEST hNewDefaultTest, PRTTEST phOldTest);
196
197	/**
198	* Changes the test case name.
199	*
200	* @returns IRPT status code.
201	* @param hTest The test handle. If NIL_RTTEST we'll use the one
202	* associated with the calling thread.
203	* @param pszName The new test case name. Empty string is not accepted,
204	* nor are strings longer than 127 chars. Keep it short
205	* but descriptive.
206	*/
207	RTR3DECL(int) RTTestChangeName(RTTEST hTest, const char *pszName);
208
209	/**
210	* Allocate a block of guarded memory.
211	*
212	* @returns IPRT status code.
213	* @param hTest The test handle. If NIL_RTTEST we'll use the one
214	* associated with the calling thread.
215	* @param cb The amount of memory to allocate.
216	* @param cbAlign The alignment of the returned block.
217	* @param fHead Head or tail optimized guard.
218	* @param ppvUser Where to return the pointer to the block.
219	*/
220	RTR3DECL(int) RTTestGuardedAlloc(RTTEST hTest, size_t cb, uint32_t cbAlign, bool fHead, void **ppvUser);
221
222	/**
223	* Allocates a block of guarded memory where the guarded is immediately after
224	* the user memory.
225	*
226	* @returns Pointer to the allocated memory. NULL on failure.
227	* @param hTest The test handle. If NIL_RTTEST we'll use the one
228	* associated with the calling thread.
229	* @param cb The amount of memory to allocate.
230	*/
231	RTR3DECL(void *) RTTestGuardedAllocTail(RTTEST hTest, size_t cb);
232
233	/**
234	* Allocates a block of guarded memory where the guarded is right in front of
235	* the user memory.
236	*
237	* @returns Pointer to the allocated memory. NULL on failure.
238	* @param hTest The test handle. If NIL_RTTEST we'll use the one
239	* associated with the calling thread.
240	* @param cb The amount of memory to allocate.
241	*/
242	RTR3DECL(void *) RTTestGuardedAllocHead(RTTEST hTest, size_t cb);
243
244	/**
245	* Frees a block of guarded memory.
246	*
247	* @returns IPRT status code.
248	* @param hTest The test handle. If NIL_RTTEST we'll use the one
249	* associated with the calling thread.
250	* @param pv The memory. NULL is ignored.
251	*/
252	RTR3DECL(int) RTTestGuardedFree(RTTEST hTest, void *pv);
253
254	/**
255	* Test vprintf making sure the output starts on a new line.
256	*
257	* @returns Number of chars printed.
258	* @param hTest The test handle. If NIL_RTTEST we'll use the one
259	* associated with the calling thread.
260	* @param enmLevel Message importance level.
261	* @param pszFormat The message.
262	* @param va Arguments.
263	*/
264	RTR3DECL(int) RTTestPrintfNlV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va);
265
266	/**
267	* Test printf making sure the output starts on a new line.
268	*
269	* @returns Number of chars printed.
270	* @param hTest The test handle. If NIL_RTTEST we'll use the one
271	* associated with the calling thread.
272	* @param enmLevel Message importance level.
273	* @param pszFormat The message.
274	* @param ... Arguments.
275	*/
276	RTR3DECL(int) RTTestPrintfNl(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...);
277
278	/**
279	* Test vprintf, makes sure lines are prefixed and so forth.
280	*
281	* @returns Number of chars printed.
282	* @param hTest The test handle. If NIL_RTTEST we'll use the one
283	* associated with the calling thread.
284	* @param enmLevel Message importance level.
285	* @param pszFormat The message.
286	* @param va Arguments.
287	*/
288	RTR3DECL(int) RTTestPrintfV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va);
289
290	/**
291	* Test printf, makes sure lines are prefixed and so forth.
292	*
293	* @returns Number of chars printed.
294	* @param hTest The test handle. If NIL_RTTEST we'll use the one
295	* associated with the calling thread.
296	* @param enmLevel Message importance level.
297	* @param pszFormat The message.
298	* @param ... Arguments.
299	*/
300	RTR3DECL(int) RTTestPrintf(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...);
301
302	/**
303	* Prints the test banner.
304	*
305	* @returns Number of chars printed.
306	* @param hTest The test handle. If NIL_RTTEST we'll use the one
307	* associated with the calling thread.
308	*/
309	RTR3DECL(int) RTTestBanner(RTTEST hTest);
310
311	/**
312	* Summaries the test, destroys the test instance and return an exit code.
313	*
314	* @returns Test program exit code.
315	* @param hTest The test handle. If NIL_RTTEST we'll use the one
316	* associated with the calling thread.
317	*/
318	RTR3DECL(RTEXITCODE) RTTestSummaryAndDestroy(RTTEST hTest);
319
320	/**
321	* Skips the test, destroys the test instance and return an exit code.
322	*
323	* @returns Test program exit code.
324	* @param hTest The test handle. If NIL_RTTEST we'll use the one
325	* associated with the calling thread.
326	* @param pszReasonFmt Text explaining why, optional (NULL).
327	* @param va Arguments for the reason format string.
328	*/
329	RTR3DECL(RTEXITCODE) RTTestSkipAndDestroyV(RTTEST hTest, const char *pszReasonFmt, va_list va);
330
331	/**
332	* Skips the test, destroys the test instance and return an exit code.
333	*
334	* @returns Test program exit code.
335	* @param hTest The test handle. If NIL_RTTEST we'll use the one
336	* associated with the calling thread.
337	* @param pszReasonFmt Text explaining why, optional (NULL).
338	* @param ... Arguments for the reason format string.
339	*/
340	RTR3DECL(RTEXITCODE) RTTestSkipAndDestroy(RTTEST hTest, const char *pszReasonFmt, ...);
341
342	/**
343	* Starts a sub-test.
344	*
345	* This will perform an implicit RTTestSubDone() call if that has not been done
346	* since the last RTTestSub call.
347	*
348	* @returns Number of chars printed.
349	* @param hTest The test handle. If NIL_RTTEST we'll use the one
350	* associated with the calling thread.
351	* @param pszSubTest The sub-test name.
352	*/
353	RTR3DECL(int) RTTestSub(RTTEST hTest, const char *pszSubTest);
354
355	/**
356	* Format string version of RTTestSub.
357	*
358	* See RTTestSub for details.
359	*
360	* @returns Number of chars printed.
361	* @param hTest The test handle. If NIL_RTTEST we'll use the one
362	* associated with the calling thread.
363	* @param pszSubTestFmt The sub-test name format string.
364	* @param ... Arguments.
365	*/
366	RTR3DECL(int) RTTestSubF(RTTEST hTest, const char *pszSubTestFmt, ...);
367
368	/**
369	* Format string version of RTTestSub.
370	*
371	* See RTTestSub for details.
372	*
373	* @returns Number of chars printed.
374	* @param hTest The test handle. If NIL_RTTEST we'll use the one
375	* associated with the calling thread.
376	* @param pszSubTestFmt The sub-test name format string.
377	* @param va Arguments.
378	*/
379	RTR3DECL(int) RTTestSubV(RTTEST hTest, const char *pszSubTestFmt, va_list va);
380
381	/**
382	* Completes a sub-test.
383	*
384	* @returns Number of chars printed, negative numbers are IPRT error codes.
385	* @param hTest The test handle. If NIL_RTTEST we'll use the one
386	* associated with the calling thread.
387	*/
388	RTR3DECL(int) RTTestSubDone(RTTEST hTest);
389
390	/**
391	* Prints an extended PASSED message, optional.
392	*
393	* This does not conclude the sub-test, it could be used to report the passing
394	* of a sub-sub-to-the-power-of-N-test.
395	*
396	* @returns Number of chars printed, negative numbers are IPRT error codes.
397	* @param hTest The test handle. If NIL_RTTEST we'll use the one
398	* associated with the calling thread.
399	* @param pszFormat The message. No trailing newline.
400	* @param va The arguments.
401	*/
402	RTR3DECL(int) RTTestPassedV(RTTEST hTest, const char *pszFormat, va_list va);
403
404	/**
405	* Prints an extended PASSED message, optional.
406	*
407	* This does not conclude the sub-test, it could be used to report the passing
408	* of a sub-sub-to-the-power-of-N-test.
409	*
410	* @returns Number of chars printed, negative numbers are IPRT error codes.
411	* @param hTest The test handle. If NIL_RTTEST we'll use the one
412	* associated with the calling thread.
413	* @param pszFormat The message. No trailing newline.
414	* @param ... The arguments.
415	*/
416	RTR3DECL(int) RTTestPassed(RTTEST hTest, const char *pszFormat, ...);
417
418	/**
419	* Marks the current test as 'SKIPPED' and optionally displays a message
420	* explaining why.
421	*
422	* @returns Number of chars printed, negative numbers are IPRT error codes.
423	* @param hTest The test handle. If NIL_RTTEST we'll use the one
424	* associated with the calling thread.
425	* @param pszFormat The message. No trailing newline. Can be NULL or empty.
426	* @param ... The arguments.
427	*/
428	RTR3DECL(int) RTTestSkipped(RTTEST hTest, const char *pszFormat, ...);
429
430	/**
431	* Marks the current test as 'SKIPPED' and optionally displays a message
432	* explaining why.
433	*
434	* @returns Number of chars printed, negative numbers are IPRT error codes.
435	* @param hTest The test handle. If NIL_RTTEST we'll use the one
436	* associated with the calling thread.
437	* @param pszFormat The message. No trailing newline. Can be NULL or empty.
438	* @param va The arguments.
439	*/
440	RTR3DECL(int) RTTestSkippedV(RTTEST hTest, const char *pszFormat, va_list va);
441
442
443	/**
444	* Value units.
445	*
446	* @remarks This is an interface where we have to be binary compatible with both
447	* older versions of this header and other components using the same
448	* contant values.
449	* @remarks When adding a new item:
450	* - Always add at the end of the list - do NOT group it.
451	* - Add it to rtTestUnitName in r3/test.cpp.
452	* - include/VBox/VMMDevTesting.h (VMMDEV_TESTING_UNIT_XXX).
453	* - Add it to g_aszBs2TestUnitNames in
454	* TestSuite/bootsectors/bootsector2-common-routines.mac.
455	*
456	*/
457	typedef enum RTTESTUNIT
458	{
459	/** The customary invalid zero value. */
460	RTTESTUNIT_INVALID = 0,
461
462	RTTESTUNIT_PCT, /*< Percentage (10^-2). /
463	RTTESTUNIT_BYTES, /*< Bytes. /
464	RTTESTUNIT_BYTES_PER_SEC, /*< Bytes per second. /
465	RTTESTUNIT_KILOBYTES, /*< Kilobytes. /
466	RTTESTUNIT_KILOBYTES_PER_SEC, /*< Kilobytes per second. /
467	RTTESTUNIT_MEGABYTES, /*< Megabytes. /
468	RTTESTUNIT_MEGABYTES_PER_SEC, /*< Megabytes per second. /
469	RTTESTUNIT_PACKETS, /*< Packets. /
470	RTTESTUNIT_PACKETS_PER_SEC, /*< Packets per second. /
471	RTTESTUNIT_FRAMES, /*< Frames. /
472	RTTESTUNIT_FRAMES_PER_SEC, /*< Frames per second. /
473	RTTESTUNIT_OCCURRENCES, /*< Occurrences. /
474	RTTESTUNIT_OCCURRENCES_PER_SEC, /*< Occurrences per second. /
475	RTTESTUNIT_CALLS, /*< Calls. /
476	RTTESTUNIT_CALLS_PER_SEC, /*< Calls per second. /
477	RTTESTUNIT_ROUND_TRIP, /*< Round trips. /
478	RTTESTUNIT_SECS, /*< Seconds. /
479	RTTESTUNIT_MS, /*< Milliseconds. /
480	RTTESTUNIT_NS, /*< Nanoseconds. /
481	RTTESTUNIT_NS_PER_CALL, /*< Nanoseconds per call. /
482	RTTESTUNIT_NS_PER_FRAME, /*< Nanoseconds per frame. /
483	RTTESTUNIT_NS_PER_OCCURRENCE, /*< Nanoseconds per occurrence. /
484	RTTESTUNIT_NS_PER_PACKET, /*< Nanoseconds per frame. /
485	RTTESTUNIT_NS_PER_ROUND_TRIP, /*< Nanoseconds per round trip. /
486	RTTESTUNIT_INSTRS, /*< Instructions. /
487	RTTESTUNIT_INSTRS_PER_SEC, /*< Instructions per second. /
488	RTTESTUNIT_NONE, /*< No unit. /
489	RTTESTUNIT_PP1K, /*< Parts per thousand (10^-3). /
490	RTTESTUNIT_PP10K, /*< Parts per ten thousand (10^-4). /
491	RTTESTUNIT_PPM, /*< Parts per million (10^-6). /
492	RTTESTUNIT_PPB, /*< Parts per billion (10^-9). /
493
494	/** The end of valid units. */
495	RTTESTUNIT_END
496	} RTTESTUNIT;
497	AssertCompile(RTTESTUNIT_INSTRS == 0x19);
498	AssertCompile(RTTESTUNIT_NONE == 0x1b);
499
500	/**
501	* Report a named test result value.
502	*
503	* This is typically used for benchmarking but can be used for other purposes
504	* like reporting limits of some implementation. The value gets associated with
505	* the current sub test, the name must be unique within the sub test.
506	*
507	* @returns IPRT status code.
508	*
509	* @param hTest The test handle. If NIL_RTTEST we'll use the one
510	* associated with the calling thread.
511	* @param pszName The value name.
512	* @param u64Value The value.
513	* @param enmUnit The value unit.
514	*/
515	RTR3DECL(int) RTTestValue(RTTEST hTest, const char *pszName, uint64_t u64Value, RTTESTUNIT enmUnit);
516
517	/**
518	* Same as RTTestValue, except that the name is now a format string.
519	*
520	* @returns IPRT status code.
521	*
522	* @param hTest The test handle. If NIL_RTTEST we'll use the one
523	* associated with the calling thread.
524	* @param u64Value The value.
525	* @param enmUnit The value unit.
526	* @param pszNameFmt The value name format string.
527	* @param ... String arguments.
528	*/
529	RTR3DECL(int) RTTestValueF(RTTEST hTest, uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, ...);
530
531	/**
532	* Same as RTTestValue, except that the name is now a format string.
533	*
534	* @returns IPRT status code.
535	*
536	* @param hTest The test handle. If NIL_RTTEST we'll use the one
537	* associated with the calling thread.
538	* @param u64Value The value.
539	* @param enmUnit The value unit.
540	* @param pszNameFmt The value name format string.
541	* @param va_list String arguments.
542	*/
543	RTR3DECL(int) RTTestValueV(RTTEST hTest, uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, va_list va);
544
545	/**
546	* Increments the error counter.
547	*
548	* @returns IPRT status code.
549	* @param hTest The test handle. If NIL_RTTEST we'll use the one
550	* associated with the calling thread.
551	*/
552	RTR3DECL(int) RTTestErrorInc(RTTEST hTest);
553
554	/**
555	* Get the current error count.
556	*
557	* @returns The error counter, UINT32_MAX if no valid test handle.
558	* @param hTest The test handle. If NIL_RTTEST we'll use the one
559	* associated with the calling thread.
560	*/
561	RTR3DECL(uint32_t) RTTestErrorCount(RTTEST hTest);
562
563	/**
564	* Get the error count of the current sub test.
565	*
566	* @returns The error counter, UINT32_MAX if no valid test handle.
567	* @param hTest The test handle. If NIL_RTTEST we'll use the one
568	* associated with the calling thread.
569	*/
570	RTR3DECL(uint32_t) RTTestSubErrorCount(RTTEST hTest);
571
572	/**
573	* Increments the error counter and prints a failure message.
574	*
575	* @returns IPRT status code.
576	* @param hTest The test handle. If NIL_RTTEST we'll use the one
577	* associated with the calling thread.
578	* @param pszFormat The message. No trailing newline.
579	* @param va The arguments.
580	*/
581	RTR3DECL(int) RTTestFailedV(RTTEST hTest, const char *pszFormat, va_list va);
582
583	/**
584	* Increments the error counter and prints a failure message.
585	*
586	* @returns IPRT status code.
587	* @param hTest The test handle. If NIL_RTTEST we'll use the one
588	* associated with the calling thread.
589	* @param pszFormat The message. No trailing newline.
590	* @param ... The arguments.
591	*/
592	RTR3DECL(int) RTTestFailed(RTTEST hTest, const char *pszFormat, ...);
593
594	/**
595	* Same as RTTestPrintfV with RTTESTLVL_FAILURE.
596	*
597	* @returns Number of chars printed.
598	* @param hTest The test handle. If NIL_RTTEST we'll use the one
599	* associated with the calling thread.
600	* @param pszFormat The message.
601	* @param va Arguments.
602	*/
603	RTR3DECL(int) RTTestFailureDetailsV(RTTEST hTest, const char *pszFormat, va_list va);
604
605	/**
606	* Same as RTTestPrintf with RTTESTLVL_FAILURE.
607	*
608	* @returns Number of chars printed.
609	* @param hTest The test handle. If NIL_RTTEST we'll use the one
610	* associated with the calling thread.
611	* @param pszFormat The message.
612	* @param ... Arguments.
613	*/
614	RTR3DECL(int) RTTestFailureDetails(RTTEST hTest, const char *pszFormat, ...);
615
616
617	/** @def RTTEST_CHECK
618	* Check whether a boolean expression holds true.
619	*
620	* If the expression is false, call RTTestFailed giving the line number and expression.
621	*
622	* @param hTest The test handle.
623	* @param expr The expression to evaluate.
624	*/
625	#define RTTEST_CHECK(hTest, expr) \
626	do { if (!(expr)) { \
627	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
628	} \
629	} while (0)
630	/** @def RTTEST_CHECK_RET
631	* Check whether a boolean expression holds true, returns on false.
632	*
633	* If the expression is false, call RTTestFailed giving the line number and
634	* expression, then return @a rcRet.
635	*
636	* @param hTest The test handle.
637	* @param expr The expression to evaluate.
638	* @param rcRet What to return on failure.
639	*/
640	#define RTTEST_CHECK_RET(hTest, expr, rcRet) \
641	do { if (!(expr)) { \
642	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
643	return (rcRet); \
644	} \
645	} while (0)
646	/** @def RTTEST_CHECK_RETV
647	* Check whether a boolean expression holds true, returns void on false.
648	*
649	* If the expression is false, call RTTestFailed giving the line number and
650	* expression, then return void.
651	*
652	* @param hTest The test handle.
653	* @param expr The expression to evaluate.
654	*/
655	#define RTTEST_CHECK_RETV(hTest, expr) \
656	do { if (!(expr)) { \
657	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
658	return; \
659	} \
660	} while (0)
661	/** @def RTTEST_CHECK_BREAK
662	* Check whether a boolean expression holds true.
663	*
664	* If the expression is false, call RTTestFailed giving the line number and
665	* expression, then break.
666	*
667	* @param hTest The test handle.
668	* @param expr The expression to evaluate.
669	*/
670	#define RTTEST_CHECK_BREAK(hTest, expr) \
671	if (!(expr)) { \
672	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
673	break; \
674	} else do {} while (0)
675
676
677	/** @def RTTEST_CHECK_MSG
678	* Check whether a boolean expression holds true.
679	*
680	* If the expression is false, call RTTestFailed giving the line number and expression.
681	*
682	* @param hTest The test handle.
683	* @param expr The expression to evaluate.
684	* @param DetailsArgs Argument list for RTTestFailureDetails, including
685	* parenthesis.
686	*/
687	#define RTTEST_CHECK_MSG(hTest, expr, DetailsArgs) \
688	do { if (!(expr)) { \
689	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
690	RTTestFailureDetails DetailsArgs; \
691	} \
692	} while (0)
693	/** @def RTTEST_CHECK_MSG_RET
694	* Check whether a boolean expression holds true, returns on false.
695	*
696	* If the expression is false, call RTTestFailed giving the line number and expression.
697	*
698	* @param hTest The test handle.
699	* @param expr The expression to evaluate.
700	* @param DetailsArgs Argument list for RTTestFailureDetails, including
701	* parenthesis.
702	* @param rcRet What to return on failure.
703	*/
704	#define RTTEST_CHECK_MSG_RET(hTest, expr, DetailsArgs, rcRet) \
705	do { if (!(expr)) { \
706	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
707	RTTestFailureDetails DetailsArgs; \
708	return (rcRet); \
709	} \
710	} while (0)
711	/** @def RTTEST_CHECK_MSG_RET
712	* Check whether a boolean expression holds true, returns void on false.
713	*
714	* If the expression is false, call RTTestFailed giving the line number and expression.
715	*
716	* @param hTest The test handle.
717	* @param expr The expression to evaluate.
718	* @param DetailsArgs Argument list for RTTestFailureDetails, including
719	* parenthesis.
720	*/
721	#define RTTEST_CHECK_MSG_RETV(hTest, expr, DetailsArgs) \
722	do { if (!(expr)) { \
723	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
724	RTTestFailureDetails DetailsArgs; \
725	return; \
726	} \
727	} while (0)
728
729
730	/** @def RTTEST_CHECK_RC
731	* Check whether an expression returns a specific IPRT style status code.
732	*
733	* If a different status code is return, call RTTestFailed giving the line
734	* number, expression, actual and expected status codes.
735	*
736	* @param hTest The test handle.
737	* @param rcExpr The expression resulting in an IPRT status code.
738	* @param rcExpect The expected return code. This may be referenced
739	* more than once by the macro.
740	*/
741	#define RTTEST_CHECK_RC(hTest, rcExpr, rcExpect) \
742	do { \
743	int rcCheck = (rcExpr); \
744	if (rcCheck != (rcExpect)) { \
745	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
746	} \
747	} while (0)
748	/** @def RTTEST_CHECK_RC_RET
749	* Check whether an expression returns a specific IPRT style status code.
750	*
751	* If a different status code is return, call RTTestFailed giving the line
752	* number, expression, actual and expected status codes, then return.
753	*
754	* @param hTest The test handle.
755	* @param rcExpr The expression resulting in an IPRT status code.
756	* This will be assigned to a local rcCheck variable
757	* that can be used as return value.
758	* @param rcExpect The expected return code. This may be referenced
759	* more than once by the macro.
760	* @param rcRet The return code.
761	*/
762	#define RTTEST_CHECK_RC_RET(hTest, rcExpr, rcExpect, rcRet) \
763	do { \
764	int rcCheck = (rcExpr); \
765	if (rcCheck != (rcExpect)) { \
766	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
767	return (rcRet); \
768	} \
769	} while (0)
770	/** @def RTTEST_CHECK_RC_RETV
771	* Check whether an expression returns a specific IPRT style status code.
772	*
773	* If a different status code is return, call RTTestFailed giving the line
774	* number, expression, actual and expected status codes, then return.
775	*
776	* @param hTest The test handle.
777	* @param rcExpr The expression resulting in an IPRT status code.
778	* @param rcExpect The expected return code. This may be referenced
779	* more than once by the macro.
780	*/
781	#define RTTEST_CHECK_RC_RETV(hTest, rcExpr, rcExpect) \
782	do { \
783	int rcCheck = (rcExpr); \
784	if (rcCheck != (rcExpect)) { \
785	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
786	return; \
787	} \
788	} while (0)
789	/** @def RTTEST_CHECK_RC_BREAK
790	* Check whether an expression returns a specific IPRT style status code.
791	*
792	* If a different status code is return, call RTTestFailed giving the line
793	* number, expression, actual and expected status codes, then break.
794	*
795	* @param hTest The test handle.
796	* @param rcExpr The expression resulting in an IPRT status code.
797	* @param rcExpect The expected return code. This may be referenced
798	* more than once by the macro.
799	*/
800	#define RTTEST_CHECK_RC_BREAK(hTest, rcExpr, rcExpect) \
801	if (1) { \
802	int rcCheck = (rcExpr); \
803	if (rcCheck != (rcExpect)) { \
804	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
805	break; \
806	} \
807	} else do {} while (0)
808
809
810	/** @def RTTEST_CHECK_RC_OK
811	* Check whether a IPRT style status code indicates success.
812	*
813	* If the status indicates failure, call RTTestFailed giving the line number,
814	* expression and status code.
815	*
816	* @param hTest The test handle.
817	* @param rcExpr The expression resulting in an IPRT status code.
818	*/
819	#define RTTEST_CHECK_RC_OK(hTest, rcExpr) \
820	do { \
821	int rcCheck = (rcExpr); \
822	if (RT_FAILURE(rcCheck)) { \
823	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
824	} \
825	} while (0)
826	/** @def RTTEST_CHECK_RC_OK_RET
827	* Check whether a IPRT style status code indicates success.
828	*
829	* If the status indicates failure, call RTTestFailed giving the line number,
830	* expression and status code, then return with the specified value.
831	*
832	* @param hTest The test handle.
833	* @param rcExpr The expression resulting in an IPRT status code.
834	* This will be assigned to a local rcCheck variable
835	* that can be used as return value.
836	* @param rcRet The return code.
837	*/
838	#define RTTEST_CHECK_RC_OK_RET(hTest, rcExpr, rcRet) \
839	do { \
840	int rcCheck = (rcExpr); \
841	if (RT_FAILURE(rcCheck)) { \
842	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
843	return (rcRet); \
844	} \
845	} while (0)
846	/** @def RTTEST_CHECK_RC_OK_RETV
847	* Check whether a IPRT style status code indicates success.
848	*
849	* If the status indicates failure, call RTTestFailed giving the line number,
850	* expression and status code, then return.
851	*
852	* @param hTest The test handle.
853	* @param rcExpr The expression resulting in an IPRT status code.
854	*/
855	#define RTTEST_CHECK_RC_OK_RETV(hTest, rcExpr) \
856	do { \
857	int rcCheck = (rcExpr); \
858	if (RT_FAILURE(rcCheck)) { \
859	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
860	return; \
861	} \
862	} while (0)
863
864
865
866
867	/** @name Implicit Test Handle API Variation
868	* The test handle is retrieved from the test TLS entry of the calling thread.
869	* @{
870	*/
871
872	/**
873	* Test vprintf, makes sure lines are prefixed and so forth.
874	*
875	* @returns Number of chars printed.
876	* @param enmLevel Message importance level.
877	* @param pszFormat The message.
878	* @param va Arguments.
879	*/
880	RTR3DECL(int) RTTestIPrintfV(RTTESTLVL enmLevel, const char *pszFormat, va_list va);
881
882	/**
883	* Test printf, makes sure lines are prefixed and so forth.
884	*
885	* @returns Number of chars printed.
886	* @param enmLevel Message importance level.
887	* @param pszFormat The message.
888	* @param ... Arguments.
889	*/
890	RTR3DECL(int) RTTestIPrintf(RTTESTLVL enmLevel, const char *pszFormat, ...);
891
892	/**
893	* Starts a sub-test.
894	*
895	* This will perform an implicit RTTestSubDone() call if that has not been done
896	* since the last RTTestSub call.
897	*
898	* @returns Number of chars printed.
899	* @param pszSubTest The sub-test name.
900	*/
901	RTR3DECL(int) RTTestISub(const char *pszSubTest);
902
903	/**
904	* Format string version of RTTestSub.
905	*
906	* See RTTestSub for details.
907	*
908	* @returns Number of chars printed.
909	* @param pszSubTestFmt The sub-test name format string.
910	* @param ... Arguments.
911	*/
912	RTR3DECL(int) RTTestISubF(const char *pszSubTestFmt, ...);
913
914	/**
915	* Format string version of RTTestSub.
916	*
917	* See RTTestSub for details.
918	*
919	* @returns Number of chars printed.
920	* @param pszSubTestFmt The sub-test name format string.
921	* @param va Arguments.
922	*/
923	RTR3DECL(int) RTTestISubV(const char *pszSubTestFmt, va_list va);
924
925	/**
926	* Completes a sub-test.
927	*
928	* @returns Number of chars printed.
929	*/
930	RTR3DECL(int) RTTestISubDone(void);
931
932	/**
933	* Prints an extended PASSED message, optional.
934	*
935	* This does not conclude the sub-test, it could be used to report the passing
936	* of a sub-sub-to-the-power-of-N-test.
937	*
938	* @returns IPRT status code.
939	* @param pszFormat The message. No trailing newline.
940	* @param va The arguments.
941	*/
942	RTR3DECL(int) RTTestIPassedV(const char *pszFormat, va_list va);
943
944	/**
945	* Prints an extended PASSED message, optional.
946	*
947	* This does not conclude the sub-test, it could be used to report the passing
948	* of a sub-sub-to-the-power-of-N-test.
949	*
950	* @returns IPRT status code.
951	* @param pszFormat The message. No trailing newline.
952	* @param ... The arguments.
953	*/
954	RTR3DECL(int) RTTestIPassed(const char *pszFormat, ...);
955
956	/**
957	* Report a named test result value.
958	*
959	* This is typically used for benchmarking but can be used for other purposes
960	* like reporting limits of some implementation. The value gets associated with
961	* the current sub test, the name must be unique within the sub test.
962	*
963	* @returns IPRT status code.
964	*
965	* @param pszName The value name.
966	* @param u64Value The value.
967	* @param enmUnit The value unit.
968	*/
969	RTR3DECL(int) RTTestIValue(const char *pszName, uint64_t u64Value, RTTESTUNIT enmUnit);
970
971	/**
972	* Same as RTTestValue, except that the name is now a format string.
973	*
974	* @returns IPRT status code.
975	*
976	* @param u64Value The value.
977	* @param enmUnit The value unit.
978	* @param pszNameFmt The value name format string.
979	* @param ... String arguments.
980	*/
981	RTR3DECL(int) RTTestIValueF(uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, ...);
982
983	/**
984	* Same as RTTestValue, except that the name is now a format string.
985	*
986	* @returns IPRT status code.
987	*
988	* @param u64Value The value.
989	* @param enmUnit The value unit.
990	* @param pszNameFmt The value name format string.
991	* @param va_list String arguments.
992	*/
993	RTR3DECL(int) RTTestIValueV(uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, va_list va);
994
995	/**
996	* Increments the error counter.
997	*
998	* @returns IPRT status code.
999	*/
1000	RTR3DECL(int) RTTestIErrorInc(void);
1001
1002	/**
1003	* Get the current error count.
1004	*
1005	* @returns The error counter, UINT32_MAX if no valid test handle.
1006	*/
1007	RTR3DECL(uint32_t) RTTestIErrorCount(void);
1008
1009	/**
1010	* Increments the error counter and prints a failure message.
1011	*
1012	* @returns IPRT status code.
1013	* @param pszFormat The message. No trailing newline.
1014	* @param va The arguments.
1015	*/
1016	RTR3DECL(int) RTTestIFailedV(const char *pszFormat, va_list va);
1017
1018	/**
1019	* Increments the error counter and prints a failure message.
1020	*
1021	* @returns IPRT status code.
1022	* @param pszFormat The message. No trailing newline.
1023	* @param ... The arguments.
1024	*/
1025	RTR3DECL(int) RTTestIFailed(const char *pszFormat, ...);
1026
1027	/**
1028	* Increments the error counter, prints a failure message and returns the
1029	* specified status code.
1030	*
1031	* This is mainly a convenience method for saving vertical space in the source
1032	* code.
1033	*
1034	* @returns @a rcRet
1035	* @param rcRet The IPRT status code to return.
1036	* @param pszFormat The message. No trailing newline.
1037	* @param va The arguments.
1038	*/
1039	RTR3DECL(int) RTTestIFailedRcV(int rcRet, const char *pszFormat, va_list va);
1040
1041	/**
1042	* Increments the error counter, prints a failure message and returns the
1043	* specified status code.
1044	*
1045	* This is mainly a convenience method for saving vertical space in the source
1046	* code.
1047	*
1048	* @returns @a rcRet
1049	* @param rcRet The IPRT status code to return.
1050	* @param pszFormat The message. No trailing newline.
1051	* @param ... The arguments.
1052	*/
1053	RTR3DECL(int) RTTestIFailedRc(int rcRet, const char *pszFormat, ...);
1054
1055	/**
1056	* Same as RTTestIPrintfV with RTTESTLVL_FAILURE.
1057	*
1058	* @returns Number of chars printed.
1059	* @param pszFormat The message.
1060	* @param va Arguments.
1061	*/
1062	RTR3DECL(int) RTTestIFailureDetailsV(const char *pszFormat, va_list va);
1063
1064	/**
1065	* Same as RTTestIPrintf with RTTESTLVL_FAILURE.
1066	*
1067	* @returns Number of chars printed.
1068	* @param pszFormat The message.
1069	* @param ... Arguments.
1070	*/
1071	RTR3DECL(int) RTTestIFailureDetails(const char *pszFormat, ...);
1072
1073
1074	/** @def RTTESTI_CHECK
1075	* Check whether a boolean expression holds true.
1076	*
1077	* If the expression is false, call RTTestIFailed giving the line number and
1078	* expression.
1079	*
1080	* @param expr The expression to evaluate.
1081	*/
1082	#define RTTESTI_CHECK(expr) \
1083	do { if (!(expr)) { \
1084	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1085	} \
1086	} while (0)
1087	/** @def RTTESTI_CHECK_RET
1088	* Check whether a boolean expression holds true, returns on false.
1089	*
1090	* If the expression is false, call RTTestIFailed giving the line number and
1091	* expression, then return @a rcRet.
1092	*
1093	* @param expr The expression to evaluate.
1094	* @param rcRet What to return on failure.
1095	*/
1096	#define RTTESTI_CHECK_RET(expr, rcRet) \
1097	do { if (!(expr)) { \
1098	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1099	return (rcRet); \
1100	} \
1101	} while (0)
1102	/** @def RTTESTI_CHECK_RETV
1103	* Check whether a boolean expression holds true, returns void on false.
1104	*
1105	* If the expression is false, call RTTestIFailed giving the line number and
1106	* expression, then return void.
1107	*
1108	* @param expr The expression to evaluate.
1109	*/
1110	#define RTTESTI_CHECK_RETV(expr) \
1111	do { if (!(expr)) { \
1112	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1113	return; \
1114	} \
1115	} while (0)
1116	/** @def RTTESTI_CHECK_RETV
1117	* Check whether a boolean expression holds true, returns void on false.
1118	*
1119	* If the expression is false, call RTTestIFailed giving the line number and
1120	* expression, then break.
1121	*
1122	* @param expr The expression to evaluate.
1123	*/
1124	#define RTTESTI_CHECK_BREAK(expr) \
1125	if (!(expr)) { \
1126	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1127	break; \
1128	} do {} while (0)
1129
1130
1131	/** @def RTTESTI_CHECK_MSG
1132	* Check whether a boolean expression holds true.
1133	*
1134	* If the expression is false, call RTTestIFailed giving the line number and
1135	* expression.
1136	*
1137	* @param expr The expression to evaluate.
1138	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
1139	* parenthesis.
1140	*/
1141	#define RTTESTI_CHECK_MSG(expr, DetailsArgs) \
1142	do { if (!(expr)) { \
1143	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1144	RTTestIFailureDetails DetailsArgs; \
1145	} \
1146	} while (0)
1147	/** @def RTTESTI_CHECK_MSG_RET
1148	* Check whether a boolean expression holds true, returns on false.
1149	*
1150	* If the expression is false, call RTTestIFailed giving the line number and
1151	* expression.
1152	*
1153	* @param expr The expression to evaluate.
1154	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
1155	* parenthesis.
1156	* @param rcRet What to return on failure.
1157	*/
1158	#define RTTESTI_CHECK_MSG_RET(expr, DetailsArgs, rcRet) \
1159	do { if (!(expr)) { \
1160	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1161	RTTestIFailureDetails DetailsArgs; \
1162	return (rcRet); \
1163	} \
1164	} while (0)
1165	/** @def RTTESTI_CHECK_MSG_RET
1166	* Check whether a boolean expression holds true, returns void on false.
1167	*
1168	* If the expression is false, call RTTestIFailed giving the line number and
1169	* expression.
1170	*
1171	* @param expr The expression to evaluate.
1172	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
1173	* parenthesis.
1174	*/
1175	#define RTTESTI_CHECK_MSG_RETV(expr, DetailsArgs) \
1176	do { if (!(expr)) { \
1177	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1178	RTTestIFailureDetails DetailsArgs; \
1179	return; \
1180	} \
1181	} while (0)
1182
1183
1184	/** @def RTTESTI_CHECK_RC
1185	* Check whether an expression returns a specific IPRT style status code.
1186	*
1187	* If a different status code is return, call RTTestIFailed giving the line
1188	* number, expression, actual and expected status codes.
1189	*
1190	* @param rcExpr The expression resulting in an IPRT status code.
1191	* @param rcExpect The expected return code. This may be referenced
1192	* more than once by the macro.
1193	*/
1194	#define RTTESTI_CHECK_RC(rcExpr, rcExpect) \
1195	do { \
1196	int rcCheck = (rcExpr); \
1197	if (rcCheck != (rcExpect)) { \
1198	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1199	} \
1200	} while (0)
1201	/** @def RTTESTI_CHECK_RC_RET
1202	* Check whether an expression returns a specific IPRT style status code.
1203	*
1204	* If a different status code is return, call RTTestIFailed giving the line
1205	* number, expression, actual and expected status codes, then return.
1206	*
1207	* @param rcExpr The expression resulting in an IPRT status code.
1208	* This will be assigned to a local rcCheck variable
1209	* that can be used as return value.
1210	* @param rcExpect The expected return code. This may be referenced
1211	* more than once by the macro.
1212	* @param rcRet The return code.
1213	*/
1214	#define RTTESTI_CHECK_RC_RET(rcExpr, rcExpect, rcRet) \
1215	do { \
1216	int rcCheck = (rcExpr); \
1217	if (rcCheck != (rcExpect)) { \
1218	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1219	return (rcRet); \
1220	} \
1221	} while (0)
1222	/** @def RTTESTI_CHECK_RC_RETV
1223	* Check whether an expression returns a specific IPRT style status code.
1224	*
1225	* If a different status code is return, call RTTestIFailed giving the line
1226	* number, expression, actual and expected status codes, then return.
1227	*
1228	* @param rcExpr The expression resulting in an IPRT status code.
1229	* @param rcExpect The expected return code. This may be referenced
1230	* more than once by the macro.
1231	*/
1232	#define RTTESTI_CHECK_RC_RETV(rcExpr, rcExpect) \
1233	do { \
1234	int rcCheck = (rcExpr); \
1235	if (rcCheck != (rcExpect)) { \
1236	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1237	return; \
1238	} \
1239	} while (0)
1240	/** @def RTTESTI_CHECK_RC_BREAK
1241	* Check whether an expression returns a specific IPRT style status code.
1242	*
1243	* If a different status code is return, call RTTestIFailed giving the line
1244	* number, expression, actual and expected status codes, then break.
1245	*
1246	* @param rcExpr The expression resulting in an IPRT status code.
1247	* @param rcExpect The expected return code. This may be referenced
1248	* more than once by the macro.
1249	*/
1250	#define RTTESTI_CHECK_RC_BREAK(rcExpr, rcExpect) \
1251	if (1) { \
1252	int rcCheck = (rcExpr); \
1253	if (rcCheck != (rcExpect)) { \
1254	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1255	break; \
1256	} \
1257	} else do {} while (0)
1258
1259
1260	/** @def RTTESTI_CHECK_RC_OK
1261	* Check whether a IPRT style status code indicates success.
1262	*
1263	* If the status indicates failure, call RTTestIFailed giving the line number,
1264	* expression and status code.
1265	*
1266	* @param rcExpr The expression resulting in an IPRT status code.
1267	*/
1268	#define RTTESTI_CHECK_RC_OK(rcExpr) \
1269	do { \
1270	int rcCheck = (rcExpr); \
1271	if (RT_FAILURE(rcCheck)) { \
1272	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1273	} \
1274	} while (0)
1275	/** @def RTTESTI_CHECK_RC_OK_RET
1276	* Check whether a IPRT style status code indicates success.
1277	*
1278	* If the status indicates failure, call RTTestIFailed giving the line number,
1279	* expression and status code, then return with the specified value.
1280	*
1281	* @param rcExpr The expression resulting in an IPRT status code.
1282	* This will be assigned to a local rcCheck variable
1283	* that can be used as return value.
1284	* @param rcRet The return code.
1285	*/
1286	#define RTTESTI_CHECK_RC_OK_RET(rcExpr, rcRet) \
1287	do { \
1288	int rcCheck = (rcExpr); \
1289	if (RT_FAILURE(rcCheck)) { \
1290	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1291	return (rcRet); \
1292	} \
1293	} while (0)
1294	/** @def RTTESTI_CHECK_RC_OK_RETV
1295	* Check whether a IPRT style status code indicates success.
1296	*
1297	* If the status indicates failure, call RTTestIFailed giving the line number,
1298	* expression and status code, then return.
1299	*
1300	* @param rcExpr The expression resulting in an IPRT status code.
1301	*/
1302	#define RTTESTI_CHECK_RC_OK_RETV(rcExpr) \
1303	do { \
1304	int rcCheck = (rcExpr); \
1305	if (RT_FAILURE(rcCheck)) { \
1306	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1307	return; \
1308	} \
1309	} while (0)
1310
1311	/** @} */
1312
1313
1314	/** @} */
1315
1316	RT_C_DECLS_END
1317
1318	#endif
1319

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

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

Download in other formats: