VirtualBox

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

Last change on this file since 76557 was 76557, checked in by vboxsync, 6 years ago

include/iprt: Use IPRT_INCLUDED_ rather than _iprt_ as header guard prefix, letting scm enforce this (thereby avoiding copy&paste errors like rsa.h).

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