VirtualBox

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

Last change on this file since 68817 was 62915, checked in by vboxsync, 8 years ago

IPRT/test: Added RTTestDisableAssertions and RTTestRestoreAssertions with RTTestI aliases. This simplifies the use of RTAssertSetQuiet/MayPanic by keeping the saved state in the test handle and dealing with nesting, thus reducing the code necessary when testing error paths in APIs which uses assertions.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 50.3 KB
Line 
1/** @file
2 * IPRT - Testcase Framework.
3 */
4
5/*
6 * Copyright (C) 2009-2016 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
34RT_C_DECLS_BEGIN
35
36/** @defgroup grp_rt_test RTTest - Testcase Framework.
37 * @ingroup grp_rt
38 * @{
39 */
40
41/** A test handle. */
42typedef R3PTRTYPE(struct RTTESTINT *) RTTEST;
43/** A pointer to a test handle. */
44typedef RTTEST *PRTTEST;
45/** A const pointer to a test handle. */
46typedef RTTEST const *PCRTTEST;
47
48/** A NIL Test handle. */
49#define NIL_RTTEST ((RTTEST)0)
50
51/**
52 * Test message importance level.
53 */
54typedef 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 */
80RTR3DECL(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 */
92RTR3DECL(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 */
158RTR3DECL(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 */
182RTR3DECL(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 */
197RTR3DECL(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 */
205RTR3DECL(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 */
215RTR3DECL(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 */
227RTR3DECL(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 */
240RTR3DECL(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 */
251RTR3DECL(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 */
262RTR3DECL(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 */
272RTR3DECL(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 */
284RTR3DECL(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 */
296RTR3DECL(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 */
308RTR3DECL(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 */
320RTR3DECL(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 */
329RTR3DECL(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 */
338RTR3DECL(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 */
349RTR3DECL(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 */
360RTR3DECL(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 */
373RTR3DECL(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 */
386RTR3DECL(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 */
399RTR3DECL(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 */
408RTR3DECL(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 */
422RTR3DECL(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 */
436RTR3DECL(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 */
448RTR3DECL(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 */
460RTR3DECL(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 */
477typedef 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;
517AssertCompile(RTTESTUNIT_INSTRS == 0x19);
518AssertCompile(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 */
535RTR3DECL(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 */
549RTR3DECL(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 */
564RTR3DECL(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 */
574RTR3DECL(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 */
583RTR3DECL(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 */
592RTR3DECL(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 */
603RTR3DECL(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 */
614RTR3DECL(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 */
625RTR3DECL(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 */
636RTR3DECL(int) RTTestFailureDetails(RTTEST hTest, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
637
638/**
639 * Disables and shuts up assertions.
640 *
641 * Max 8 nestings.
642 *
643 * @returns IPRT status code.
644 * @param hTest The test handle. If NIL_RTTEST we'll use the one
645 * associated with the calling thread.
646 * @sa RTAssertSetMayPanic, RTAssertSetQuiet.
647 */
648RTR3DECL(int) RTTestDisableAssertions(RTTEST hTest);
649
650/**
651 * Restores the previous call to RTTestDisableAssertions.
652 *
653 * @returns IPRT status code.
654 * @param hTest The test handle. If NIL_RTTEST we'll use the one
655 * associated with the calling thread.
656 */
657RTR3DECL(int) RTTestRestoreAssertions(RTTEST hTest);
658
659
660/** @def RTTEST_CHECK
661 * Check whether a boolean expression holds true.
662 *
663 * If the expression is false, call RTTestFailed giving the line number and expression.
664 *
665 * @param hTest The test handle.
666 * @param expr The expression to evaluate.
667 */
668#define RTTEST_CHECK(hTest, expr) \
669 do { if (!(expr)) { \
670 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
671 } \
672 } while (0)
673/** @def RTTEST_CHECK_RET
674 * Check whether a boolean expression holds true, returns on false.
675 *
676 * If the expression is false, call RTTestFailed giving the line number and
677 * expression, then return @a rcRet.
678 *
679 * @param hTest The test handle.
680 * @param expr The expression to evaluate.
681 * @param rcRet What to return on failure.
682 */
683#define RTTEST_CHECK_RET(hTest, expr, rcRet) \
684 do { if (!(expr)) { \
685 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
686 return (rcRet); \
687 } \
688 } while (0)
689/** @def RTTEST_CHECK_RETV
690 * Check whether a boolean expression holds true, returns void on false.
691 *
692 * If the expression is false, call RTTestFailed giving the line number and
693 * expression, then return void.
694 *
695 * @param hTest The test handle.
696 * @param expr The expression to evaluate.
697 */
698#define RTTEST_CHECK_RETV(hTest, expr) \
699 do { if (!(expr)) { \
700 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
701 return; \
702 } \
703 } while (0)
704/** @def RTTEST_CHECK_BREAK
705 * Check whether a boolean expression holds true.
706 *
707 * If the expression is false, call RTTestFailed giving the line number and
708 * expression, then break.
709 *
710 * @param hTest The test handle.
711 * @param expr The expression to evaluate.
712 */
713#define RTTEST_CHECK_BREAK(hTest, expr) \
714 if (!(expr)) { \
715 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
716 break; \
717 } else do {} while (0)
718
719
720/** @def RTTEST_CHECK_MSG
721 * Check whether a boolean expression holds true.
722 *
723 * If the expression is false, call RTTestFailed giving the line number and expression.
724 *
725 * @param hTest The test handle.
726 * @param expr The expression to evaluate.
727 * @param DetailsArgs Argument list for RTTestFailureDetails, including
728 * parenthesis.
729 */
730#define RTTEST_CHECK_MSG(hTest, expr, DetailsArgs) \
731 do { if (!(expr)) { \
732 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
733 RTTestFailureDetails DetailsArgs; \
734 } \
735 } while (0)
736/** @def RTTEST_CHECK_MSG_RET
737 * Check whether a boolean expression holds true, returns on false.
738 *
739 * If the expression is false, call RTTestFailed giving the line number and expression.
740 *
741 * @param hTest The test handle.
742 * @param expr The expression to evaluate.
743 * @param DetailsArgs Argument list for RTTestFailureDetails, including
744 * parenthesis.
745 * @param rcRet What to return on failure.
746 */
747#define RTTEST_CHECK_MSG_RET(hTest, expr, DetailsArgs, rcRet) \
748 do { if (!(expr)) { \
749 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
750 RTTestFailureDetails DetailsArgs; \
751 return (rcRet); \
752 } \
753 } while (0)
754/** @def RTTEST_CHECK_MSG_RET
755 * Check whether a boolean expression holds true, returns void on false.
756 *
757 * If the expression is false, call RTTestFailed giving the line number and expression.
758 *
759 * @param hTest The test handle.
760 * @param expr The expression to evaluate.
761 * @param DetailsArgs Argument list for RTTestFailureDetails, including
762 * parenthesis.
763 */
764#define RTTEST_CHECK_MSG_RETV(hTest, expr, DetailsArgs) \
765 do { if (!(expr)) { \
766 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
767 RTTestFailureDetails DetailsArgs; \
768 return; \
769 } \
770 } while (0)
771
772
773/** @def RTTEST_CHECK_RC
774 * Check whether an expression returns a specific IPRT style status code.
775 *
776 * If a different status code is return, call RTTestFailed giving the line
777 * number, expression, actual and expected status codes.
778 *
779 * @param hTest The test handle.
780 * @param rcExpr The expression resulting in an IPRT status code.
781 * @param rcExpect The expected return code. This may be referenced
782 * more than once by the macro.
783 */
784#define RTTEST_CHECK_RC(hTest, rcExpr, rcExpect) \
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 } \
790 } while (0)
791/** @def RTTEST_CHECK_RC_RET
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 return.
796 *
797 * @param hTest The test handle.
798 * @param rcExpr The expression resulting in an IPRT status code.
799 * This will be assigned to a local rcCheck variable
800 * that can be used as return value.
801 * @param rcExpect The expected return code. This may be referenced
802 * more than once by the macro.
803 * @param rcRet The return code.
804 */
805#define RTTEST_CHECK_RC_RET(hTest, rcExpr, rcExpect, rcRet) \
806 do { \
807 int rcCheck = (rcExpr); \
808 if (rcCheck != (rcExpect)) { \
809 RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
810 return (rcRet); \
811 } \
812 } while (0)
813/** @def RTTEST_CHECK_RC_RETV
814 * Check whether an expression returns a specific IPRT style status code.
815 *
816 * If a different status code is return, call RTTestFailed giving the line
817 * number, expression, actual and expected status codes, then return.
818 *
819 * @param hTest The test handle.
820 * @param rcExpr The expression resulting in an IPRT status code.
821 * @param rcExpect The expected return code. This may be referenced
822 * more than once by the macro.
823 */
824#define RTTEST_CHECK_RC_RETV(hTest, rcExpr, rcExpect) \
825 do { \
826 int rcCheck = (rcExpr); \
827 if (rcCheck != (rcExpect)) { \
828 RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
829 return; \
830 } \
831 } while (0)
832/** @def RTTEST_CHECK_RC_BREAK
833 * Check whether an expression returns a specific IPRT style status code.
834 *
835 * If a different status code is return, call RTTestFailed giving the line
836 * number, expression, actual and expected status codes, then break.
837 *
838 * @param hTest The test handle.
839 * @param rcExpr The expression resulting in an IPRT status code.
840 * @param rcExpect The expected return code. This may be referenced
841 * more than once by the macro.
842 */
843#define RTTEST_CHECK_RC_BREAK(hTest, rcExpr, rcExpect) \
844 if (1) { \
845 int rcCheck = (rcExpr); \
846 if (rcCheck != (rcExpect)) { \
847 RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
848 break; \
849 } \
850 } else do {} while (0)
851
852
853/** @def RTTEST_CHECK_RC_OK
854 * Check whether a IPRT style status code indicates success.
855 *
856 * If the status indicates failure, call RTTestFailed giving the line number,
857 * expression and status code.
858 *
859 * @param hTest The test handle.
860 * @param rcExpr The expression resulting in an IPRT status code.
861 */
862#define RTTEST_CHECK_RC_OK(hTest, rcExpr) \
863 do { \
864 int rcCheck = (rcExpr); \
865 if (RT_FAILURE(rcCheck)) { \
866 RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
867 } \
868 } while (0)
869/** @def RTTEST_CHECK_RC_OK_RET
870 * Check whether a IPRT style status code indicates success.
871 *
872 * If the status indicates failure, call RTTestFailed giving the line number,
873 * expression and status code, then return with the specified value.
874 *
875 * @param hTest The test handle.
876 * @param rcExpr The expression resulting in an IPRT status code.
877 * This will be assigned to a local rcCheck variable
878 * that can be used as return value.
879 * @param rcRet The return code.
880 */
881#define RTTEST_CHECK_RC_OK_RET(hTest, rcExpr, rcRet) \
882 do { \
883 int rcCheck = (rcExpr); \
884 if (RT_FAILURE(rcCheck)) { \
885 RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
886 return (rcRet); \
887 } \
888 } while (0)
889/** @def RTTEST_CHECK_RC_OK_RETV
890 * Check whether a IPRT style status code indicates success.
891 *
892 * If the status indicates failure, call RTTestFailed giving the line number,
893 * expression and status code, then return.
894 *
895 * @param hTest The test handle.
896 * @param rcExpr The expression resulting in an IPRT status code.
897 */
898#define RTTEST_CHECK_RC_OK_RETV(hTest, rcExpr) \
899 do { \
900 int rcCheck = (rcExpr); \
901 if (RT_FAILURE(rcCheck)) { \
902 RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
903 return; \
904 } \
905 } while (0)
906
907
908
909
910/** @name Implicit Test Handle API Variation
911 * The test handle is retrieved from the test TLS entry of the calling thread.
912 * @{
913 */
914
915/**
916 * Test vprintf, makes sure lines are prefixed and so forth.
917 *
918 * @returns Number of chars printed.
919 * @param enmLevel Message importance level.
920 * @param pszFormat The message.
921 * @param va Arguments.
922 */
923RTR3DECL(int) RTTestIPrintfV(RTTESTLVL enmLevel, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
924
925/**
926 * Test printf, makes sure lines are prefixed and so forth.
927 *
928 * @returns Number of chars printed.
929 * @param enmLevel Message importance level.
930 * @param pszFormat The message.
931 * @param ... Arguments.
932 */
933RTR3DECL(int) RTTestIPrintf(RTTESTLVL enmLevel, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
934
935/**
936 * Starts a sub-test.
937 *
938 * This will perform an implicit RTTestSubDone() call if that has not been done
939 * since the last RTTestSub call.
940 *
941 * @returns Number of chars printed.
942 * @param pszSubTest The sub-test name.
943 */
944RTR3DECL(int) RTTestISub(const char *pszSubTest);
945
946/**
947 * Format string version of RTTestSub.
948 *
949 * See RTTestSub for details.
950 *
951 * @returns Number of chars printed.
952 * @param pszSubTestFmt The sub-test name format string.
953 * @param ... Arguments.
954 */
955RTR3DECL(int) RTTestISubF(const char *pszSubTestFmt, ...) RT_IPRT_FORMAT_ATTR(1, 2);
956
957/**
958 * Format string version of RTTestSub.
959 *
960 * See RTTestSub for details.
961 *
962 * @returns Number of chars printed.
963 * @param pszSubTestFmt The sub-test name format string.
964 * @param va Arguments.
965 */
966RTR3DECL(int) RTTestISubV(const char *pszSubTestFmt, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
967
968/**
969 * Completes a sub-test.
970 *
971 * @returns Number of chars printed.
972 */
973RTR3DECL(int) RTTestISubDone(void);
974
975/**
976 * Prints an extended PASSED message, optional.
977 *
978 * This does not conclude the sub-test, it could be used to report the passing
979 * of a sub-sub-to-the-power-of-N-test.
980 *
981 * @returns IPRT status code.
982 * @param pszFormat The message. No trailing newline.
983 * @param va The arguments.
984 */
985RTR3DECL(int) RTTestIPassedV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
986
987/**
988 * Prints an extended PASSED message, optional.
989 *
990 * This does not conclude the sub-test, it could be used to report the passing
991 * of a sub-sub-to-the-power-of-N-test.
992 *
993 * @returns IPRT status code.
994 * @param pszFormat The message. No trailing newline.
995 * @param ... The arguments.
996 */
997RTR3DECL(int) RTTestIPassed(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
998
999/**
1000 * Report a named test result value.
1001 *
1002 * This is typically used for benchmarking but can be used for other purposes
1003 * like reporting limits of some implementation. The value gets associated with
1004 * the current sub test, the name must be unique within the sub test.
1005 *
1006 * @returns IPRT status code.
1007 *
1008 * @param pszName The value name.
1009 * @param u64Value The value.
1010 * @param enmUnit The value unit.
1011 */
1012RTR3DECL(int) RTTestIValue(const char *pszName, uint64_t u64Value, RTTESTUNIT enmUnit);
1013
1014/**
1015 * Same as RTTestValue, except that the name is now a format string.
1016 *
1017 * @returns IPRT status code.
1018 *
1019 * @param u64Value The value.
1020 * @param enmUnit The value unit.
1021 * @param pszNameFmt The value name format string.
1022 * @param ... String arguments.
1023 */
1024RTR3DECL(int) RTTestIValueF(uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
1025
1026/**
1027 * Same as RTTestValue, except that the name is now a format string.
1028 *
1029 * @returns IPRT status code.
1030 *
1031 * @param u64Value The value.
1032 * @param enmUnit The value unit.
1033 * @param pszNameFmt The value name format string.
1034 * @param va String arguments.
1035 */
1036RTR3DECL(int) RTTestIValueV(uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
1037
1038/**
1039 * Increments the error counter.
1040 *
1041 * @returns IPRT status code.
1042 */
1043RTR3DECL(int) RTTestIErrorInc(void);
1044
1045/**
1046 * Get the current error count.
1047 *
1048 * @returns The error counter, UINT32_MAX if no valid test handle.
1049 */
1050RTR3DECL(uint32_t) RTTestIErrorCount(void);
1051
1052/**
1053 * Increments the error counter and prints a failure message.
1054 *
1055 * @returns IPRT status code.
1056 * @param pszFormat The message. No trailing newline.
1057 * @param va The arguments.
1058 */
1059RTR3DECL(int) RTTestIFailedV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
1060
1061/**
1062 * Increments the error counter and prints a failure message.
1063 *
1064 * @returns IPRT status code.
1065 * @param pszFormat The message. No trailing newline.
1066 * @param ... The arguments.
1067 */
1068RTR3DECL(int) RTTestIFailed(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1069
1070/**
1071 * Increments the error counter, prints a failure message and returns the
1072 * specified status code.
1073 *
1074 * This is mainly a convenience method for saving vertical space in the source
1075 * code.
1076 *
1077 * @returns @a rcRet
1078 * @param rcRet The IPRT status code to return.
1079 * @param pszFormat The message. No trailing newline.
1080 * @param va The arguments.
1081 */
1082RTR3DECL(int) RTTestIFailedRcV(int rcRet, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
1083
1084/**
1085 * Increments the error counter, prints a failure message and returns the
1086 * specified status code.
1087 *
1088 * This is mainly a convenience method for saving vertical space in the source
1089 * code.
1090 *
1091 * @returns @a rcRet
1092 * @param rcRet The IPRT status code to return.
1093 * @param pszFormat The message. No trailing newline.
1094 * @param ... The arguments.
1095 */
1096RTR3DECL(int) RTTestIFailedRc(int rcRet, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
1097
1098/**
1099 * Same as RTTestIPrintfV with RTTESTLVL_FAILURE.
1100 *
1101 * @returns Number of chars printed.
1102 * @param pszFormat The message.
1103 * @param va Arguments.
1104 */
1105RTR3DECL(int) RTTestIFailureDetailsV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
1106
1107/**
1108 * Same as RTTestIPrintf with RTTESTLVL_FAILURE.
1109 *
1110 * @returns Number of chars printed.
1111 * @param pszFormat The message.
1112 * @param ... Arguments.
1113 */
1114RTR3DECL(int) RTTestIFailureDetails(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1115
1116/**
1117 * Disables and shuts up assertions.
1118 *
1119 * Max 8 nestings.
1120 *
1121 * @returns IPRT status code.
1122 * @sa RTAssertSetMayPanic, RTAssertSetQuiet.
1123 */
1124RTR3DECL(int) RTTestIDisableAssertions(void);
1125
1126/**
1127 * Restores the previous call to RTTestDisableAssertions.
1128 *
1129 * @returns IPRT status code.
1130 */
1131RTR3DECL(int) RTTestIRestoreAssertions(void);
1132
1133
1134/** @def RTTESTI_CHECK
1135 * Check whether a boolean expression holds true.
1136 *
1137 * If the expression is false, call RTTestIFailed giving the line number and
1138 * expression.
1139 *
1140 * @param expr The expression to evaluate.
1141 */
1142#define RTTESTI_CHECK(expr) \
1143 do { if (!(expr)) { \
1144 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1145 } \
1146 } while (0)
1147/** @def RTTESTI_CHECK_RET
1148 * Check whether a boolean expression holds true, returns on false.
1149 *
1150 * If the expression is false, call RTTestIFailed giving the line number and
1151 * expression, then return @a rcRet.
1152 *
1153 * @param expr The expression to evaluate.
1154 * @param rcRet What to return on failure.
1155 */
1156#define RTTESTI_CHECK_RET(expr, rcRet) \
1157 do { if (!(expr)) { \
1158 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1159 return (rcRet); \
1160 } \
1161 } while (0)
1162/** @def RTTESTI_CHECK_RETV
1163 * Check whether a boolean expression holds true, returns void on false.
1164 *
1165 * If the expression is false, call RTTestIFailed giving the line number and
1166 * expression, then return void.
1167 *
1168 * @param expr The expression to evaluate.
1169 */
1170#define RTTESTI_CHECK_RETV(expr) \
1171 do { if (!(expr)) { \
1172 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1173 return; \
1174 } \
1175 } while (0)
1176/** @def RTTESTI_CHECK_RETV
1177 * Check whether a boolean expression holds true, returns void on false.
1178 *
1179 * If the expression is false, call RTTestIFailed giving the line number and
1180 * expression, then break.
1181 *
1182 * @param expr The expression to evaluate.
1183 */
1184#define RTTESTI_CHECK_BREAK(expr) \
1185 if (!(expr)) { \
1186 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1187 break; \
1188 } else do {} while (0)
1189
1190
1191/** @def RTTESTI_CHECK_MSG
1192 * Check whether a boolean expression holds true.
1193 *
1194 * If the expression is false, call RTTestIFailed giving the line number and
1195 * expression.
1196 *
1197 * @param expr The expression to evaluate.
1198 * @param DetailsArgs Argument list for RTTestIFailureDetails, including
1199 * parenthesis.
1200 */
1201#define RTTESTI_CHECK_MSG(expr, DetailsArgs) \
1202 do { if (!(expr)) { \
1203 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1204 RTTestIFailureDetails DetailsArgs; \
1205 } \
1206 } while (0)
1207/** @def RTTESTI_CHECK_MSG_BREAK
1208 * Check whether a boolean expression holds true, returns on false.
1209 *
1210 * If the expression is false, call RTTestIFailed giving the line number and
1211 * expression.
1212 *
1213 * @param expr The expression to evaluate.
1214 * @param DetailsArgs Argument list for RTTestIFailureDetails, including
1215 * parenthesis.
1216 */
1217#define RTTESTI_CHECK_MSG_BREAK(expr, DetailsArgs) \
1218 if (!(expr)) { \
1219 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1220 RTTestIFailureDetails DetailsArgs; \
1221 break; \
1222 } else do {} while (0)
1223/** @def RTTESTI_CHECK_MSG_RET
1224 * Check whether a boolean expression holds true, returns on false.
1225 *
1226 * If the expression is false, call RTTestIFailed giving the line number and
1227 * expression.
1228 *
1229 * @param expr The expression to evaluate.
1230 * @param DetailsArgs Argument list for RTTestIFailureDetails, including
1231 * parenthesis.
1232 * @param rcRet What to return on failure.
1233 */
1234#define RTTESTI_CHECK_MSG_RET(expr, DetailsArgs, rcRet) \
1235 do { if (!(expr)) { \
1236 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1237 RTTestIFailureDetails DetailsArgs; \
1238 return (rcRet); \
1239 } \
1240 } while (0)
1241/** @def RTTESTI_CHECK_MSG_RET
1242 * Check whether a boolean expression holds true, returns void on false.
1243 *
1244 * If the expression is false, call RTTestIFailed giving the line number and
1245 * expression.
1246 *
1247 * @param expr The expression to evaluate.
1248 * @param DetailsArgs Argument list for RTTestIFailureDetails, including
1249 * parenthesis.
1250 */
1251#define RTTESTI_CHECK_MSG_RETV(expr, DetailsArgs) \
1252 do { if (!(expr)) { \
1253 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1254 RTTestIFailureDetails DetailsArgs; \
1255 return; \
1256 } \
1257 } while (0)
1258
1259/** @def RTTESTI_CHECK_RC
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.
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(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 } \
1275 } while (0)
1276/** @def RTTESTI_CHECK_RC_RET
1277 * Check whether an expression returns a specific IPRT style status code.
1278 *
1279 * If a different status code is return, call RTTestIFailed giving the line
1280 * number, expression, actual and expected status codes, then return.
1281 *
1282 * @param rcExpr The expression resulting in an IPRT status code.
1283 * This will be assigned to a local rcCheck variable
1284 * that can be used as return value.
1285 * @param rcExpect The expected return code. This may be referenced
1286 * more than once by the macro.
1287 * @param rcRet The return code.
1288 */
1289#define RTTESTI_CHECK_RC_RET(rcExpr, rcExpect, rcRet) \
1290 do { \
1291 int rcCheck = (rcExpr); \
1292 if (rcCheck != (rcExpect)) { \
1293 RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1294 return (rcRet); \
1295 } \
1296 } while (0)
1297/** @def RTTESTI_CHECK_RC_RETV
1298 * Check whether an expression returns a specific IPRT style status code.
1299 *
1300 * If a different status code is return, call RTTestIFailed giving the line
1301 * number, expression, actual and expected status codes, then return.
1302 *
1303 * @param rcExpr The expression resulting in an IPRT status code.
1304 * @param rcExpect The expected return code. This may be referenced
1305 * more than once by the macro.
1306 */
1307#define RTTESTI_CHECK_RC_RETV(rcExpr, rcExpect) \
1308 do { \
1309 int rcCheck = (rcExpr); \
1310 if (rcCheck != (rcExpect)) { \
1311 RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1312 return; \
1313 } \
1314 } while (0)
1315/** @def RTTESTI_CHECK_RC_BREAK
1316 * Check whether an expression returns a specific IPRT style status code.
1317 *
1318 * If a different status code is return, call RTTestIFailed giving the line
1319 * number, expression, actual and expected status codes, then break.
1320 *
1321 * @param rcExpr The expression resulting in an IPRT status code.
1322 * @param rcExpect The expected return code. This may be referenced
1323 * more than once by the macro.
1324 */
1325#define RTTESTI_CHECK_RC_BREAK(rcExpr, rcExpect) \
1326 if (1) { \
1327 int rcCheck = (rcExpr); \
1328 if (rcCheck != (rcExpect)) { \
1329 RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1330 break; \
1331 } \
1332 } else do {} while (0)
1333/** @def RTTESTI_CHECK_RC_OK
1334 * Check whether a IPRT style status code indicates success.
1335 *
1336 * If the status indicates failure, call RTTestIFailed giving the line number,
1337 * expression and status code.
1338 *
1339 * @param rcExpr The expression resulting in an IPRT status code.
1340 */
1341#define RTTESTI_CHECK_RC_OK(rcExpr) \
1342 do { \
1343 int rcCheck = (rcExpr); \
1344 if (RT_FAILURE(rcCheck)) { \
1345 RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1346 } \
1347 } while (0)
1348/** @def RTTESTI_CHECK_RC_OK_BREAK
1349 * Check whether a IPRT style status code indicates success.
1350 *
1351 * If a different status code is return, call RTTestIFailed giving the line
1352 * number, expression, actual and expected status codes, then break.
1353 *
1354 * @param rcExpr The expression resulting in an IPRT status code.
1355 */
1356#define RTTESTI_CHECK_RC_OK_BREAK(rcExpr) \
1357 do { \
1358 int rcCheck = (rcExpr); \
1359 if (RT_FAILURE(rcCheck)) { \
1360 RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1361 break; \
1362 } \
1363 } while (0)
1364/** @def RTTESTI_CHECK_RC_OK_RET
1365 * Check whether a IPRT style status code indicates success.
1366 *
1367 * If the status indicates failure, call RTTestIFailed giving the line number,
1368 * expression and status code, then return with the specified value.
1369 *
1370 * @param rcExpr The expression resulting in an IPRT status code.
1371 * This will be assigned to a local rcCheck variable
1372 * that can be used as return value.
1373 * @param rcRet The return code.
1374 */
1375#define RTTESTI_CHECK_RC_OK_RET(rcExpr, rcRet) \
1376 do { \
1377 int rcCheck = (rcExpr); \
1378 if (RT_FAILURE(rcCheck)) { \
1379 RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1380 return (rcRet); \
1381 } \
1382 } while (0)
1383/** @def RTTESTI_CHECK_RC_OK_RETV
1384 * Check whether a IPRT style status code indicates success.
1385 *
1386 * If the status indicates failure, call RTTestIFailed giving the line number,
1387 * expression and status code, then return.
1388 *
1389 * @param rcExpr The expression resulting in an IPRT status code.
1390 */
1391#define RTTESTI_CHECK_RC_OK_RETV(rcExpr) \
1392 do { \
1393 int rcCheck = (rcExpr); \
1394 if (RT_FAILURE(rcCheck)) { \
1395 RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1396 return; \
1397 } \
1398 } while (0)
1399
1400/** @} */
1401
1402
1403/** @} */
1404
1405RT_C_DECLS_END
1406
1407#endif
1408
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette