VirtualBox

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

Last change on this file since 45113 was 44529, checked in by vboxsync, 12 years ago

header (C) fixes

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