test.h revision 32af7dbaedf948b4fa22e2c7381f5d34ea51d8db
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/** @file
5b281ba489ca18f0380d7efc7a5108b606cce449vboxsync * IPRT - Testcase Framework.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync */
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/*
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync * Copyright (C) 2009 Oracle Corporation
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * available from http://www.virtualbox.org. This file is free software;
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * you can redistribute it and/or modify it under the terms of the GNU
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * General Public License (GPL) as published by the Free Software
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * The contents of this file may alternatively be used under the terms
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * of the Common Development and Distribution License Version 1.0
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * VirtualBox OSE distribution, in which case the provisions of the
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * CDDL are applicable instead of those of the GPL.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * You may elect to license modified versions of this file under the
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * terms and conditions of either the GPL or the CDDL or both.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync */
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync#ifndef ___iprt_test_h
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync#define ___iprt_test_h
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync#include <iprt/cdefs.h>
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync#include <iprt/types.h>
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync#include <iprt/stdarg.h>
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
590bfe12ce22cd3716448fbb9f4dc51664bfe5e2vboxsyncRT_C_DECLS_BEGIN
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/** @defgroup grp_rt_test RTTest - Testcase Framework.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @ingroup grp_rt
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @{
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync */
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/** A test handle. */
165b506f4c024dabd5a4caaeda31c66712d154eavboxsynctypedef struct RTTESTINT *RTTEST;
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync/** A pointer to a test handle. */
165b506f4c024dabd5a4caaeda31c66712d154eavboxsynctypedef RTTEST *PRTTEST;
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/** A const pointer to a test handle. */
165b506f4c024dabd5a4caaeda31c66712d154eavboxsynctypedef RTTEST const *PCRTTEST;
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/** A NIL Test handle. */
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync#define NIL_RTTEST ((RTTEST)0)
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/**
5c1381fc884d30a749517579368ff6cb4b43e809vboxsync * Test message importance level.
5c1381fc884d30a749517579368ff6cb4b43e809vboxsync */
5c1381fc884d30a749517579368ff6cb4b43e809vboxsynctypedef enum RTTESTLVL
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync{
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync /** Invalid 0. */
5c1381fc884d30a749517579368ff6cb4b43e809vboxsync RTTESTLVL_INVALID = 0,
5c1381fc884d30a749517579368ff6cb4b43e809vboxsync /** Message should always be printed. */
5c1381fc884d30a749517579368ff6cb4b43e809vboxsync RTTESTLVL_ALWAYS,
5c1381fc884d30a749517579368ff6cb4b43e809vboxsync /** Failure message. */
5c1381fc884d30a749517579368ff6cb4b43e809vboxsync RTTESTLVL_FAILURE,
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync /** Sub-test banner. */
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync RTTESTLVL_SUB_TEST,
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync /** Info message. */
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync RTTESTLVL_INFO,
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync /** Debug message. */
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync RTTESTLVL_DEBUG,
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync /** The last (invalid). */
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync RTTESTLVL_END
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync} RTTESTLVL;
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync/**
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync * Creates a test instance.
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync *
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * @returns IPRT status code.
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync * @param pszTest The test name.
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync * @param phTest Where to store the test instance handle.
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync */
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsyncRTR3DECL(int) RTTestCreate(const char *pszTest, PRTTEST phTest);
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync/**
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * Initializes IPRT and creates a test instance.
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync *
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * Typical usage is:
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * @code
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync int main(int argc, char **argv)
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync {
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync RTTEST hTest;
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync int rc = RTTestInitAndCreate("tstSomething", &hTest);
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync if (rc)
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync return rc;
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync ...
5e5603ae40c7a0a884fe91e269b7d6d6c0ba56f5vboxsync }
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync @endcode
5e5603ae40c7a0a884fe91e269b7d6d6c0ba56f5vboxsync *
5e5603ae40c7a0a884fe91e269b7d6d6c0ba56f5vboxsync * @returns RTEXITCODE_SUCCESS on success. On failure an error message is
5e5603ae40c7a0a884fe91e269b7d6d6c0ba56f5vboxsync * printed and a suitable exit code is return.
5e5603ae40c7a0a884fe91e269b7d6d6c0ba56f5vboxsync *
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * @param pszTest The test name.
5e5603ae40c7a0a884fe91e269b7d6d6c0ba56f5vboxsync * @param phTest Where to store the test instance handle.
5e5603ae40c7a0a884fe91e269b7d6d6c0ba56f5vboxsync */
ad27e1d5e48ca41245120c331cc88b50464813cevboxsyncRTR3DECL(RTEXITCODE) RTTestInitAndCreate(const char *pszTest, PRTTEST phTest);
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync/**
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * Destroys a test instance previously created by RTTestCreate.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync *
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @returns IPRT status code.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @param hTest The test handle. NIL_RTTEST is ignored.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync */
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsyncRTR3DECL(int) RTTestDestroy(RTTEST hTest);
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync/**
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * Changes the default test instance for the calling thread.
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync *
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * @returns IPRT status code.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync *
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @param hNewDefaultTest The new default test. NIL_RTTEST is fine.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @param phOldTest Where to store the old test handle. Optional.
6a5bc4dc98789eb202e249b189f036e5ff9129ccvboxsync */
2235e7604f29ce0edc7a1d9aa829668563f86867vboxsyncRTR3DECL(int) RTTestSetDefault(RTTEST hNewDefaultTest, PRTTEST phOldTest);
2235e7604f29ce0edc7a1d9aa829668563f86867vboxsync
2235e7604f29ce0edc7a1d9aa829668563f86867vboxsync/**
2235e7604f29ce0edc7a1d9aa829668563f86867vboxsync * Allocate a block of guarded memory.
6a5bc4dc98789eb202e249b189f036e5ff9129ccvboxsync *
6a5bc4dc98789eb202e249b189f036e5ff9129ccvboxsync * @returns IPRT status code.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * associated with the calling thread.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @param cb The amount of memory to allocate.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @param cbAlign The alignment of the returned block.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @param fHead Head or tail optimized guard.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @param ppvUser Where to return the pointer to the block.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync */
3c1c973ceaac2fdf7f3b0305f57ae30531acb9ccvboxsyncRTR3DECL(int) RTTestGuardedAlloc(RTTEST hTest, size_t cb, uint32_t cbAlign, bool fHead, void **ppvUser);
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync/**
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * Allocates a block of guarded memory where the guarded is immediately after
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * the user memory.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync *
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @returns Pointer to the allocated memory. NULL on failure.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * associated with the calling thread.
04bce18d27791abed8346aba0de41c53a2acd81avboxsync * @param cb The amount of memory to allocate.
04bce18d27791abed8346aba0de41c53a2acd81avboxsync */
04bce18d27791abed8346aba0de41c53a2acd81avboxsyncRTR3DECL(void *) RTTestGuardedAllocTail(RTTEST hTest, size_t cb);
04bce18d27791abed8346aba0de41c53a2acd81avboxsync
04bce18d27791abed8346aba0de41c53a2acd81avboxsync/**
04bce18d27791abed8346aba0de41c53a2acd81avboxsync * Allocates a block of guarded memory where the guarded is right in front of
6bfca32c67f507f862b751d90d7fa364d3f3844avboxsync * the user memory.
04bce18d27791abed8346aba0de41c53a2acd81avboxsync *
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * @returns Pointer to the allocated memory. NULL on failure.
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * associated with the calling thread.
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * @param cb The amount of memory to allocate.
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync */
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsyncRTR3DECL(void *) RTTestGuardedAllocHead(RTTEST hTest, size_t cb);
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync/**
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * Frees a block of guarded memory.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync *
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @returns IPRT status code.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * associated with the calling thread.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param pv The memory. NULL is ignored.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync */
e3e8bde164b5715114ebf596187b5512fa9b75advboxsyncRTR3DECL(int) RTTestGuardedFree(RTTEST hTest, void *pv);
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync/**
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * Test vprintf making sure the output starts on a new line.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync *
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @returns Number of chars printed.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * associated with the calling thread.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param enmLevel Message importance level.
04bce18d27791abed8346aba0de41c53a2acd81avboxsync * @param pszFormat The message.
04bce18d27791abed8346aba0de41c53a2acd81avboxsync * @param va Arguments.
04bce18d27791abed8346aba0de41c53a2acd81avboxsync */
04bce18d27791abed8346aba0de41c53a2acd81avboxsyncRTR3DECL(int) RTTestPrintfNlV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va);
04bce18d27791abed8346aba0de41c53a2acd81avboxsync
04bce18d27791abed8346aba0de41c53a2acd81avboxsync/**
04bce18d27791abed8346aba0de41c53a2acd81avboxsync * Test printf making sure the output starts on a new line.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync *
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @returns Number of chars printed.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * associated with the calling thread.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param enmLevel Message importance level.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param pszFormat The message.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param ... Arguments.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync */
e3e8bde164b5715114ebf596187b5512fa9b75advboxsyncRTR3DECL(int) RTTestPrintfNl(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...);
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync/**
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync * Test vprintf, makes sure lines are prefixed and so forth.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync *
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * @returns Number of chars printed.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * associated with the calling thread.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * @param enmLevel Message importance level.
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync * @param pszFormat The message.
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync * @param va Arguments.
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync */
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsyncRTR3DECL(int) RTTestPrintfV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va);
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync/**
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * Test printf, makes sure lines are prefixed and so forth.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync *
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * @returns Number of chars printed.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * associated with the calling thread.
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync * @param enmLevel Message importance level.
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync * @param pszFormat The message.
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync * @param ... Arguments.
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync */
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsyncRTR3DECL(int) RTTestPrintf(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...);
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync/**
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync * Prints the test banner.
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync *
ac76755aa3b8483a71b7e52674eaf3432cbda053vboxsync * @returns Number of chars printed.
ac76755aa3b8483a71b7e52674eaf3432cbda053vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync * associated with the calling thread.
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync */
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsyncRTR3DECL(int) RTTestBanner(RTTEST hTest);
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync/**
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * Summaries the test, destroys the test instance and return an exit code.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @returns Test program exit code.
d9658602103599d13b5449fc1ea49d765a23e6f1vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
d9658602103599d13b5449fc1ea49d765a23e6f1vboxsync * associated with the calling thread.
d9658602103599d13b5449fc1ea49d765a23e6f1vboxsync */
d9658602103599d13b5449fc1ea49d765a23e6f1vboxsyncRTR3DECL(RTEXITCODE) RTTestSummaryAndDestroy(RTTEST hTest);
d9658602103599d13b5449fc1ea49d765a23e6f1vboxsync
d9658602103599d13b5449fc1ea49d765a23e6f1vboxsync/**
d9658602103599d13b5449fc1ea49d765a23e6f1vboxsync * Skips the test, destroys the test instance and return an exit code.
d9658602103599d13b5449fc1ea49d765a23e6f1vboxsync *
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @returns Test program exit code.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * associated with the calling thread.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @param pszReasonFmt Text explaining why, optional (NULL).
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param va Arguments for the reason format string.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync */
165b506f4c024dabd5a4caaeda31c66712d154eavboxsyncRTR3DECL(RTEXITCODE) RTTestSkipAndDestroyV(RTTEST hTest, const char *pszReasonFmt, va_list va);
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
e0dec59adb362e8486c0622785420ad10e720972vboxsync/**
e0dec59adb362e8486c0622785420ad10e720972vboxsync * Skips the test, destroys the test instance and return an exit code.
e0dec59adb362e8486c0622785420ad10e720972vboxsync *
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @returns Test program exit code.
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * associated with the calling thread.
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * @param pszReasonFmt Text explaining why, optional (NULL).
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * @param ... Arguments for the reason format string.
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsyncRTR3DECL(RTEXITCODE) RTTestSkipAndDestroy(RTTEST hTest, const char *pszReasonFmt, ...);
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync/**
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * Starts a sub-test.
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync *
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * This will perform an implicit RTTestSubDone() call if that has not been done
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * since the last RTTestSub call.
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync *
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync * @returns Number of chars printed.
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync * associated with the calling thread.
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync * @param pszSubTest The sub-test name.
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync */
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsyncRTR3DECL(int) RTTestSub(RTTEST hTest, const char *pszSubTest);
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync/**
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync * Format string version of RTTestSub.
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync *
c0b6af690ad705bddfa87c643b89770a7a0aaf5avboxsync * See RTTestSub for details.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @returns Number of chars printed.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * associated with the calling thread.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param pszSubTestFmt The sub-test name format string.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param ... Arguments.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync */
165b506f4c024dabd5a4caaeda31c66712d154eavboxsyncRTR3DECL(int) RTTestSubF(RTTEST hTest, const char *pszSubTestFmt, ...);
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync/**
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Format string version of RTTestSub.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * See RTTestSub for details.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
e0dec59adb362e8486c0622785420ad10e720972vboxsync * @returns Number of chars printed.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * associated with the calling thread.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param pszSubTestFmt The sub-test name format string.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @param va Arguments.
fa86ccda70bc5dd1ae28597340f252b212dcf36dvboxsync */
fa86ccda70bc5dd1ae28597340f252b212dcf36dvboxsyncRTR3DECL(int) RTTestSubV(RTTEST hTest, const char *pszSubTestFmt, va_list va);
fa86ccda70bc5dd1ae28597340f252b212dcf36dvboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/**
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Completes a sub-test.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @returns Number of chars printed.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * associated with the calling thread.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync */
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsyncRTR3DECL(int) RTTestSubDone(RTTEST hTest);
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/**
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Prints an extended PASSED message, optional.
e0dec59adb362e8486c0622785420ad10e720972vboxsync *
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * This does not conclude the sub-test, it could be used to report the passing
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * of a sub-sub-to-the-power-of-N-test.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @returns IPRT status code.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * associated with the calling thread.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param pszFormat The message. No trailing newline.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param va The arguments.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync */
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsyncRTR3DECL(int) RTTestPassedV(RTTEST hTest, const char *pszFormat, va_list va);
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/**
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * Prints an extended PASSED message, optional.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync *
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * This does not conclude the sub-test, it could be used to report the passing
e0dec59adb362e8486c0622785420ad10e720972vboxsync * of a sub-sub-to-the-power-of-N-test.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * @returns IPRT status code.
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * associated with the calling thread.
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * @param pszFormat The message. No trailing newline.
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * @param ... The arguments.
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsyncRTR3DECL(int) RTTestPassed(RTTEST hTest, const char *pszFormat, ...);
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync/**
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync * Value units.
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsynctypedef enum RTTESTUNIT
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync{
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** The usual invalid value. */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync RTTESTUNIT_INVALID = 0,
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** Percentage (10^-2). */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync RTTESTUNIT_PCT,
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** Bytes. */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync RTTESTUNIT_BYTES,
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** Bytes per second. */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync RTTESTUNIT_BYTES_PER_SEC,
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** Kilobytes. */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync RTTESTUNIT_KILOBYTES,
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** Kilobytes per second. */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync RTTESTUNIT_KILOBYTES_PER_SEC,
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** Megabytes. */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync RTTESTUNIT_MEGABYTES,
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** Megabytes per second. */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync RTTESTUNIT_MEGABYTES_PER_SEC,
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** Packets. */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync RTTESTUNIT_PACKETS,
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** Packets per second. */
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync RTTESTUNIT_PACKETS_PER_SEC,
4ba3599814cc63307fe48a5d47394ae7c6f391e6vboxsync /** Frames. */
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync RTTESTUNIT_FRAMES,
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync /** Frames per second. */
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync RTTESTUNIT_FRAMES_PER_SEC,
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync /** Occurrences. */
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync RTTESTUNIT_OCCURRENCES,
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync /** Occurrences per second. */
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync RTTESTUNIT_OCCURRENCES_PER_SEC,
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync /** Calls. */
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync RTTESTUNIT_CALLS,
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync /** Calls per second. */
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync RTTESTUNIT_CALLS_PER_SEC,
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync /** Round trips. */
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync RTTESTUNIT_ROUND_TRIP,
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync /** Seconds. */
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync RTTESTUNIT_SECS,
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync /** Milliseconds. */
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync RTTESTUNIT_MS,
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync /** Nanoseconds. */
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync RTTESTUNIT_NS,
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync /** Nanoseconds per call. */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync RTTESTUNIT_NS_PER_CALL,
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync /** Nanoseconds per frame. */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync RTTESTUNIT_NS_PER_FRAME,
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync /** Nanoseconds per occurrence. */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync RTTESTUNIT_NS_PER_OCCURRENCE,
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync /** Nanoseconds per frame. */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync RTTESTUNIT_NS_PER_PACKET,
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync /** Nanoseconds per round trip. */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync RTTESTUNIT_NS_PER_ROUND_TRIP,
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync /** Parts per thousand (10^-3). */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync RTTESTUNIT_PP1K,
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync /** Parts per ten thousand (10^-4). */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync RTTESTUNIT_PP10K,
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync /** Parts per million (10^-6). */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync RTTESTUNIT_PPM,
9c0a6e4256c062f83da67f49727042ce66272ef6vboxsync /** Parts per billion (10^-9). */
9c0a6e4256c062f83da67f49727042ce66272ef6vboxsync RTTESTUNIT_PPB,
9c0a6e4256c062f83da67f49727042ce66272ef6vboxsync /** The end of valid units. */
107145464a0dfa38b6017b2d8a377aa5f4e49605vboxsync RTTESTUNIT_END
107145464a0dfa38b6017b2d8a377aa5f4e49605vboxsync} RTTESTUNIT;
107145464a0dfa38b6017b2d8a377aa5f4e49605vboxsync
9c0a6e4256c062f83da67f49727042ce66272ef6vboxsync/**
a3231a71cbaa971ead3788ec264543941580b513vboxsync * Report a named test result value.
a3231a71cbaa971ead3788ec264543941580b513vboxsync *
9c0a6e4256c062f83da67f49727042ce66272ef6vboxsync * This is typically used for benchmarking but can be used for other purposes
107145464a0dfa38b6017b2d8a377aa5f4e49605vboxsync * like reporting limits of some implementation. The value gets associated with
107145464a0dfa38b6017b2d8a377aa5f4e49605vboxsync * the current sub test, the name must be unique within the sub test.
9c0a6e4256c062f83da67f49727042ce66272ef6vboxsync *
9c0a6e4256c062f83da67f49727042ce66272ef6vboxsync * @returns IPRT status code.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync *
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * associated with the calling thread.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param pszName The value name.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param u64Value The value.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param enmUnit The value unit.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsyncRTR3DECL(int) RTTestValue(RTTEST hTest, const char *pszName, uint64_t u64Value, RTTESTUNIT enmUnit);
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync/**
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * Same as RTTestValue, except that the name is now a format string.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync *
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @returns IPRT status code.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync *
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
34bfec0bd844700e3b769dcfad1a869ca6b8a0d8vboxsync * associated with the calling thread.
34bfec0bd844700e3b769dcfad1a869ca6b8a0d8vboxsync * @param u64Value The value.
34bfec0bd844700e3b769dcfad1a869ca6b8a0d8vboxsync * @param enmUnit The value unit.
34bfec0bd844700e3b769dcfad1a869ca6b8a0d8vboxsync * @param pszNameFmt The value name format string.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param ... String arguments.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsyncRTR3DECL(int) RTTestValueF(RTTEST hTest, uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, ...);
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync/**
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * Same as RTTestValue, except that the name is now a format string.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync *
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @returns IPRT status code.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync *
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * associated with the calling thread.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param u64Value The value.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param enmUnit The value unit.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param pszNameFmt The value name format string.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param va_list String arguments.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsyncRTR3DECL(int) RTTestValueV(RTTEST hTest, uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, va_list va);
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync/**
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * Increments the error counter.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync *
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @returns IPRT status code.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * associated with the calling thread.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsyncRTR3DECL(int) RTTestErrorInc(RTTEST hTest);
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/**
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Get the current error count.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync *
590bfe12ce22cd3716448fbb9f4dc51664bfe5e2vboxsync * @returns The error counter, UINT32_MAX if no valid test handle.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param hTest The test handle. If NIL_RTTEST we'll use the one
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * associated with the calling thread.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync */
RTR3DECL(uint32_t) RTTestErrorCount(RTTEST hTest);
/**
* Increments the error counter and prints a failure message.
*
* @returns IPRT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszFormat The message. No trailing newline.
* @param va The arguments.
*/
RTR3DECL(int) RTTestFailedV(RTTEST hTest, const char *pszFormat, va_list va);
/**
* Increments the error counter and prints a failure message.
*
* @returns IPRT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszFormat The message. No trailing newline.
* @param ... The arguments.
*/
RTR3DECL(int) RTTestFailed(RTTEST hTest, const char *pszFormat, ...);
/**
* Same as RTTestPrintfV with RTTESTLVL_FAILURE.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszFormat The message.
* @param va Arguments.
*/
RTR3DECL(int) RTTestFailureDetailsV(RTTEST hTest, const char *pszFormat, va_list va);
/**
* Same as RTTestPrintf with RTTESTLVL_FAILURE.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszFormat The message.
* @param ... Arguments.
*/
RTR3DECL(int) RTTestFailureDetails(RTTEST hTest, const char *pszFormat, ...);
/** @def RTTEST_CHECK
* Check whether a boolean expression holds true.
*
* If the expression is false, call RTTestFailed giving the line number and expression.
*
* @param hTest The test handle.
* @param expr The expression to evaluate.
*/
#define RTTEST_CHECK(hTest, expr) \
do { if (!(expr)) { \
RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
} \
} while (0)
/** @def RTTEST_CHECK_RET
* Check whether a boolean expression holds true, returns on false.
*
* If the expression is false, call RTTestFailed giving the line number and
* expression, then return @a rcRet.
*
* @param hTest The test handle.
* @param expr The expression to evaluate.
* @param rcRet What to return on failure.
*/
#define RTTEST_CHECK_RET(hTest, expr, rcRet) \
do { if (!(expr)) { \
RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
return (rcRet); \
} \
} while (0)
/** @def RTTEST_CHECK_RETV
* Check whether a boolean expression holds true, returns void on false.
*
* If the expression is false, call RTTestFailed giving the line number and
* expression, then return void.
*
* @param hTest The test handle.
* @param expr The expression to evaluate.
*/
#define RTTEST_CHECK_RETV(hTest, expr) \
do { if (!(expr)) { \
RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
return; \
} \
} while (0)
/** @def RTTEST_CHECK_BREAK
* Check whether a boolean expression holds true.
*
* If the expression is false, call RTTestFailed giving the line number and
* expression, then break.
*
* @param hTest The test handle.
* @param expr The expression to evaluate.
*/
#define RTTEST_CHECK_BREAK(hTest, expr) \
if (!(expr)) { \
RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
break; \
} else do {} while (0)
/** @def RTTEST_CHECK_MSG
* Check whether a boolean expression holds true.
*
* If the expression is false, call RTTestFailed giving the line number and expression.
*
* @param hTest The test handle.
* @param expr The expression to evaluate.
* @param DetailsArgs Argument list for RTTestFailureDetails, including
* parenthesis.
*/
#define RTTEST_CHECK_MSG(hTest, expr, DetailsArgs) \
do { if (!(expr)) { \
RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
RTTestFailureDetails DetailsArgs; \
} \
} while (0)
/** @def RTTEST_CHECK_MSG_RET
* Check whether a boolean expression holds true, returns on false.
*
* If the expression is false, call RTTestFailed giving the line number and expression.
*
* @param hTest The test handle.
* @param expr The expression to evaluate.
* @param DetailsArgs Argument list for RTTestFailureDetails, including
* parenthesis.
* @param rcRet What to return on failure.
*/
#define RTTEST_CHECK_MSG_RET(hTest, expr, DetailsArgs, rcRet) \
do { if (!(expr)) { \
RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
RTTestFailureDetails DetailsArgs; \
return (rcRet); \
} \
} while (0)
/** @def RTTEST_CHECK_MSG_RET
* Check whether a boolean expression holds true, returns void on false.
*
* If the expression is false, call RTTestFailed giving the line number and expression.
*
* @param hTest The test handle.
* @param expr The expression to evaluate.
* @param DetailsArgs Argument list for RTTestFailureDetails, including
* parenthesis.
*/
#define RTTEST_CHECK_MSG_RETV(hTest, expr, DetailsArgs) \
do { if (!(expr)) { \
RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
RTTestFailureDetails DetailsArgs; \
return; \
} \
} while (0)
/** @def RTTEST_CHECK_RC
* Check whether an expression returns a specific IPRT style status code.
*
* If a different status code is return, call RTTestFailed giving the line
* number, expression, actual and expected status codes.
*
* @param hTest The test handle.
* @param rcExpr The expression resulting in an IPRT status code.
* @param rcExpect The expected return code. This may be referenced
* more than once by the macro.
*/
#define RTTEST_CHECK_RC(hTest, rcExpr, rcExpect) \
do { \
int rcCheck = (rcExpr); \
if (rcCheck != (rcExpect)) { \
RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
} \
} while (0)
/** @def RTTEST_CHECK_RC_RET
* Check whether an expression returns a specific IPRT style status code.
*
* If a different status code is return, call RTTestFailed giving the line
* number, expression, actual and expected status codes, then return.
*
* @param hTest The test handle.
* @param rcExpr The expression resulting in an IPRT status code.
* This will be assigned to a local rcCheck variable
* that can be used as return value.
* @param rcExpect The expected return code. This may be referenced
* more than once by the macro.
* @param rcRet The return code.
*/
#define RTTEST_CHECK_RC_RET(hTest, rcExpr, rcExpect, rcRet) \
do { \
int rcCheck = (rcExpr); \
if (rcCheck != (rcExpect)) { \
RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
return (rcRet); \
} \
} while (0)
/** @def RTTEST_CHECK_RC_RETV
* Check whether an expression returns a specific IPRT style status code.
*
* If a different status code is return, call RTTestFailed giving the line
* number, expression, actual and expected status codes, then return.
*
* @param hTest The test handle.
* @param rcExpr The expression resulting in an IPRT status code.
* @param rcExpect The expected return code. This may be referenced
* more than once by the macro.
*/
#define RTTEST_CHECK_RC_RETV(hTest, rcExpr, rcExpect) \
do { \
int rcCheck = (rcExpr); \
if (rcCheck != (rcExpect)) { \
RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
return; \
} \
} while (0)
/** @def RTTEST_CHECK_RC_BREAK
* Check whether an expression returns a specific IPRT style status code.
*
* If a different status code is return, call RTTestFailed giving the line
* number, expression, actual and expected status codes, then break.
*
* @param hTest The test handle.
* @param rcExpr The expression resulting in an IPRT status code.
* @param rcExpect The expected return code. This may be referenced
* more than once by the macro.
*/
#define RTTEST_CHECK_RC_BREAK(hTest, rcExpr, rcExpect) \
if (1) { \
int rcCheck = (rcExpr); \
if (rcCheck != (rcExpect)) { \
RTTestFailed((hTest), "line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
break; \
} \
} else do {} while (0)
/** @def RTTEST_CHECK_RC_OK
* Check whether a IPRT style status code indicates success.
*
* If the status indicates failure, call RTTestFailed giving the line number,
* expression and status code.
*
* @param hTest The test handle.
* @param rcExpr The expression resulting in an IPRT status code.
*/
#define RTTEST_CHECK_RC_OK(hTest, rcExpr) \
do { \
int rcCheck = (rcExpr); \
if (RT_FAILURE(rcCheck)) { \
RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
} \
} while (0)
/** @def RTTEST_CHECK_RC_OK_RET
* Check whether a IPRT style status code indicates success.
*
* If the status indicates failure, call RTTestFailed giving the line number,
* expression and status code, then return with the specified value.
*
* @param hTest The test handle.
* @param rcExpr The expression resulting in an IPRT status code.
* This will be assigned to a local rcCheck variable
* that can be used as return value.
* @param rcRet The return code.
*/
#define RTTEST_CHECK_RC_OK_RET(hTest, rcExpr, rcRet) \
do { \
int rcCheck = (rcExpr); \
if (RT_FAILURE(rcCheck)) { \
RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
return (rcRet); \
} \
} while (0)
/** @def RTTEST_CHECK_RC_OK_RETV
* Check whether a IPRT style status code indicates success.
*
* If the status indicates failure, call RTTestFailed giving the line number,
* expression and status code, then return.
*
* @param hTest The test handle.
* @param rcExpr The expression resulting in an IPRT status code.
*/
#define RTTEST_CHECK_RC_OK_RETV(hTest, rcExpr) \
do { \
int rcCheck = (rcExpr); \
if (RT_FAILURE(rcCheck)) { \
RTTestFailed((hTest), "line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
return; \
} \
} while (0)
/** @name Implicit Test Handle API Variation
* The test handle is retrieved from the test TLS entry of the calling thread.
* @{
*/
/**
* Test vprintf, makes sure lines are prefixed and so forth.
*
* @returns Number of chars printed.
* @param enmLevel Message importance level.
* @param pszFormat The message.
* @param va Arguments.
*/
RTR3DECL(int) RTTestIPrintfV(RTTESTLVL enmLevel, const char *pszFormat, va_list va);
/**
* Test printf, makes sure lines are prefixed and so forth.
*
* @returns Number of chars printed.
* @param enmLevel Message importance level.
* @param pszFormat The message.
* @param ... Arguments.
*/
RTR3DECL(int) RTTestIPrintf(RTTESTLVL enmLevel, const char *pszFormat, ...);
/**
* Starts a sub-test.
*
* This will perform an implicit RTTestSubDone() call if that has not been done
* since the last RTTestSub call.
*
* @returns Number of chars printed.
* @param pszSubTest The sub-test name.
*/
RTR3DECL(int) RTTestISub(const char *pszSubTest);
/**
* Format string version of RTTestSub.
*
* See RTTestSub for details.
*
* @returns Number of chars printed.
* @param pszSubTestFmt The sub-test name format string.
* @param ... Arguments.
*/
RTR3DECL(int) RTTestISubF(const char *pszSubTestFmt, ...);
/**
* Format string version of RTTestSub.
*
* See RTTestSub for details.
*
* @returns Number of chars printed.
* @param pszSubTestFmt The sub-test name format string.
* @param va Arguments.
*/
RTR3DECL(int) RTTestISubV(const char *pszSubTestFmt, va_list va);
/**
* Completes a sub-test.
*
* @returns Number of chars printed.
*/
RTR3DECL(int) RTTestISubDone(void);
/**
* Prints an extended PASSED message, optional.
*
* This does not conclude the sub-test, it could be used to report the passing
* of a sub-sub-to-the-power-of-N-test.
*
* @returns IPRT status code.
* @param pszFormat The message. No trailing newline.
* @param va The arguments.
*/
RTR3DECL(int) RTTestIPassedV(const char *pszFormat, va_list va);
/**
* Prints an extended PASSED message, optional.
*
* This does not conclude the sub-test, it could be used to report the passing
* of a sub-sub-to-the-power-of-N-test.
*
* @returns IPRT status code.
* @param pszFormat The message. No trailing newline.
* @param ... The arguments.
*/
RTR3DECL(int) RTTestIPassed(const char *pszFormat, ...);
/**
* Report a named test result value.
*
* This is typically used for benchmarking but can be used for other purposes
* like reporting limits of some implementation. The value gets associated with
* the current sub test, the name must be unique within the sub test.
*
* @returns IPRT status code.
*
* @param pszName The value name.
* @param u64Value The value.
* @param enmUnit The value unit.
*/
RTR3DECL(int) RTTestIValue(const char *pszName, uint64_t u64Value, RTTESTUNIT enmUnit);
/**
* Same as RTTestValue, except that the name is now a format string.
*
* @returns IPRT status code.
*
* @param u64Value The value.
* @param enmUnit The value unit.
* @param pszNameFmt The value name format string.
* @param ... String arguments.
*/
RTR3DECL(int) RTTestIValueF(uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, ...);
/**
* Same as RTTestValue, except that the name is now a format string.
*
* @returns IPRT status code.
*
* @param u64Value The value.
* @param enmUnit The value unit.
* @param pszNameFmt The value name format string.
* @param va_list String arguments.
*/
RTR3DECL(int) RTTestIValueV(uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, va_list va);
/**
* Increments the error counter.
*
* @returns IPRT status code.
*/
RTR3DECL(int) RTTestIErrorInc(void);
/**
* Get the current error count.
*
* @returns The error counter, UINT32_MAX if no valid test handle.
*/
RTR3DECL(uint32_t) RTTestIErrorCount(void);
/**
* Increments the error counter and prints a failure message.
*
* @returns IPRT status code.
* @param pszFormat The message. No trailing newline.
* @param va The arguments.
*/
RTR3DECL(int) RTTestIFailedV(const char *pszFormat, va_list va);
/**
* Increments the error counter and prints a failure message.
*
* @returns IPRT status code.
* @param pszFormat The message. No trailing newline.
* @param ... The arguments.
*/
RTR3DECL(int) RTTestIFailed(const char *pszFormat, ...);
/**
* Increments the error counter, prints a failure message and returns the
* specified status code.
*
* This is mainly a convenience method for saving vertical space in the source
* code.
*
* @returns @a rcRet
* @param rcRet The IPRT status code to return.
* @param pszFormat The message. No trailing newline.
* @param va The arguments.
*/
RTR3DECL(int) RTTestIFailedRcV(int rcRet, const char *pszFormat, va_list va);
/**
* Increments the error counter, prints a failure message and returns the
* specified status code.
*
* This is mainly a convenience method for saving vertical space in the source
* code.
*
* @returns @a rcRet
* @param rcRet The IPRT status code to return.
* @param pszFormat The message. No trailing newline.
* @param ... The arguments.
*/
RTR3DECL(int) RTTestIFailedRc(int rcRet, const char *pszFormat, ...);
/**
* Same as RTTestIPrintfV with RTTESTLVL_FAILURE.
*
* @returns Number of chars printed.
* @param pszFormat The message.
* @param va Arguments.
*/
RTR3DECL(int) RTTestIFailureDetailsV(const char *pszFormat, va_list va);
/**
* Same as RTTestIPrintf with RTTESTLVL_FAILURE.
*
* @returns Number of chars printed.
* @param pszFormat The message.
* @param ... Arguments.
*/
RTR3DECL(int) RTTestIFailureDetails(const char *pszFormat, ...);
/** @def RTTESTI_CHECK
* Check whether a boolean expression holds true.
*
* If the expression is false, call RTTestIFailed giving the line number and
* expression.
*
* @param expr The expression to evaluate.
*/
#define RTTESTI_CHECK(expr) \
do { if (!(expr)) { \
RTTestIFailed("line %u: %s", __LINE__, #expr); \
} \
} while (0)
/** @def RTTESTI_CHECK_RET
* Check whether a boolean expression holds true, returns on false.
*
* If the expression is false, call RTTestIFailed giving the line number and
* expression, then return @a rcRet.
*
* @param expr The expression to evaluate.
* @param rcRet What to return on failure.
*/
#define RTTESTI_CHECK_RET(expr, rcRet) \
do { if (!(expr)) { \
RTTestIFailed("line %u: %s", __LINE__, #expr); \
return (rcRet); \
} \
} while (0)
/** @def RTTESTI_CHECK_RETV
* Check whether a boolean expression holds true, returns void on false.
*
* If the expression is false, call RTTestIFailed giving the line number and
* expression, then return void.
*
* @param expr The expression to evaluate.
*/
#define RTTESTI_CHECK_RETV(expr) \
do { if (!(expr)) { \
RTTestIFailed("line %u: %s", __LINE__, #expr); \
return; \
} \
} while (0)
/** @def RTTESTI_CHECK_RETV
* Check whether a boolean expression holds true, returns void on false.
*
* If the expression is false, call RTTestIFailed giving the line number and
* expression, then break.
*
* @param expr The expression to evaluate.
*/
#define RTTESTI_CHECK_BREAK(expr) \
if (!(expr)) { \
RTTestIFailed("line %u: %s", __LINE__, #expr); \
break; \
} do {} while (0)
/** @def RTTESTI_CHECK_MSG
* Check whether a boolean expression holds true.
*
* If the expression is false, call RTTestIFailed giving the line number and
* expression.
*
* @param expr The expression to evaluate.
* @param DetailsArgs Argument list for RTTestIFailureDetails, including
* parenthesis.
*/
#define RTTESTI_CHECK_MSG(expr, DetailsArgs) \
do { if (!(expr)) { \
RTTestIFailed("line %u: %s", __LINE__, #expr); \
RTTestIFailureDetails DetailsArgs; \
} \
} while (0)
/** @def RTTESTI_CHECK_MSG_RET
* Check whether a boolean expression holds true, returns on false.
*
* If the expression is false, call RTTestIFailed giving the line number and
* expression.
*
* @param expr The expression to evaluate.
* @param DetailsArgs Argument list for RTTestIFailureDetails, including
* parenthesis.
* @param rcRet What to return on failure.
*/
#define RTTESTI_CHECK_MSG_RET(expr, DetailsArgs, rcRet) \
do { if (!(expr)) { \
RTTestIFailed("line %u: %s", __LINE__, #expr); \
RTTestIFailureDetails DetailsArgs; \
return (rcRet); \
} \
} while (0)
/** @def RTTESTI_CHECK_MSG_RET
* Check whether a boolean expression holds true, returns void on false.
*
* If the expression is false, call RTTestIFailed giving the line number and
* expression.
*
* @param expr The expression to evaluate.
* @param DetailsArgs Argument list for RTTestIFailureDetails, including
* parenthesis.
*/
#define RTTESTI_CHECK_MSG_RETV(expr, DetailsArgs) \
do { if (!(expr)) { \
RTTestIFailed("line %u: %s", __LINE__, #expr); \
RTTestIFailureDetails DetailsArgs; \
return; \
} \
} while (0)
/** @def RTTESTI_CHECK_RC
* Check whether an expression returns a specific IPRT style status code.
*
* If a different status code is return, call RTTestIFailed giving the line
* number, expression, actual and expected status codes.
*
* @param rcExpr The expression resulting in an IPRT status code.
* @param rcExpect The expected return code. This may be referenced
* more than once by the macro.
*/
#define RTTESTI_CHECK_RC(rcExpr, rcExpect) \
do { \
int rcCheck = (rcExpr); \
if (rcCheck != (rcExpect)) { \
RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
} \
} while (0)
/** @def RTTESTI_CHECK_RC_RET
* Check whether an expression returns a specific IPRT style status code.
*
* If a different status code is return, call RTTestIFailed giving the line
* number, expression, actual and expected status codes, then return.
*
* @param rcExpr The expression resulting in an IPRT status code.
* This will be assigned to a local rcCheck variable
* that can be used as return value.
* @param rcExpect The expected return code. This may be referenced
* more than once by the macro.
* @param rcRet The return code.
*/
#define RTTESTI_CHECK_RC_RET(rcExpr, rcExpect, rcRet) \
do { \
int rcCheck = (rcExpr); \
if (rcCheck != (rcExpect)) { \
RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
return (rcRet); \
} \
} while (0)
/** @def RTTESTI_CHECK_RC_RETV
* Check whether an expression returns a specific IPRT style status code.
*
* If a different status code is return, call RTTestIFailed giving the line
* number, expression, actual and expected status codes, then return.
*
* @param rcExpr The expression resulting in an IPRT status code.
* @param rcExpect The expected return code. This may be referenced
* more than once by the macro.
*/
#define RTTESTI_CHECK_RC_RETV(rcExpr, rcExpect) \
do { \
int rcCheck = (rcExpr); \
if (rcCheck != (rcExpect)) { \
RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
return; \
} \
} while (0)
/** @def RTTESTI_CHECK_RC_BREAK
* Check whether an expression returns a specific IPRT style status code.
*
* If a different status code is return, call RTTestIFailed giving the line
* number, expression, actual and expected status codes, then break.
*
* @param rcExpr The expression resulting in an IPRT status code.
* @param rcExpect The expected return code. This may be referenced
* more than once by the macro.
*/
#define RTTESTI_CHECK_RC_BREAK(rcExpr, rcExpect) \
if (1) { \
int rcCheck = (rcExpr); \
if (rcCheck != (rcExpect)) { \
RTTestIFailed("line %u: %s: expected %Rrc, got %Rrc", __LINE__, #rcExpr, (rcExpect), rcCheck); \
break; \
} \
} else do {} while (0)
/** @def RTTESTI_CHECK_RC_OK
* Check whether a IPRT style status code indicates success.
*
* If the status indicates failure, call RTTestIFailed giving the line number,
* expression and status code.
*
* @param rcExpr The expression resulting in an IPRT status code.
*/
#define RTTESTI_CHECK_RC_OK(rcExpr) \
do { \
int rcCheck = (rcExpr); \
if (RT_FAILURE(rcCheck)) { \
RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
} \
} while (0)
/** @def RTTESTI_CHECK_RC_OK_RET
* Check whether a IPRT style status code indicates success.
*
* If the status indicates failure, call RTTestIFailed giving the line number,
* expression and status code, then return with the specified value.
*
* @param rcExpr The expression resulting in an IPRT status code.
* This will be assigned to a local rcCheck variable
* that can be used as return value.
* @param rcRet The return code.
*/
#define RTTESTI_CHECK_RC_OK_RET(rcExpr, rcRet) \
do { \
int rcCheck = (rcExpr); \
if (RT_FAILURE(rcCheck)) { \
RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
return (rcRet); \
} \
} while (0)
/** @def RTTESTI_CHECK_RC_OK_RETV
* Check whether a IPRT style status code indicates success.
*
* If the status indicates failure, call RTTestIFailed giving the line number,
* expression and status code, then return.
*
* @param rcExpr The expression resulting in an IPRT status code.
*/
#define RTTESTI_CHECK_RC_OK_RETV(rcExpr) \
do { \
int rcCheck = (rcExpr); \
if (RT_FAILURE(rcCheck)) { \
RTTestIFailed("line %u: %s: %Rrc", __LINE__, #rcExpr, rcCheck); \
return; \
} \
} while (0)
/** @} */
/** @} */
RT_C_DECLS_END
#endif