VirtualBox

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

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 53.8 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 * Prints an extended PASSED message, optional.
424 *
425 * This does not conclude the sub-test, it could be used to report the passing
426 * of a sub-sub-to-the-power-of-N-test.
427 *
428 * @returns Number of chars printed, negative numbers are IPRT error codes.
429 * @param hTest The test handle. If NIL_RTTEST we'll use the one
430 * associated with the calling thread.
431 * @param pszFormat The message. No trailing newline.
432 * @param va The arguments.
433 */
434RTR3DECL(int) RTTestPassedV(RTTEST hTest, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
435
436/**
437 * Prints an extended PASSED message, optional.
438 *
439 * This does not conclude the sub-test, it could be used to report the passing
440 * of a sub-sub-to-the-power-of-N-test.
441 *
442 * @returns Number of chars printed, negative numbers are IPRT error codes.
443 * @param hTest The test handle. If NIL_RTTEST we'll use the one
444 * associated with the calling thread.
445 * @param pszFormat The message. No trailing newline.
446 * @param ... The arguments.
447 */
448RTR3DECL(int) RTTestPassed(RTTEST hTest, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
449
450/**
451 * Marks the current test as 'SKIPPED' and optionally displays a message
452 * explaining why.
453 *
454 * @returns Number of chars printed, negative numbers are IPRT error codes.
455 * @param hTest The test handle. If NIL_RTTEST we'll use the one
456 * associated with the calling thread.
457 * @param pszFormat The message. No trailing newline. Can be NULL or empty.
458 * @param ... The arguments.
459 */
460RTR3DECL(int) RTTestSkipped(RTTEST hTest, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(2, 3);
461
462/**
463 * Marks the current test as 'SKIPPED' and optionally displays a message
464 * explaining why.
465 *
466 * @returns Number of chars printed, negative numbers are IPRT error codes.
467 * @param hTest The test handle. If NIL_RTTEST we'll use the one
468 * associated with the calling thread.
469 * @param pszFormat The message. No trailing newline. Can be NULL or empty.
470 * @param va The arguments.
471 */
472RTR3DECL(int) RTTestSkippedV(RTTEST hTest, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(2, 0);
473
474
475/**
476 * Value units.
477 *
478 * @remarks This is an interface where we have to be binary compatible with both
479 * older versions of this header and other components using the same
480 * contant values.
481 * @remarks When adding a new item:
482 * - Always add at the end of the list.
483 * - Add it to rtTestUnitName in r3/test.cpp.
484 * - Add it as VMMDEV_TESTING_UNIT_ in include/VBox/VMMDevTesting.h.
485 * - Add it to g_aszBs2TestUnitNames in
486 * ValidationKit/bootsectors/bootsector2-common-routines.mac.
487 * - Add it to g_aszBs3TestUnitNames in bs3kit/bs3-cmn-TestData.c.
488 * - Add it to ValidationKit/common/constants/valueunit.py both as
489 * a constant (strip RTTESTUNIT_) and as a name (same as what
490 * rtTestUnitName returns) for mapping. Testmanager must be
491 * updated.
492 * - Add it to Value.kdBestByUnit in ValidationKit/analysis/reader.py.
493 */
494typedef enum RTTESTUNIT
495{
496 /** The customary invalid zero value. */
497 RTTESTUNIT_INVALID = 0,
498
499 RTTESTUNIT_PCT, /**< Percentage (10^-2). */
500 RTTESTUNIT_BYTES, /**< Bytes. */
501 RTTESTUNIT_BYTES_PER_SEC, /**< Bytes per second. */
502 RTTESTUNIT_KILOBYTES, /**< Kilobytes. */
503 RTTESTUNIT_KILOBYTES_PER_SEC, /**< Kilobytes per second. */
504 RTTESTUNIT_MEGABYTES, /**< Megabytes. */
505 RTTESTUNIT_MEGABYTES_PER_SEC, /**< Megabytes per second. */
506 RTTESTUNIT_PACKETS, /**< Packets. */
507 RTTESTUNIT_PACKETS_PER_SEC, /**< Packets per second. */
508 RTTESTUNIT_FRAMES, /**< Frames. */
509 RTTESTUNIT_FRAMES_PER_SEC, /**< Frames per second. */
510 RTTESTUNIT_OCCURRENCES, /**< Occurrences. */
511 RTTESTUNIT_OCCURRENCES_PER_SEC, /**< Occurrences per second. */
512 RTTESTUNIT_CALLS, /**< Calls. */
513 RTTESTUNIT_CALLS_PER_SEC, /**< Calls per second. */
514 RTTESTUNIT_ROUND_TRIP, /**< Round trips. */
515 RTTESTUNIT_SECS, /**< Seconds. */
516 RTTESTUNIT_MS, /**< Milliseconds. */
517 RTTESTUNIT_NS, /**< Nanoseconds. */
518 RTTESTUNIT_NS_PER_CALL, /**< Nanoseconds per call. */
519 RTTESTUNIT_NS_PER_FRAME, /**< Nanoseconds per frame. */
520 RTTESTUNIT_NS_PER_OCCURRENCE, /**< Nanoseconds per occurrence. */
521 RTTESTUNIT_NS_PER_PACKET, /**< Nanoseconds per frame. */
522 RTTESTUNIT_NS_PER_ROUND_TRIP, /**< Nanoseconds per round trip. */
523 RTTESTUNIT_INSTRS, /**< Instructions. */
524 RTTESTUNIT_INSTRS_PER_SEC, /**< Instructions per second. */
525 RTTESTUNIT_NONE, /**< No unit. */
526 RTTESTUNIT_PP1K, /**< Parts per thousand (10^-3). */
527 RTTESTUNIT_PP10K, /**< Parts per ten thousand (10^-4). */
528 RTTESTUNIT_PPM, /**< Parts per million (10^-6). */
529 RTTESTUNIT_PPB, /**< Parts per billion (10^-9). */
530 RTTESTUNIT_TICKS, /**< CPU ticks. */
531 RTTESTUNIT_TICKS_PER_CALL, /**< CPU ticks per call. */
532 RTTESTUNIT_TICKS_PER_OCCURENCE, /**< CPU ticks per occurence. */
533 RTTESTUNIT_PAGES, /**< Page count. */
534 RTTESTUNIT_PAGES_PER_SEC, /**< Pages per second. */
535 RTTESTUNIT_TICKS_PER_PAGE, /**< CPU ticks per page. */
536 RTTESTUNIT_NS_PER_PAGE, /**< Nanoseconds per page. */
537 RTTESTUNIT_PS, /**< Picoseconds. */
538 RTTESTUNIT_PS_PER_CALL, /**< Picoseconds per call. */
539 RTTESTUNIT_PS_PER_FRAME, /**< Picoseconds per frame. */
540 RTTESTUNIT_PS_PER_OCCURRENCE, /**< Picoseconds per occurrence. */
541 RTTESTUNIT_PS_PER_PACKET, /**< Picoseconds per frame. */
542 RTTESTUNIT_PS_PER_ROUND_TRIP, /**< Picoseconds per round trip. */
543 RTTESTUNIT_PS_PER_PAGE, /**< Picoseconds per page. */
544
545 /** The end of valid units. */
546 RTTESTUNIT_END
547} RTTESTUNIT;
548AssertCompile(RTTESTUNIT_INSTRS == 0x19);
549AssertCompile(RTTESTUNIT_NONE == 0x1b);
550AssertCompile(RTTESTUNIT_NS_PER_PAGE == 0x26);
551AssertCompile(RTTESTUNIT_PS_PER_PAGE == 0x2d);
552
553/**
554 * Report a named test result value.
555 *
556 * This is typically used for benchmarking but can be used for other purposes
557 * like reporting limits of some implementation. The value gets associated with
558 * the current sub test, the name must be unique within the sub test.
559 *
560 * @returns IPRT status code.
561 *
562 * @param hTest The test handle. If NIL_RTTEST we'll use the one
563 * associated with the calling thread.
564 * @param pszName The value name.
565 * @param u64Value The value.
566 * @param enmUnit The value unit.
567 */
568RTR3DECL(int) RTTestValue(RTTEST hTest, const char *pszName, uint64_t u64Value, RTTESTUNIT enmUnit);
569
570/**
571 * Same as RTTestValue, except that the name is now a format string.
572 *
573 * @returns IPRT status code.
574 *
575 * @param hTest The test handle. If NIL_RTTEST we'll use the one
576 * associated with the calling thread.
577 * @param u64Value The value.
578 * @param enmUnit The value unit.
579 * @param pszNameFmt The value name format string.
580 * @param ... String arguments.
581 */
582RTR3DECL(int) RTTestValueF(RTTEST hTest, uint64_t u64Value, RTTESTUNIT enmUnit,
583 const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(4, 5);
584
585/**
586 * Same as RTTestValue, except that the name is now a format string.
587 *
588 * @returns IPRT status code.
589 *
590 * @param hTest The test handle. If NIL_RTTEST we'll use the one
591 * associated with the calling thread.
592 * @param u64Value The value.
593 * @param enmUnit The value unit.
594 * @param pszNameFmt The value name format string.
595 * @param va String arguments.
596 */
597RTR3DECL(int) RTTestValueV(RTTEST hTest, uint64_t u64Value, RTTESTUNIT enmUnit,
598 const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(4, 0);
599
600/**
601 * Increments the error counter.
602 *
603 * @returns IPRT status code.
604 * @param hTest The test handle. If NIL_RTTEST we'll use the one
605 * associated with the calling thread.
606 */
607RTR3DECL(int) RTTestErrorInc(RTTEST hTest);
608
609/**
610 * Get the current error count.
611 *
612 * @returns The error counter, UINT32_MAX if no valid test handle.
613 * @param hTest The test handle. If NIL_RTTEST we'll use the one
614 * associated with the calling thread.
615 */
616RTR3DECL(uint32_t) RTTestErrorCount(RTTEST hTest);
617
618/**
619 * Get the error count of the current sub test.
620 *
621 * @returns The error counter, UINT32_MAX if no valid test handle.
622 * @param hTest The test handle. If NIL_RTTEST we'll use the one
623 * associated with the calling thread.
624 */
625RTR3DECL(uint32_t) RTTestSubErrorCount(RTTEST hTest);
626
627/**
628 * Increments the error counter and prints a failure message.
629 *
630 * @returns IPRT status code.
631 * @param hTest The test handle. If NIL_RTTEST we'll use the one
632 * associated with the calling thread.
633 * @param pszFormat The message. No trailing newline.
634 * @param va The arguments.
635 */
636RTR3DECL(int) RTTestFailedV(RTTEST hTest, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
637
638/**
639 * Increments the error counter and prints a failure message.
640 *
641 * @returns IPRT status code.
642 * @param hTest The test handle. If NIL_RTTEST we'll use the one
643 * associated with the calling thread.
644 * @param pszFormat The message. No trailing newline.
645 * @param ... The arguments.
646 */
647RTR3DECL(int) RTTestFailed(RTTEST hTest, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
648
649/**
650 * Same as RTTestPrintfV with RTTESTLVL_FAILURE.
651 *
652 * @returns Number of chars printed.
653 * @param hTest The test handle. If NIL_RTTEST we'll use the one
654 * associated with the calling thread.
655 * @param pszFormat The message.
656 * @param va Arguments.
657 */
658RTR3DECL(int) RTTestFailureDetailsV(RTTEST hTest, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
659
660/**
661 * Same as RTTestPrintf with RTTESTLVL_FAILURE.
662 *
663 * @returns Number of chars printed.
664 * @param hTest The test handle. If NIL_RTTEST we'll use the one
665 * associated with the calling thread.
666 * @param pszFormat The message.
667 * @param ... Arguments.
668 */
669RTR3DECL(int) RTTestFailureDetails(RTTEST hTest, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
670
671/**
672 * Sets error context info to be printed with the first failure.
673 *
674 * @returns IPRT status code.
675 * @param hTest The test handle. If NIL_RTTEST we'll use the one
676 * associated with the calling thread.
677 * @param pszFormat The message, no trailing newline. NULL to clear the
678 * context message.
679 * @param va The arguments.
680 */
681RTR3DECL(int) RTTestErrContextV(RTTEST hTest, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
682
683/**
684 * Sets error context info to be printed with the first failure.
685 *
686 * @returns IPRT status code.
687 * @param hTest The test handle. If NIL_RTTEST we'll use the one
688 * associated with the calling thread.
689 * @param pszFormat The message, no trailing newline. NULL to clear the
690 * context message.
691 * @param ... The arguments.
692 */
693RTR3DECL(int) RTTestErrContext(RTTEST hTest, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
694
695/**
696 * Disables and shuts up assertions.
697 *
698 * Max 8 nestings.
699 *
700 * @returns IPRT status code.
701 * @param hTest The test handle. If NIL_RTTEST we'll use the one
702 * associated with the calling thread.
703 * @sa RTAssertSetMayPanic, RTAssertSetQuiet.
704 */
705RTR3DECL(int) RTTestDisableAssertions(RTTEST hTest);
706
707/**
708 * Restores the previous call to RTTestDisableAssertions.
709 *
710 * @returns IPRT status code.
711 * @param hTest The test handle. If NIL_RTTEST we'll use the one
712 * associated with the calling thread.
713 */
714RTR3DECL(int) RTTestRestoreAssertions(RTTEST hTest);
715
716
717/** @def RTTEST_CHECK
718 * Check whether a boolean expression holds true.
719 *
720 * If the expression is false, call RTTestFailed giving the line number and expression.
721 *
722 * @param hTest The test handle.
723 * @param expr The expression to evaluate.
724 */
725#define RTTEST_CHECK(hTest, expr) \
726 do { if (!(expr)) { \
727 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
728 } \
729 } while (0)
730/** @def RTTEST_CHECK_RET
731 * Check whether a boolean expression holds true, returns on false.
732 *
733 * If the expression is false, call RTTestFailed giving the line number and
734 * expression, then return @a rcRet.
735 *
736 * @param hTest The test handle.
737 * @param expr The expression to evaluate.
738 * @param rcRet What to return on failure.
739 */
740#define RTTEST_CHECK_RET(hTest, expr, rcRet) \
741 do { if (!(expr)) { \
742 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
743 return (rcRet); \
744 } \
745 } while (0)
746/** @def RTTEST_CHECK_RETV
747 * Check whether a boolean expression holds true, returns void on false.
748 *
749 * If the expression is false, call RTTestFailed giving the line number and
750 * expression, then return void.
751 *
752 * @param hTest The test handle.
753 * @param expr The expression to evaluate.
754 */
755#define RTTEST_CHECK_RETV(hTest, expr) \
756 do { if (!(expr)) { \
757 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
758 return; \
759 } \
760 } while (0)
761/** @def RTTEST_CHECK_BREAK
762 * Check whether a boolean expression holds true.
763 *
764 * If the expression is false, call RTTestFailed giving the line number and
765 * expression, then break.
766 *
767 * @param hTest The test handle.
768 * @param expr The expression to evaluate.
769 */
770#define RTTEST_CHECK_BREAK(hTest, expr) \
771 if (!(expr)) { \
772 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
773 break; \
774 } else do {} while (0)
775
776
777/** @def RTTEST_CHECK_MSG
778 * Check whether a boolean expression holds true.
779 *
780 * If the expression is false, call RTTestFailed giving the line number and expression.
781 *
782 * @param hTest The test handle.
783 * @param expr The expression to evaluate.
784 * @param DetailsArgs Argument list for RTTestFailureDetails, including
785 * parenthesis.
786 */
787#define RTTEST_CHECK_MSG(hTest, expr, DetailsArgs) \
788 do { if (!(expr)) { \
789 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
790 RTTestFailureDetails DetailsArgs; \
791 } \
792 } while (0)
793/** @def RTTEST_CHECK_MSG_RET
794 * Check whether a boolean expression holds true, returns on false.
795 *
796 * If the expression is false, call RTTestFailed giving the line number and expression.
797 *
798 * @param hTest The test handle.
799 * @param expr The expression to evaluate.
800 * @param DetailsArgs Argument list for RTTestFailureDetails, including
801 * parenthesis.
802 * @param rcRet What to return on failure.
803 */
804#define RTTEST_CHECK_MSG_RET(hTest, expr, DetailsArgs, rcRet) \
805 do { if (!(expr)) { \
806 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
807 RTTestFailureDetails DetailsArgs; \
808 return (rcRet); \
809 } \
810 } while (0)
811/** @def RTTEST_CHECK_MSG_RETV
812 * Check whether a boolean expression holds true, returns void on false.
813 *
814 * If the expression is false, call RTTestFailed giving the line number and expression.
815 *
816 * @param hTest The test handle.
817 * @param expr The expression to evaluate.
818 * @param DetailsArgs Argument list for RTTestFailureDetails, including
819 * parenthesis.
820 */
821#define RTTEST_CHECK_MSG_RETV(hTest, expr, DetailsArgs) \
822 do { if (!(expr)) { \
823 RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
824 RTTestFailureDetails DetailsArgs; \
825 return; \
826 } \
827 } while (0)
828
829
830/** @def RTTEST_CHECK_RC
831 * Check whether an expression returns a specific IPRT style status code.
832 *
833 * If a different status code is return, call RTTestFailed giving the line
834 * number, expression, actual and expected status codes.
835 *
836 * @param hTest The test handle.
837 * @param rcExpr The expression resulting in an IPRT status code.
838 * @param rcExpect The expected return code. This may be referenced
839 * more than once by the macro.
840 */
841#define RTTEST_CHECK_RC(hTest, rcExpr, rcExpect) \
842 do { \
843 int rcCheck = (rcExpr); \
844 if (rcCheck != (rcExpect)) { \
845 RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
846 } \
847 } while (0)
848/** @def RTTEST_CHECK_RC_RET
849 * Check whether an expression returns a specific IPRT style status code.
850 *
851 * If a different status code is return, call RTTestFailed giving the line
852 * number, expression, actual and expected status codes, then return.
853 *
854 * @param hTest The test handle.
855 * @param rcExpr The expression resulting in an IPRT status code.
856 * This will be assigned to a local rcCheck variable
857 * that can be used as return value.
858 * @param rcExpect The expected return code. This may be referenced
859 * more than once by the macro.
860 * @param rcRet The return code.
861 */
862#define RTTEST_CHECK_RC_RET(hTest, rcExpr, rcExpect, rcRet) \
863 do { \
864 int rcCheck = (rcExpr); \
865 if (rcCheck != (rcExpect)) { \
866 RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
867 return (rcRet); \
868 } \
869 } while (0)
870/** @def RTTEST_CHECK_RC_RETV
871 * Check whether an expression returns a specific IPRT style status code.
872 *
873 * If a different status code is return, call RTTestFailed giving the line
874 * number, expression, actual and expected status codes, then return.
875 *
876 * @param hTest The test handle.
877 * @param rcExpr The expression resulting in an IPRT status code.
878 * @param rcExpect The expected return code. This may be referenced
879 * more than once by the macro.
880 */
881#define RTTEST_CHECK_RC_RETV(hTest, rcExpr, rcExpect) \
882 do { \
883 int rcCheck = (rcExpr); \
884 if (rcCheck != (rcExpect)) { \
885 RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
886 return; \
887 } \
888 } while (0)
889/** @def RTTEST_CHECK_RC_BREAK
890 * Check whether an expression returns a specific IPRT style status code.
891 *
892 * If a different status code is return, call RTTestFailed giving the line
893 * number, expression, actual and expected status codes, then break.
894 *
895 * @param hTest The test handle.
896 * @param rcExpr The expression resulting in an IPRT status code.
897 * @param rcExpect The expected return code. This may be referenced
898 * more than once by the macro.
899 */
900#define RTTEST_CHECK_RC_BREAK(hTest, rcExpr, rcExpect) \
901 if (1) { \
902 int rcCheck = (rcExpr); \
903 if (rcCheck != (rcExpect)) { \
904 RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
905 break; \
906 } \
907 } else do {} while (0)
908
909
910/** @def RTTEST_CHECK_RC_OK
911 * Check whether a IPRT style status code indicates success.
912 *
913 * If the status indicates failure, call RTTestFailed giving the line number,
914 * expression and status code.
915 *
916 * @param hTest The test handle.
917 * @param rcExpr The expression resulting in an IPRT status code.
918 */
919#define RTTEST_CHECK_RC_OK(hTest, rcExpr) \
920 do { \
921 int rcCheck = (rcExpr); \
922 if (RT_FAILURE(rcCheck)) { \
923 RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
924 } \
925 } while (0)
926/** @def RTTEST_CHECK_RC_OK_RET
927 * Check whether a IPRT style status code indicates success.
928 *
929 * If the status indicates failure, call RTTestFailed giving the line number,
930 * expression and status code, then return with the specified value.
931 *
932 * @param hTest The test handle.
933 * @param rcExpr The expression resulting in an IPRT status code.
934 * This will be assigned to a local rcCheck variable
935 * that can be used as return value.
936 * @param rcRet The return code.
937 */
938#define RTTEST_CHECK_RC_OK_RET(hTest, rcExpr, rcRet) \
939 do { \
940 int rcCheck = (rcExpr); \
941 if (RT_FAILURE(rcCheck)) { \
942 RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
943 return (rcRet); \
944 } \
945 } while (0)
946/** @def RTTEST_CHECK_RC_OK_RETV
947 * Check whether a IPRT style status code indicates success.
948 *
949 * If the status indicates failure, call RTTestFailed giving the line number,
950 * expression and status code, then return.
951 *
952 * @param hTest The test handle.
953 * @param rcExpr The expression resulting in an IPRT status code.
954 */
955#define RTTEST_CHECK_RC_OK_RETV(hTest, rcExpr) \
956 do { \
957 int rcCheck = (rcExpr); \
958 if (RT_FAILURE(rcCheck)) { \
959 RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
960 return; \
961 } \
962 } while (0)
963
964
965
966
967/** @name Implicit Test Handle API Variation
968 * The test handle is retrieved from the test TLS entry of the calling thread.
969 * @{
970 */
971
972/**
973 * Test vprintf, makes sure lines are prefixed and so forth.
974 *
975 * @returns Number of chars printed.
976 * @param enmLevel Message importance level.
977 * @param pszFormat The message.
978 * @param va Arguments.
979 */
980RTR3DECL(int) RTTestIPrintfV(RTTESTLVL enmLevel, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
981
982/**
983 * Test printf, makes sure lines are prefixed and so forth.
984 *
985 * @returns Number of chars printed.
986 * @param enmLevel Message importance level.
987 * @param pszFormat The message.
988 * @param ... Arguments.
989 */
990RTR3DECL(int) RTTestIPrintf(RTTESTLVL enmLevel, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
991
992/**
993 * Starts a sub-test.
994 *
995 * This will perform an implicit RTTestSubDone() call if that has not been done
996 * since the last RTTestSub call.
997 *
998 * @returns Number of chars printed.
999 * @param pszSubTest The sub-test name.
1000 */
1001RTR3DECL(int) RTTestISub(const char *pszSubTest);
1002
1003/**
1004 * Format string version of RTTestSub.
1005 *
1006 * See RTTestSub for details.
1007 *
1008 * @returns Number of chars printed.
1009 * @param pszSubTestFmt The sub-test name format string.
1010 * @param ... Arguments.
1011 */
1012RTR3DECL(int) RTTestISubF(const char *pszSubTestFmt, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1013
1014/**
1015 * Format string version of RTTestSub.
1016 *
1017 * See RTTestSub for details.
1018 *
1019 * @returns Number of chars printed.
1020 * @param pszSubTestFmt The sub-test name format string.
1021 * @param va Arguments.
1022 */
1023RTR3DECL(int) RTTestISubV(const char *pszSubTestFmt, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
1024
1025/**
1026 * Completes a sub-test.
1027 *
1028 * @returns Number of chars printed.
1029 */
1030RTR3DECL(int) RTTestISubDone(void);
1031
1032/**
1033 * Prints an extended PASSED message, optional.
1034 *
1035 * This does not conclude the sub-test, it could be used to report the passing
1036 * of a sub-sub-to-the-power-of-N-test.
1037 *
1038 * @returns IPRT status code.
1039 * @param pszFormat The message. No trailing newline.
1040 * @param va The arguments.
1041 */
1042RTR3DECL(int) RTTestIPassedV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
1043
1044/**
1045 * Prints an extended PASSED message, optional.
1046 *
1047 * This does not conclude the sub-test, it could be used to report the passing
1048 * of a sub-sub-to-the-power-of-N-test.
1049 *
1050 * @returns IPRT status code.
1051 * @param pszFormat The message. No trailing newline.
1052 * @param ... The arguments.
1053 */
1054RTR3DECL(int) RTTestIPassed(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1055
1056/**
1057 * Report a named test result value.
1058 *
1059 * This is typically used for benchmarking but can be used for other purposes
1060 * like reporting limits of some implementation. The value gets associated with
1061 * the current sub test, the name must be unique within the sub test.
1062 *
1063 * @returns IPRT status code.
1064 *
1065 * @param pszName The value name.
1066 * @param u64Value The value.
1067 * @param enmUnit The value unit.
1068 */
1069RTR3DECL(int) RTTestIValue(const char *pszName, uint64_t u64Value, RTTESTUNIT enmUnit);
1070
1071/**
1072 * Same as RTTestValue, except that the name is now a format string.
1073 *
1074 * @returns IPRT status code.
1075 *
1076 * @param u64Value The value.
1077 * @param enmUnit The value unit.
1078 * @param pszNameFmt The value name format string.
1079 * @param ... String arguments.
1080 */
1081RTR3DECL(int) RTTestIValueF(uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
1082
1083/**
1084 * Same as RTTestValue, except that the name is now a format string.
1085 *
1086 * @returns IPRT status code.
1087 *
1088 * @param u64Value The value.
1089 * @param enmUnit The value unit.
1090 * @param pszNameFmt The value name format string.
1091 * @param va String arguments.
1092 */
1093RTR3DECL(int) RTTestIValueV(uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
1094
1095/**
1096 * Increments the error counter.
1097 *
1098 * @returns IPRT status code.
1099 */
1100RTR3DECL(int) RTTestIErrorInc(void);
1101
1102/**
1103 * Get the current error count.
1104 *
1105 * @returns The error counter, UINT32_MAX if no valid test handle.
1106 */
1107RTR3DECL(uint32_t) RTTestIErrorCount(void);
1108
1109/**
1110 * Increments the error counter and prints a failure message.
1111 *
1112 * @returns IPRT status code.
1113 * @param pszFormat The message. No trailing newline.
1114 * @param va The arguments.
1115 */
1116RTR3DECL(int) RTTestIFailedV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
1117
1118/**
1119 * Increments the error counter and prints a failure message.
1120 *
1121 * @returns IPRT status code.
1122 * @param pszFormat The message. No trailing newline.
1123 * @param ... The arguments.
1124 */
1125RTR3DECL(int) RTTestIFailed(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1126
1127/**
1128 * Increments the error counter, prints a failure message and returns the
1129 * specified status code.
1130 *
1131 * This is mainly a convenience method for saving vertical space in the source
1132 * code.
1133 *
1134 * @returns @a rcRet
1135 * @param rcRet The IPRT status code to return.
1136 * @param pszFormat The message. No trailing newline.
1137 * @param va The arguments.
1138 */
1139RTR3DECL(int) RTTestIFailedRcV(int rcRet, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
1140
1141/**
1142 * Increments the error counter, prints a failure message and returns the
1143 * specified status code.
1144 *
1145 * This is mainly a convenience method for saving vertical space in the source
1146 * code.
1147 *
1148 * @returns @a rcRet
1149 * @param rcRet The IPRT status code to return.
1150 * @param pszFormat The message. No trailing newline.
1151 * @param ... The arguments.
1152 */
1153RTR3DECL(int) RTTestIFailedRc(int rcRet, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
1154
1155/**
1156 * Same as RTTestIPrintfV with RTTESTLVL_FAILURE.
1157 *
1158 * @returns Number of chars printed.
1159 * @param pszFormat The message.
1160 * @param va Arguments.
1161 */
1162RTR3DECL(int) RTTestIFailureDetailsV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
1163
1164/**
1165 * Same as RTTestIPrintf with RTTESTLVL_FAILURE.
1166 *
1167 * @returns Number of chars printed.
1168 * @param pszFormat The message.
1169 * @param ... Arguments.
1170 */
1171RTR3DECL(int) RTTestIFailureDetails(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1172
1173/**
1174 * Sets error context info to be printed with the first failure.
1175 *
1176 * @returns IPRT status code.
1177 * @param pszFormat The message, no trailing newline. NULL to clear the
1178 * context message.
1179 * @param va The arguments.
1180 */
1181RTR3DECL(int) RTTestIErrContextV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
1182
1183/**
1184 * Sets error context info to be printed with the first failure.
1185 *
1186 * @returns IPRT status code.
1187 * @param pszFormat The message, no trailing newline. NULL to clear the
1188 * context message.
1189 * @param ... The arguments.
1190 */
1191RTR3DECL(int) RTTestIErrContext(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1192
1193/**
1194 * Disables and shuts up assertions.
1195 *
1196 * Max 8 nestings.
1197 *
1198 * @returns IPRT status code.
1199 * @sa RTAssertSetMayPanic, RTAssertSetQuiet.
1200 */
1201RTR3DECL(int) RTTestIDisableAssertions(void);
1202
1203/**
1204 * Restores the previous call to RTTestDisableAssertions.
1205 *
1206 * @returns IPRT status code.
1207 */
1208RTR3DECL(int) RTTestIRestoreAssertions(void);
1209
1210
1211/** @def RTTESTI_CHECK
1212 * Check whether a boolean expression holds true.
1213 *
1214 * If the expression is false, call RTTestIFailed giving the line number and
1215 * expression.
1216 *
1217 * @param expr The expression to evaluate.
1218 */
1219#define RTTESTI_CHECK(expr) \
1220 do { if (!(expr)) { \
1221 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1222 } \
1223 } while (0)
1224/** @def RTTESTI_CHECK_RET
1225 * Check whether a boolean expression holds true, returns on false.
1226 *
1227 * If the expression is false, call RTTestIFailed giving the line number and
1228 * expression, then return @a rcRet.
1229 *
1230 * @param expr The expression to evaluate.
1231 * @param rcRet What to return on failure.
1232 */
1233#define RTTESTI_CHECK_RET(expr, rcRet) \
1234 do { if (!(expr)) { \
1235 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1236 return (rcRet); \
1237 } \
1238 } while (0)
1239/** @def RTTESTI_CHECK_RETV
1240 * Check whether a boolean expression holds true, returns void on false.
1241 *
1242 * If the expression is false, call RTTestIFailed giving the line number and
1243 * expression, then return void.
1244 *
1245 * @param expr The expression to evaluate.
1246 */
1247#define RTTESTI_CHECK_RETV(expr) \
1248 do { if (!(expr)) { \
1249 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1250 return; \
1251 } \
1252 } while (0)
1253/** @def RTTESTI_CHECK_BREAK
1254 * Check whether a boolean expression holds true, returns void on false.
1255 *
1256 * If the expression is false, call RTTestIFailed giving the line number and
1257 * expression, then break.
1258 *
1259 * @param expr The expression to evaluate.
1260 */
1261#define RTTESTI_CHECK_BREAK(expr) \
1262 if (!(expr)) { \
1263 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1264 break; \
1265 } else do {} while (0)
1266
1267
1268/** @def RTTESTI_CHECK_MSG
1269 * Check whether a boolean expression holds true.
1270 *
1271 * If the expression is false, call RTTestIFailed giving the line number and
1272 * expression.
1273 *
1274 * @param expr The expression to evaluate.
1275 * @param DetailsArgs Argument list for RTTestIFailureDetails, including
1276 * parenthesis.
1277 */
1278#define RTTESTI_CHECK_MSG(expr, DetailsArgs) \
1279 do { if (!(expr)) { \
1280 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1281 RTTestIFailureDetails DetailsArgs; \
1282 } \
1283 } while (0)
1284/** @def RTTESTI_CHECK_MSG_BREAK
1285 * Check whether a boolean expression holds true, returns on false.
1286 *
1287 * If the expression is false, call RTTestIFailed giving the line number and
1288 * expression.
1289 *
1290 * @param expr The expression to evaluate.
1291 * @param DetailsArgs Argument list for RTTestIFailureDetails, including
1292 * parenthesis.
1293 */
1294#define RTTESTI_CHECK_MSG_BREAK(expr, DetailsArgs) \
1295 if (!(expr)) { \
1296 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1297 RTTestIFailureDetails DetailsArgs; \
1298 break; \
1299 } else do {} while (0)
1300/** @def RTTESTI_CHECK_MSG_RET
1301 * Check whether a boolean expression holds true, returns on false.
1302 *
1303 * If the expression is false, call RTTestIFailed giving the line number and
1304 * expression.
1305 *
1306 * @param expr The expression to evaluate.
1307 * @param DetailsArgs Argument list for RTTestIFailureDetails, including
1308 * parenthesis.
1309 * @param rcRet What to return on failure.
1310 */
1311#define RTTESTI_CHECK_MSG_RET(expr, DetailsArgs, rcRet) \
1312 do { if (!(expr)) { \
1313 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1314 RTTestIFailureDetails DetailsArgs; \
1315 return (rcRet); \
1316 } \
1317 } while (0)
1318/** @def RTTESTI_CHECK_MSG_RETV
1319 * Check whether a boolean expression holds true, returns void on false.
1320 *
1321 * If the expression is false, call RTTestIFailed giving the line number and
1322 * expression.
1323 *
1324 * @param expr The expression to evaluate.
1325 * @param DetailsArgs Argument list for RTTestIFailureDetails, including
1326 * parenthesis.
1327 */
1328#define RTTESTI_CHECK_MSG_RETV(expr, DetailsArgs) \
1329 do { if (!(expr)) { \
1330 RTTestIFailed("line %u: %s", __LINE__, #expr); \
1331 RTTestIFailureDetails DetailsArgs; \
1332 return; \
1333 } \
1334 } while (0)
1335
1336/** @def RTTESTI_CHECK_RC
1337 * Check whether an expression returns a specific IPRT style status code.
1338 *
1339 * If a different status code is return, call RTTestIFailed giving the line
1340 * number, expression, actual and expected status codes.
1341 *
1342 * @param rcExpr The expression resulting in an IPRT status code.
1343 * @param rcExpect The expected return code. This may be referenced
1344 * more than once by the macro.
1345 */
1346#define RTTESTI_CHECK_RC(rcExpr, rcExpect) \
1347 do { \
1348 int rcCheck = (rcExpr); \
1349 if (rcCheck != (rcExpect)) { \
1350 RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1351 } \
1352 } while (0)
1353/** @def RTTESTI_CHECK_RC_RET
1354 * Check whether an expression returns a specific IPRT style status code.
1355 *
1356 * If a different status code is return, call RTTestIFailed giving the line
1357 * number, expression, actual and expected status codes, then return.
1358 *
1359 * @param rcExpr The expression resulting in an IPRT status code.
1360 * This will be assigned to a local rcCheck variable
1361 * that can be used as return value.
1362 * @param rcExpect The expected return code. This may be referenced
1363 * more than once by the macro.
1364 * @param rcRet The return code.
1365 */
1366#define RTTESTI_CHECK_RC_RET(rcExpr, rcExpect, rcRet) \
1367 do { \
1368 int rcCheck = (rcExpr); \
1369 if (rcCheck != (rcExpect)) { \
1370 RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1371 return (rcRet); \
1372 } \
1373 } while (0)
1374/** @def RTTESTI_CHECK_RC_RETV
1375 * Check whether an expression returns a specific IPRT style status code.
1376 *
1377 * If a different status code is return, call RTTestIFailed giving the line
1378 * number, expression, actual and expected status codes, then return.
1379 *
1380 * @param rcExpr The expression resulting in an IPRT status code.
1381 * @param rcExpect The expected return code. This may be referenced
1382 * more than once by the macro.
1383 */
1384#define RTTESTI_CHECK_RC_RETV(rcExpr, rcExpect) \
1385 do { \
1386 int rcCheck = (rcExpr); \
1387 if (rcCheck != (rcExpect)) { \
1388 RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1389 return; \
1390 } \
1391 } while (0)
1392/** @def RTTESTI_CHECK_RC_BREAK
1393 * Check whether an expression returns a specific IPRT style status code.
1394 *
1395 * If a different status code is return, call RTTestIFailed giving the line
1396 * number, expression, actual and expected status codes, then break.
1397 *
1398 * @param rcExpr The expression resulting in an IPRT status code.
1399 * @param rcExpect The expected return code. This may be referenced
1400 * more than once by the macro.
1401 */
1402#define RTTESTI_CHECK_RC_BREAK(rcExpr, rcExpect) \
1403 if (1) { \
1404 int rcCheck = (rcExpr); \
1405 if (rcCheck != (rcExpect)) { \
1406 RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
1407 break; \
1408 } \
1409 } else do {} while (0)
1410/** @def RTTESTI_CHECK_RC_OK
1411 * Check whether a IPRT style status code indicates success.
1412 *
1413 * If the status indicates failure, call RTTestIFailed giving the line number,
1414 * expression and status code.
1415 *
1416 * @param rcExpr The expression resulting in an IPRT status code.
1417 */
1418#define RTTESTI_CHECK_RC_OK(rcExpr) \
1419 do { \
1420 int rcCheck = (rcExpr); \
1421 if (RT_FAILURE(rcCheck)) { \
1422 RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1423 } \
1424 } while (0)
1425/** @def RTTESTI_CHECK_RC_OK_BREAK
1426 * Check whether a IPRT style status code indicates success.
1427 *
1428 * If a different status code is return, call RTTestIFailed giving the line
1429 * number, expression, actual and expected status codes, then break.
1430 *
1431 * @param rcExpr The expression resulting in an IPRT status code.
1432 */
1433#define RTTESTI_CHECK_RC_OK_BREAK(rcExpr) \
1434 do { \
1435 int rcCheck = (rcExpr); \
1436 if (RT_FAILURE(rcCheck)) { \
1437 RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1438 break; \
1439 } \
1440 } while (0)
1441/** @def RTTESTI_CHECK_RC_OK_RET
1442 * Check whether a IPRT style status code indicates success.
1443 *
1444 * If the status indicates failure, call RTTestIFailed giving the line number,
1445 * expression and status code, then return with the specified value.
1446 *
1447 * @param rcExpr The expression resulting in an IPRT status code.
1448 * This will be assigned to a local rcCheck variable
1449 * that can be used as return value.
1450 * @param rcRet The return code.
1451 */
1452#define RTTESTI_CHECK_RC_OK_RET(rcExpr, rcRet) \
1453 do { \
1454 int rcCheck = (rcExpr); \
1455 if (RT_FAILURE(rcCheck)) { \
1456 RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1457 return (rcRet); \
1458 } \
1459 } while (0)
1460/** @def RTTESTI_CHECK_RC_OK_RETV
1461 * Check whether a IPRT style status code indicates success.
1462 *
1463 * If the status indicates failure, call RTTestIFailed giving the line number,
1464 * expression and status code, then return.
1465 *
1466 * @param rcExpr The expression resulting in an IPRT status code.
1467 */
1468#define RTTESTI_CHECK_RC_OK_RETV(rcExpr) \
1469 do { \
1470 int rcCheck = (rcExpr); \
1471 if (RT_FAILURE(rcCheck)) { \
1472 RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
1473 return; \
1474 } \
1475 } while (0)
1476
1477/** @} */
1478
1479
1480/** @} */
1481
1482RT_C_DECLS_END
1483
1484#endif /* !IPRT_INCLUDED_test_h */
1485
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