/** @file
* IPRT - Testcase Framework.
*/
/*
* Copyright (C) 2009-2013 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___iprt_test_h
#define ___iprt_test_h
/** @defgroup grp_rt_test RTTest - Testcase Framework.
* @ingroup grp_rt
* @{
*/
/** A test handle. */
/** A pointer to a test handle. */
/** A const pointer to a test handle. */
/** A NIL Test handle. */
/**
* Test message importance level.
*/
typedef enum RTTESTLVL
{
/** Invalid 0. */
RTTESTLVL_INVALID = 0,
/** Message should always be printed. */
/** Failure message. */
/** Sub-test banner. */
/** Info message. */
/** Debug message. */
/** The last (invalid). */
} RTTESTLVL;
/**
* Creates a test instance.
*
* @returns IPRT status code.
* @param pszTest The test name.
* @param phTest Where to store the test instance handle.
*/
/** @name RTTEST_C_XXX - Flags for RTTestCreateEx.
* @{ */
/** Whether to check the IPRT_TEST_XXX variables when constructing the
* instance. The following environment variables get checks:
*
* - IPRT_TEST_MAX_LEVEL: String value indicating which level.
* The env. var. is applied if the program specified the default level
* (by passing RTTESTLVL_INVALID).
*
* results to.
* The env. var. is applied if iNativeTestPipe is -1.
*
* - IPRT_TEST_FILE: Path to file/named-pipe/fifo/whatever to
* write XML results to.
* The env. var. is applied if the program specified a NULL path, it is
* not applied if the program hands us an empty string.
*
* - IPRT_TEST_OMIT_TOP_TEST: If present, this makes the XML output omit
* the top level test element.
* The env. var is applied when present.
*
*/
/** Whether to omit the top test in the XML. */
/** Whether to delay the top test XML element until testing commences. */
/** Whether to try install the test instance in the test TLS slot. Setting
* this flag is incompatible with using the RTTestIXxxx variant of the API. */
/** Mask containing the valid bits. */
/** @} */
/**
* Creates a test instance.
*
* @returns IPRT status code.
* @param pszTest The test name.
* @param fFlags Flags, see RTTEST_C_XXX.
* @param enmMaxLevel The max message level. Use RTTESTLVL_INVALID for
* the default output level or one from the
* environment. If specified, the environment variable
* will not be able to override it.
* @param iNativeTestPipe Native handle to a test pipe. -1 if not interested.
* @param pszXmlFile The XML output file name. If NULL the environment
* may be used. To selectively avoid that, pass an
* empty string.
* @param phTest Where to store the test instance handle.
*
* @note At the moment, we don't fail if @a pszXmlFile or @a iNativeTestPipe
* fails to open. This may change later.
*/
/**
* Initializes IPRT and creates a test instance.
*
* Typical usage is:
* @code
int main(int argc, char **argv)
{
RTTEST hTest;
int rc = RTTestInitAndCreate("tstSomething", &hTest);
if (rc)
return rc;
...
}
@endcode
*
* @returns RTEXITCODE_SUCCESS on success. On failure an error message is
* printed and a suitable exit code is return.
*
* @param pszTest The test name.
* @param phTest Where to store the test instance handle.
*/
/**
* Variant of RTTestInitAndCreate that includes IPRT init flags and argument
* vectors.
*
* @returns RTEXITCODE_SUCCESS on success. On failure an error message is
* printed and a suitable exit code is return.
*
* @param cArgs Pointer to the argument count.
* @param ppapszArgs Pointer to the argument vector pointer.
* @param fRtInit Flags, see RTR3INIT_XXX.
* @param pszTest The test name.
* @param phTest Where to store the test instance handle.
*/
RTR3DECL(RTEXITCODE) RTTestInitExAndCreate(int cArgs, char ***papszArgs, uint32_t fRtInit, const char *pszTest, PRTTEST phTest);
/**
* Destroys a test instance previously created by RTTestCreate.
*
* @returns IPRT status code.
* @param hTest The test handle. NIL_RTTEST is ignored.
*/
/**
* Changes the default test instance for the calling thread.
*
* @returns IPRT status code.
*
* @param hNewDefaultTest The new default test. NIL_RTTEST is fine.
* @param phOldTest Where to store the old test handle. Optional.
*/
/**
* Changes the test case name.
*
* @returns IRPT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszName The new test case name. Empty string is not accepted,
* nor are strings longer than 127 chars. Keep it short
* but descriptive.
*/
/**
* Allocate a block of guarded memory.
*
* @returns IPRT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param cb The amount of memory to allocate.
* @param cbAlign The alignment of the returned block.
* @param fHead Head or tail optimized guard.
* @param ppvUser Where to return the pointer to the block.
*/
RTR3DECL(int) RTTestGuardedAlloc(RTTEST hTest, size_t cb, uint32_t cbAlign, bool fHead, void **ppvUser);
/**
* Allocates a block of guarded memory where the guarded is immediately after
* the user memory.
*
* @returns Pointer to the allocated memory. NULL on failure.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param cb The amount of memory to allocate.
*/
/**
* Allocates a block of guarded memory where the guarded is right in front of
* the user memory.
*
* @returns Pointer to the allocated memory. NULL on failure.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param cb The amount of memory to allocate.
*/
/**
* Frees a block of guarded memory.
*
* @returns IPRT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pv The memory. NULL is ignored.
*/
/**
* Test vprintf making sure the output starts on a new line.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param enmLevel Message importance level.
* @param pszFormat The message.
* @param va Arguments.
*/
/**
* Test printf making sure the output starts on a new line.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param enmLevel Message importance level.
* @param pszFormat The message.
* @param ... Arguments.
*/
/**
* Test vprintf, makes sure lines are prefixed and so forth.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param enmLevel Message importance level.
* @param pszFormat The message.
* @param va Arguments.
*/
/**
* Test printf, makes sure lines are prefixed and so forth.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param enmLevel Message importance level.
* @param pszFormat The message.
* @param ... Arguments.
*/
/**
* Prints the test banner.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
*/
/**
* Summaries the test, destroys the test instance and return an exit code.
*
* @returns Test program exit code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
*/
/**
* Skips the test, destroys the test instance and return an exit code.
*
* @returns Test program exit code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszReasonFmt Text explaining why, optional (NULL).
* @param va Arguments for the reason format string.
*/
/**
* Skips the test, destroys the test instance and return an exit code.
*
* @returns Test program exit code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszReasonFmt Text explaining why, optional (NULL).
* @param ... Arguments for the reason format string.
*/
/**
* 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 hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszSubTest The sub-test name.
*/
/**
* Format string version of RTTestSub.
*
* See RTTestSub for details.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszSubTestFmt The sub-test name format string.
* @param ... Arguments.
*/
/**
* Format string version of RTTestSub.
*
* See RTTestSub for details.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszSubTestFmt The sub-test name format string.
* @param va Arguments.
*/
/**
* Completes a sub-test.
*
* @returns Number of chars printed, negative numbers are IPRT error codes.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
*/
/**
* 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 Number of chars printed, negative numbers are IPRT error codes.
* @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.
*/
/**
* 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 Number of chars printed, negative numbers are IPRT error codes.
* @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.
*/
/**
* Marks the current test as 'SKIPPED' and optionally displays a message
* explaining why.
*
* @returns Number of chars printed, negative numbers are IPRT error codes.
* @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. Can be NULL or empty.
* @param ... The arguments.
*/
/**
* Marks the current test as 'SKIPPED' and optionally displays a message
* explaining why.
*
* @returns Number of chars printed, negative numbers are IPRT error codes.
* @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. Can be NULL or empty.
* @param va The arguments.
*/
/**
* Value units.
*
* @remarks This is an interface where we have to be binary compatible with both
* older versions of this header and other components using the same
* contant values.
* @remarks When adding a new item:
* - Always add at the end of the list - do NOT group it.
* - include/VBox/VMMDevTesting.h (VMMDEV_TESTING_UNIT_XXX).
* - Add it to g_aszBs2TestUnitNames in
*
*/
typedef enum RTTESTUNIT
{
/** The customary invalid zero value. */
RTTESTUNIT_INVALID = 0,
/** The end of valid units. */
} RTTESTUNIT;
/**
* 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 hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszName The value name.
* @param u64Value The value.
* @param enmUnit The value unit.
*/
RTR3DECL(int) RTTestValue(RTTEST hTest, 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 hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param u64Value The value.
* @param enmUnit The value unit.
* @param pszNameFmt The value name format string.
* @param ... String arguments.
*/
RTR3DECL(int) RTTestValueF(RTTEST hTest, 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 hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param u64Value The value.
* @param enmUnit The value unit.
* @param pszNameFmt The value name format string.
* @param va_list String arguments.
*/
RTR3DECL(int) RTTestValueV(RTTEST hTest, uint64_t u64Value, RTTESTUNIT enmUnit, const char *pszNameFmt, va_list va);
/**
* Increments the error counter.
*
* @returns IPRT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
*/
/**
* Get the current error count.
*
* @returns The error counter, UINT32_MAX if no valid test handle.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
*/
/**
* Get the error count of the current sub test.
*
* @returns The error counter, UINT32_MAX if no valid test handle.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/** @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.
*/
do { if (!(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.
*/
do { if (!(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.
*/
do { if (!(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.
*/
if (!(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.
*/
do { if (!(expr)) { \
} \
} 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.
*/
do { if (!(expr)) { \
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.
*/
do { if (!(expr)) { \
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.
*/
do { \
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.
*/
do { \
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.
*/
do { \
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.
*/
if (1) { \
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.
*/
do { \
if (RT_FAILURE(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.
*/
do { \
if (RT_FAILURE(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.
*/
do { \
if (RT_FAILURE(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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* Format string version of RTTestSub.
*
* See RTTestSub for details.
*
* @returns Number of chars printed.
* @param pszSubTestFmt The sub-test name format string.
* @param ... Arguments.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* Increments the error counter and prints a failure message.
*
* @returns IPRT status code.
* @param pszFormat The message. No trailing newline.
* @param va The arguments.
*/
/**
* Increments the error counter and prints a failure message.
*
* @returns IPRT status code.
* @param pszFormat The message. No trailing newline.
* @param ... The arguments.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* Same as RTTestIPrintfV with RTTESTLVL_FAILURE.
*
* @returns Number of chars printed.
* @param pszFormat The message.
* @param va Arguments.
*/
/**
* Same as RTTestIPrintf with RTTESTLVL_FAILURE.
*
* @returns Number of chars printed.
* @param pszFormat The message.
* @param ... Arguments.
*/
/** @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.
*/
do { if (!(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.
*/
do { if (!(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.
*/
do { if (!(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.
*/
if (!(expr)) { \
break; \
} else 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.
*/
do { if (!(expr)) { \
} \
} while (0)
/** @def RTTESTI_CHECK_MSG_BREAK
* 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.
*/
if (!(expr)) { \
break; \
} else do {} 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.
*/
do { if (!(expr)) { \
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.
*/
do { if (!(expr)) { \
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.
*/
do { \
} \
} 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.
*/
do { \
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.
*/
do { \
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.
*/
if (1) { \
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.
*/
do { \
if (RT_FAILURE(rcCheck)) { \
} \
} while (0)
/** @def RTTESTI_CHECK_RC_OK_BREAK
* Check whether a IPRT style status code indicates success.
*
* 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.
*/
do { \
if (RT_FAILURE(rcCheck)) { \
break; \
} \
} 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.
*/
do { \
if (RT_FAILURE(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.
*/
do { \
if (RT_FAILURE(rcCheck)) { \
return; \
} \
} while (0)
/** @} */
/** @} */
#endif