VirtualBox

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

Last change on this file was 103262, checked in by vboxsync, 4 weeks ago

IPRT,VMMDev,Bs3Kit: Added support for sub-sub-tests to better deal with bs3-cpu-generated-1 and others with too many sub-tests for the test manager.

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

© 2023 Oracle
ContactPrivacy policyTerms of Use