test.h@ 58803

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

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

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

Download in other formats: