test.h@ 57004

Last change on this file since 57004 was 57004, checked in by vboxsync, 9 years ago
iprt,*: Marked all format strings in the C part of IPRT and fixed the fallout.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 48.5 KB

Line
1	/** @file
2	* IPRT - Testcase Framework.
3	*/
4
5	/*
6	* Copyright (C) 2009-2015 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) RT_IPRT_FORMAT_ATTR(3, 0);
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, ...) RT_IPRT_FORMAT_ATTR(3, 4);
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) RT_IPRT_FORMAT_ATTR(3, 0);
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, ...) RT_IPRT_FORMAT_ATTR(3, 4);
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) RT_IPRT_FORMAT_ATTR(2, 0);
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, ...) RT_IPRT_FORMAT_ATTR(2, 3);
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, ...) RT_IPRT_FORMAT_ATTR(2, 3);
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) RT_IPRT_FORMAT_ATTR(2, 0);
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) RT_IPRT_FORMAT_ATTR(2, 0);
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, ...) RT_IPRT_FORMAT_ATTR(2, 3);
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, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(2, 3);
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) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(2, 0);
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,
530	const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(4, 5);
531
532	/**
533	* Same as RTTestValue, except that the name is now a format string.
534	*
535	* @returns IPRT status code.
536	*
537	* @param hTest The test handle. If NIL_RTTEST we'll use the one
538	* associated with the calling thread.
539	* @param u64Value The value.
540	* @param enmUnit The value unit.
541	* @param pszNameFmt The value name format string.
542	* @param va_list String arguments.
543	*/
544	RTR3DECL(int) RTTestValueV(RTTEST hTest, uint64_t u64Value, RTTESTUNIT enmUnit,
545	const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(4, 0);
546
547	/**
548	* Increments the error counter.
549	*
550	* @returns IPRT status code.
551	* @param hTest The test handle. If NIL_RTTEST we'll use the one
552	* associated with the calling thread.
553	*/
554	RTR3DECL(int) RTTestErrorInc(RTTEST hTest);
555
556	/**
557	* Get the current error count.
558	*
559	* @returns The error counter, UINT32_MAX if no valid test handle.
560	* @param hTest The test handle. If NIL_RTTEST we'll use the one
561	* associated with the calling thread.
562	*/
563	RTR3DECL(uint32_t) RTTestErrorCount(RTTEST hTest);
564
565	/**
566	* Get the error count of the current sub test.
567	*
568	* @returns The error counter, UINT32_MAX if no valid test handle.
569	* @param hTest The test handle. If NIL_RTTEST we'll use the one
570	* associated with the calling thread.
571	*/
572	RTR3DECL(uint32_t) RTTestSubErrorCount(RTTEST hTest);
573
574	/**
575	* Increments the error counter and prints a failure message.
576	*
577	* @returns IPRT status code.
578	* @param hTest The test handle. If NIL_RTTEST we'll use the one
579	* associated with the calling thread.
580	* @param pszFormat The message. No trailing newline.
581	* @param va The arguments.
582	*/
583	RTR3DECL(int) RTTestFailedV(RTTEST hTest, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
584
585	/**
586	* Increments the error counter and prints a failure message.
587	*
588	* @returns IPRT status code.
589	* @param hTest The test handle. If NIL_RTTEST we'll use the one
590	* associated with the calling thread.
591	* @param pszFormat The message. No trailing newline.
592	* @param ... The arguments.
593	*/
594	RTR3DECL(int) RTTestFailed(RTTEST hTest, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
595
596	/**
597	* Same as RTTestPrintfV with RTTESTLVL_FAILURE.
598	*
599	* @returns Number of chars printed.
600	* @param hTest The test handle. If NIL_RTTEST we'll use the one
601	* associated with the calling thread.
602	* @param pszFormat The message.
603	* @param va Arguments.
604	*/
605	RTR3DECL(int) RTTestFailureDetailsV(RTTEST hTest, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
606
607	/**
608	* Same as RTTestPrintf with RTTESTLVL_FAILURE.
609	*
610	* @returns Number of chars printed.
611	* @param hTest The test handle. If NIL_RTTEST we'll use the one
612	* associated with the calling thread.
613	* @param pszFormat The message.
614	* @param ... Arguments.
615	*/
616	RTR3DECL(int) RTTestFailureDetails(RTTEST hTest, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
617
618
619	/** @def RTTEST_CHECK
620	* Check whether a boolean expression holds true.
621	*
622	* If the expression is false, call RTTestFailed giving the line number and expression.
623	*
624	* @param hTest The test handle.
625	* @param expr The expression to evaluate.
626	*/
627	#define RTTEST_CHECK(hTest, expr) \
628	do { if (!(expr)) { \
629	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
630	} \
631	} while (0)
632	/** @def RTTEST_CHECK_RET
633	* Check whether a boolean expression holds true, returns on false.
634	*
635	* If the expression is false, call RTTestFailed giving the line number and
636	* expression, then return @a rcRet.
637	*
638	* @param hTest The test handle.
639	* @param expr The expression to evaluate.
640	* @param rcRet What to return on failure.
641	*/
642	#define RTTEST_CHECK_RET(hTest, expr, rcRet) \
643	do { if (!(expr)) { \
644	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
645	return (rcRet); \
646	} \
647	} while (0)
648	/** @def RTTEST_CHECK_RETV
649	* Check whether a boolean expression holds true, returns void on false.
650	*
651	* If the expression is false, call RTTestFailed giving the line number and
652	* expression, then return void.
653	*
654	* @param hTest The test handle.
655	* @param expr The expression to evaluate.
656	*/
657	#define RTTEST_CHECK_RETV(hTest, expr) \
658	do { if (!(expr)) { \
659	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
660	return; \
661	} \
662	} while (0)
663	/** @def RTTEST_CHECK_BREAK
664	* Check whether a boolean expression holds true.
665	*
666	* If the expression is false, call RTTestFailed giving the line number and
667	* expression, then break.
668	*
669	* @param hTest The test handle.
670	* @param expr The expression to evaluate.
671	*/
672	#define RTTEST_CHECK_BREAK(hTest, expr) \
673	if (!(expr)) { \
674	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
675	break; \
676	} else do {} while (0)
677
678
679	/** @def RTTEST_CHECK_MSG
680	* Check whether a boolean expression holds true.
681	*
682	* If the expression is false, call RTTestFailed giving the line number and expression.
683	*
684	* @param hTest The test handle.
685	* @param expr The expression to evaluate.
686	* @param DetailsArgs Argument list for RTTestFailureDetails, including
687	* parenthesis.
688	*/
689	#define RTTEST_CHECK_MSG(hTest, expr, DetailsArgs) \
690	do { if (!(expr)) { \
691	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
692	RTTestFailureDetails DetailsArgs; \
693	} \
694	} while (0)
695	/** @def RTTEST_CHECK_MSG_RET
696	* Check whether a boolean expression holds true, returns on false.
697	*
698	* If the expression is false, call RTTestFailed giving the line number and expression.
699	*
700	* @param hTest The test handle.
701	* @param expr The expression to evaluate.
702	* @param DetailsArgs Argument list for RTTestFailureDetails, including
703	* parenthesis.
704	* @param rcRet What to return on failure.
705	*/
706	#define RTTEST_CHECK_MSG_RET(hTest, expr, DetailsArgs, rcRet) \
707	do { if (!(expr)) { \
708	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
709	RTTestFailureDetails DetailsArgs; \
710	return (rcRet); \
711	} \
712	} while (0)
713	/** @def RTTEST_CHECK_MSG_RET
714	* Check whether a boolean expression holds true, returns void on false.
715	*
716	* If the expression is false, call RTTestFailed giving the line number and expression.
717	*
718	* @param hTest The test handle.
719	* @param expr The expression to evaluate.
720	* @param DetailsArgs Argument list for RTTestFailureDetails, including
721	* parenthesis.
722	*/
723	#define RTTEST_CHECK_MSG_RETV(hTest, expr, DetailsArgs) \
724	do { if (!(expr)) { \
725	RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
726	RTTestFailureDetails DetailsArgs; \
727	return; \
728	} \
729	} while (0)
730
731
732	/** @def RTTEST_CHECK_RC
733	* Check whether an expression returns a specific IPRT style status code.
734	*
735	* If a different status code is return, call RTTestFailed giving the line
736	* number, expression, actual and expected status codes.
737	*
738	* @param hTest The test handle.
739	* @param rcExpr The expression resulting in an IPRT status code.
740	* @param rcExpect The expected return code. This may be referenced
741	* more than once by the macro.
742	*/
743	#define RTTEST_CHECK_RC(hTest, rcExpr, rcExpect) \
744	do { \
745	int rcCheck = (rcExpr); \
746	if (rcCheck != (rcExpect)) { \
747	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
748	} \
749	} while (0)
750	/** @def RTTEST_CHECK_RC_RET
751	* Check whether an expression returns a specific IPRT style status code.
752	*
753	* If a different status code is return, call RTTestFailed giving the line
754	* number, expression, actual and expected status codes, then return.
755	*
756	* @param hTest The test handle.
757	* @param rcExpr The expression resulting in an IPRT status code.
758	* This will be assigned to a local rcCheck variable
759	* that can be used as return value.
760	* @param rcExpect The expected return code. This may be referenced
761	* more than once by the macro.
762	* @param rcRet The return code.
763	*/
764	#define RTTEST_CHECK_RC_RET(hTest, rcExpr, rcExpect, rcRet) \
765	do { \
766	int rcCheck = (rcExpr); \
767	if (rcCheck != (rcExpect)) { \
768	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
769	return (rcRet); \
770	} \
771	} while (0)
772	/** @def RTTEST_CHECK_RC_RETV
773	* Check whether an expression returns a specific IPRT style status code.
774	*
775	* If a different status code is return, call RTTestFailed giving the line
776	* number, expression, actual and expected status codes, then return.
777	*
778	* @param hTest The test handle.
779	* @param rcExpr The expression resulting in an IPRT status code.
780	* @param rcExpect The expected return code. This may be referenced
781	* more than once by the macro.
782	*/
783	#define RTTEST_CHECK_RC_RETV(hTest, rcExpr, rcExpect) \
784	do { \
785	int rcCheck = (rcExpr); \
786	if (rcCheck != (rcExpect)) { \
787	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
788	return; \
789	} \
790	} while (0)
791	/** @def RTTEST_CHECK_RC_BREAK
792	* Check whether an expression returns a specific IPRT style status code.
793	*
794	* If a different status code is return, call RTTestFailed giving the line
795	* number, expression, actual and expected status codes, then break.
796	*
797	* @param hTest The test handle.
798	* @param rcExpr The expression resulting in an IPRT status code.
799	* @param rcExpect The expected return code. This may be referenced
800	* more than once by the macro.
801	*/
802	#define RTTEST_CHECK_RC_BREAK(hTest, rcExpr, rcExpect) \
803	if (1) { \
804	int rcCheck = (rcExpr); \
805	if (rcCheck != (rcExpect)) { \
806	RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
807	break; \
808	} \
809	} else do {} while (0)
810
811
812	/** @def RTTEST_CHECK_RC_OK
813	* Check whether a IPRT style status code indicates success.
814	*
815	* If the status indicates failure, call RTTestFailed giving the line number,
816	* expression and status code.
817	*
818	* @param hTest The test handle.
819	* @param rcExpr The expression resulting in an IPRT status code.
820	*/
821	#define RTTEST_CHECK_RC_OK(hTest, rcExpr) \
822	do { \
823	int rcCheck = (rcExpr); \
824	if (RT_FAILURE(rcCheck)) { \
825	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
826	} \
827	} while (0)
828	/** @def RTTEST_CHECK_RC_OK_RET
829	* Check whether a IPRT style status code indicates success.
830	*
831	* If the status indicates failure, call RTTestFailed giving the line number,
832	* expression and status code, then return with the specified value.
833	*
834	* @param hTest The test handle.
835	* @param rcExpr The expression resulting in an IPRT status code.
836	* This will be assigned to a local rcCheck variable
837	* that can be used as return value.
838	* @param rcRet The return code.
839	*/
840	#define RTTEST_CHECK_RC_OK_RET(hTest, rcExpr, rcRet) \
841	do { \
842	int rcCheck = (rcExpr); \
843	if (RT_FAILURE(rcCheck)) { \
844	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
845	return (rcRet); \
846	} \
847	} while (0)
848	/** @def RTTEST_CHECK_RC_OK_RETV
849	* Check whether a IPRT style status code indicates success.
850	*
851	* If the status indicates failure, call RTTestFailed giving the line number,
852	* expression and status code, then return.
853	*
854	* @param hTest The test handle.
855	* @param rcExpr The expression resulting in an IPRT status code.
856	*/
857	#define RTTEST_CHECK_RC_OK_RETV(hTest, rcExpr) \
858	do { \
859	int rcCheck = (rcExpr); \
860	if (RT_FAILURE(rcCheck)) { \
861	RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
862	return; \
863	} \
864	} while (0)
865
866
867
868
869	/** @name Implicit Test Handle API Variation
870	* The test handle is retrieved from the test TLS entry of the calling thread.
871	* @{
872	*/
873
874	/**
875	* Test vprintf, makes sure lines are prefixed and so forth.
876	*
877	* @returns Number of chars printed.
878	* @param enmLevel Message importance level.
879	* @param pszFormat The message.
880	* @param va Arguments.
881	*/
882	RTR3DECL(int) RTTestIPrintfV(RTTESTLVL enmLevel, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
883
884	/**
885	* Test printf, makes sure lines are prefixed and so forth.
886	*
887	* @returns Number of chars printed.
888	* @param enmLevel Message importance level.
889	* @param pszFormat The message.
890	* @param ... Arguments.
891	*/
892	RTR3DECL(int) RTTestIPrintf(RTTESTLVL enmLevel, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
893
894	/**
895	* Starts a sub-test.
896	*
897	* This will perform an implicit RTTestSubDone() call if that has not been done
898	* since the last RTTestSub call.
899	*
900	* @returns Number of chars printed.
901	* @param pszSubTest The sub-test name.
902	*/
903	RTR3DECL(int) RTTestISub(const char *pszSubTest);
904
905	/**
906	* Format string version of RTTestSub.
907	*
908	* See RTTestSub for details.
909	*
910	* @returns Number of chars printed.
911	* @param pszSubTestFmt The sub-test name format string.
912	* @param ... Arguments.
913	*/
914	RTR3DECL(int) RTTestISubF(const char *pszSubTestFmt, ...) RT_IPRT_FORMAT_ATTR(1, 2);
915
916	/**
917	* Format string version of RTTestSub.
918	*
919	* See RTTestSub for details.
920	*
921	* @returns Number of chars printed.
922	* @param pszSubTestFmt The sub-test name format string.
923	* @param va Arguments.
924	*/
925	RTR3DECL(int) RTTestISubV(const char *pszSubTestFmt, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
926
927	/**
928	* Completes a sub-test.
929	*
930	* @returns Number of chars printed.
931	*/
932	RTR3DECL(int) RTTestISubDone(void);
933
934	/**
935	* Prints an extended PASSED message, optional.
936	*
937	* This does not conclude the sub-test, it could be used to report the passing
938	* of a sub-sub-to-the-power-of-N-test.
939	*
940	* @returns IPRT status code.
941	* @param pszFormat The message. No trailing newline.
942	* @param va The arguments.
943	*/
944	RTR3DECL(int) RTTestIPassedV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
945
946	/**
947	* Prints an extended PASSED message, optional.
948	*
949	* This does not conclude the sub-test, it could be used to report the passing
950	* of a sub-sub-to-the-power-of-N-test.
951	*
952	* @returns IPRT status code.
953	* @param pszFormat The message. No trailing newline.
954	* @param ... The arguments.
955	*/
956	RTR3DECL(int) RTTestIPassed(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
957
958	/**
959	* Report a named test result value.
960	*
961	* This is typically used for benchmarking but can be used for other purposes
962	* like reporting limits of some implementation. The value gets associated with
963	* the current sub test, the name must be unique within the sub test.
964	*
965	* @returns IPRT status code.
966	*
967	* @param pszName The value name.
968	* @param u64Value The value.
969	* @param enmUnit The value unit.
970	*/
971	RTR3DECL(int) RTTestIValue(const char *pszName, uint64_t u64Value, RTTESTUNIT enmUnit);
972
973	/**
974	* Same as RTTestValue, except that the name is now a format string.
975	*
976	* @returns IPRT status code.
977	*
978	* @param u64Value The value.
979	* @param enmUnit The value unit.
980	* @param pszNameFmt The value name format string.
981	* @param ... String arguments.
982	*/
983	RTR3DECL(int) RTTestIValueF(uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
984
985	/**
986	* Same as RTTestValue, except that the name is now a format string.
987	*
988	* @returns IPRT status code.
989	*
990	* @param u64Value The value.
991	* @param enmUnit The value unit.
992	* @param pszNameFmt The value name format string.
993	* @param va_list String arguments.
994	*/
995	RTR3DECL(int) RTTestIValueV(uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
996
997	/**
998	* Increments the error counter.
999	*
1000	* @returns IPRT status code.
1001	*/
1002	RTR3DECL(int) RTTestIErrorInc(void);
1003
1004	/**
1005	* Get the current error count.
1006	*
1007	* @returns The error counter, UINT32_MAX if no valid test handle.
1008	*/
1009	RTR3DECL(uint32_t) RTTestIErrorCount(void);
1010
1011	/**
1012	* Increments the error counter and prints a failure message.
1013	*
1014	* @returns IPRT status code.
1015	* @param pszFormat The message. No trailing newline.
1016	* @param va The arguments.
1017	*/
1018	RTR3DECL(int) RTTestIFailedV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
1019
1020	/**
1021	* Increments the error counter and prints a failure message.
1022	*
1023	* @returns IPRT status code.
1024	* @param pszFormat The message. No trailing newline.
1025	* @param ... The arguments.
1026	*/
1027	RTR3DECL(int) RTTestIFailed(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1028
1029	/**
1030	* Increments the error counter, prints a failure message and returns the
1031	* specified status code.
1032	*
1033	* This is mainly a convenience method for saving vertical space in the source
1034	* code.
1035	*
1036	* @returns @a rcRet
1037	* @param rcRet The IPRT status code to return.
1038	* @param pszFormat The message. No trailing newline.
1039	* @param va The arguments.
1040	*/
1041	RTR3DECL(int) RTTestIFailedRcV(int rcRet, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
1042
1043	/**
1044	* Increments the error counter, prints a failure message and returns the
1045	* specified status code.
1046	*
1047	* This is mainly a convenience method for saving vertical space in the source
1048	* code.
1049	*
1050	* @returns @a rcRet
1051	* @param rcRet The IPRT status code to return.
1052	* @param pszFormat The message. No trailing newline.
1053	* @param ... The arguments.
1054	*/
1055	RTR3DECL(int) RTTestIFailedRc(int rcRet, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
1056
1057	/**
1058	* Same as RTTestIPrintfV with RTTESTLVL_FAILURE.
1059	*
1060	* @returns Number of chars printed.
1061	* @param pszFormat The message.
1062	* @param va Arguments.
1063	*/
1064	RTR3DECL(int) RTTestIFailureDetailsV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
1065
1066	/**
1067	* Same as RTTestIPrintf with RTTESTLVL_FAILURE.
1068	*
1069	* @returns Number of chars printed.
1070	* @param pszFormat The message.
1071	* @param ... Arguments.
1072	*/
1073	RTR3DECL(int) RTTestIFailureDetails(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1074
1075
1076	/** @def RTTESTI_CHECK
1077	* Check whether a boolean expression holds true.
1078	*
1079	* If the expression is false, call RTTestIFailed giving the line number and
1080	* expression.
1081	*
1082	* @param expr The expression to evaluate.
1083	*/
1084	#define RTTESTI_CHECK(expr) \
1085	do { if (!(expr)) { \
1086	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1087	} \
1088	} while (0)
1089	/** @def RTTESTI_CHECK_RET
1090	* Check whether a boolean expression holds true, returns on false.
1091	*
1092	* If the expression is false, call RTTestIFailed giving the line number and
1093	* expression, then return @a rcRet.
1094	*
1095	* @param expr The expression to evaluate.
1096	* @param rcRet What to return on failure.
1097	*/
1098	#define RTTESTI_CHECK_RET(expr, rcRet) \
1099	do { if (!(expr)) { \
1100	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1101	return (rcRet); \
1102	} \
1103	} while (0)
1104	/** @def RTTESTI_CHECK_RETV
1105	* Check whether a boolean expression holds true, returns void on false.
1106	*
1107	* If the expression is false, call RTTestIFailed giving the line number and
1108	* expression, then return void.
1109	*
1110	* @param expr The expression to evaluate.
1111	*/
1112	#define RTTESTI_CHECK_RETV(expr) \
1113	do { if (!(expr)) { \
1114	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1115	return; \
1116	} \
1117	} while (0)
1118	/** @def RTTESTI_CHECK_RETV
1119	* Check whether a boolean expression holds true, returns void on false.
1120	*
1121	* If the expression is false, call RTTestIFailed giving the line number and
1122	* expression, then break.
1123	*
1124	* @param expr The expression to evaluate.
1125	*/
1126	#define RTTESTI_CHECK_BREAK(expr) \
1127	if (!(expr)) { \
1128	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1129	break; \
1130	} else do {} while (0)
1131
1132
1133	/** @def RTTESTI_CHECK_MSG
1134	* Check whether a boolean expression holds true.
1135	*
1136	* If the expression is false, call RTTestIFailed giving the line number and
1137	* expression.
1138	*
1139	* @param expr The expression to evaluate.
1140	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
1141	* parenthesis.
1142	*/
1143	#define RTTESTI_CHECK_MSG(expr, DetailsArgs) \
1144	do { if (!(expr)) { \
1145	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1146	RTTestIFailureDetails DetailsArgs; \
1147	} \
1148	} while (0)
1149	/** @def RTTESTI_CHECK_MSG_BREAK
1150	* Check whether a boolean expression holds true, returns on false.
1151	*
1152	* If the expression is false, call RTTestIFailed giving the line number and
1153	* expression.
1154	*
1155	* @param expr The expression to evaluate.
1156	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
1157	* parenthesis.
1158	* @param rcRet What to return on failure.
1159	*/
1160	#define RTTESTI_CHECK_MSG_BREAK(expr, DetailsArgs) \
1161	if (!(expr)) { \
1162	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1163	RTTestIFailureDetails DetailsArgs; \
1164	break; \
1165	} else do {} while (0)
1166	/** @def RTTESTI_CHECK_MSG_RET
1167	* Check whether a boolean expression holds true, returns on false.
1168	*
1169	* If the expression is false, call RTTestIFailed giving the line number and
1170	* expression.
1171	*
1172	* @param expr The expression to evaluate.
1173	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
1174	* parenthesis.
1175	* @param rcRet What to return on failure.
1176	*/
1177	#define RTTESTI_CHECK_MSG_RET(expr, DetailsArgs, rcRet) \
1178	do { if (!(expr)) { \
1179	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1180	RTTestIFailureDetails DetailsArgs; \
1181	return (rcRet); \
1182	} \
1183	} while (0)
1184	/** @def RTTESTI_CHECK_MSG_RET
1185	* Check whether a boolean expression holds true, returns void on false.
1186	*
1187	* If the expression is false, call RTTestIFailed giving the line number and
1188	* expression.
1189	*
1190	* @param expr The expression to evaluate.
1191	* @param DetailsArgs Argument list for RTTestIFailureDetails, including
1192	* parenthesis.
1193	*/
1194	#define RTTESTI_CHECK_MSG_RETV(expr, DetailsArgs) \
1195	do { if (!(expr)) { \
1196	RTTestIFailed("line %u: %s", __LINE__, #expr); \
1197	RTTestIFailureDetails DetailsArgs; \
1198	return; \
1199	} \
1200	} while (0)
1201
1202	/** @def RTTESTI_CHECK_RC
1203	* Check whether an expression returns a specific IPRT style status code.
1204	*
1205	* If a different status code is return, call RTTestIFailed giving the line
1206	* number, expression, actual and expected status codes.
1207	*
1208	* @param rcExpr The expression resulting in an IPRT status code.
1209	* @param rcExpect The expected return code. This may be referenced
1210	* more than once by the macro.
1211	*/
1212	#define RTTESTI_CHECK_RC(rcExpr, rcExpect) \
1213	do { \
1214	int rcCheck = (rcExpr); \
1215	if (rcCheck != (rcExpect)) { \
1216	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1217	} \
1218	} while (0)
1219	/** @def RTTESTI_CHECK_RC_RET
1220	* Check whether an expression returns a specific IPRT style status code.
1221	*
1222	* If a different status code is return, call RTTestIFailed giving the line
1223	* number, expression, actual and expected status codes, then return.
1224	*
1225	* @param rcExpr The expression resulting in an IPRT status code.
1226	* This will be assigned to a local rcCheck variable
1227	* that can be used as return value.
1228	* @param rcExpect The expected return code. This may be referenced
1229	* more than once by the macro.
1230	* @param rcRet The return code.
1231	*/
1232	#define RTTESTI_CHECK_RC_RET(rcExpr, rcExpect, rcRet) \
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 (rcRet); \
1238	} \
1239	} while (0)
1240	/** @def RTTESTI_CHECK_RC_RETV
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 return.
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_RETV(rcExpr, rcExpect) \
1251	do { \
1252	int rcCheck = (rcExpr); \
1253	if (rcCheck != (rcExpect)) { \
1254	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1255	return; \
1256	} \
1257	} while (0)
1258	/** @def RTTESTI_CHECK_RC_BREAK
1259	* Check whether an expression returns a specific IPRT style status code.
1260	*
1261	* If a different status code is return, call RTTestIFailed giving the line
1262	* number, expression, actual and expected status codes, then break.
1263	*
1264	* @param rcExpr The expression resulting in an IPRT status code.
1265	* @param rcExpect The expected return code. This may be referenced
1266	* more than once by the macro.
1267	*/
1268	#define RTTESTI_CHECK_RC_BREAK(rcExpr, rcExpect) \
1269	if (1) { \
1270	int rcCheck = (rcExpr); \
1271	if (rcCheck != (rcExpect)) { \
1272	RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1273	break; \
1274	} \
1275	} else do {} while (0)
1276	/** @def RTTESTI_CHECK_RC_OK
1277	* Check whether a IPRT style status code indicates success.
1278	*
1279	* If the status indicates failure, call RTTestIFailed giving the line number,
1280	* expression and status code.
1281	*
1282	* @param rcExpr The expression resulting in an IPRT status code.
1283	*/
1284	#define RTTESTI_CHECK_RC_OK(rcExpr) \
1285	do { \
1286	int rcCheck = (rcExpr); \
1287	if (RT_FAILURE(rcCheck)) { \
1288	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1289	} \
1290	} while (0)
1291	/** @def RTTESTI_CHECK_RC_OK_BREAK
1292	* Check whether a IPRT style status code indicates success.
1293	*
1294	* If a different status code is return, call RTTestIFailed giving the line
1295	* number, expression, actual and expected status codes, then break.
1296	*
1297	* @param rcExpr The expression resulting in an IPRT status code.
1298	*/
1299	#define RTTESTI_CHECK_RC_OK_BREAK(rcExpr) \
1300	do { \
1301	int rcCheck = (rcExpr); \
1302	if (RT_FAILURE(rcCheck)) { \
1303	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1304	break; \
1305	} \
1306	} while (0)
1307	/** @def RTTESTI_CHECK_RC_OK_RET
1308	* Check whether a IPRT style status code indicates success.
1309	*
1310	* If the status indicates failure, call RTTestIFailed giving the line number,
1311	* expression and status code, then return with the specified value.
1312	*
1313	* @param rcExpr The expression resulting in an IPRT status code.
1314	* This will be assigned to a local rcCheck variable
1315	* that can be used as return value.
1316	* @param rcRet The return code.
1317	*/
1318	#define RTTESTI_CHECK_RC_OK_RET(rcExpr, rcRet) \
1319	do { \
1320	int rcCheck = (rcExpr); \
1321	if (RT_FAILURE(rcCheck)) { \
1322	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1323	return (rcRet); \
1324	} \
1325	} while (0)
1326	/** @def RTTESTI_CHECK_RC_OK_RETV
1327	* Check whether a IPRT style status code indicates success.
1328	*
1329	* If the status indicates failure, call RTTestIFailed giving the line number,
1330	* expression and status code, then return.
1331	*
1332	* @param rcExpr The expression resulting in an IPRT status code.
1333	*/
1334	#define RTTESTI_CHECK_RC_OK_RETV(rcExpr) \
1335	do { \
1336	int rcCheck = (rcExpr); \
1337	if (RT_FAILURE(rcCheck)) { \
1338	RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1339	return; \
1340	} \
1341	} while (0)
1342
1343	/** @} */
1344
1345
1346	/** @} */
1347
1348	RT_C_DECLS_END
1349
1350	#endif
1351

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

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

Download in other formats: