test.h revision 9474d83dcac691984017f8255821b95ec7642804
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * IPRT - Testcase Framework.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Copyright (C) 2009 Sun Microsystems, Inc.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * This file is part of VirtualBox Open Source Edition (OSE), as
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * available from http://www.virtualbox.org. This file is free software;
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * you can redistribute it and/or modify it under the terms of the GNU
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * General Public License (GPL) as published by the Free Software
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Foundation, in version 2 as it comes in the "COPYING" file of the
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * The contents of this file may alternatively be used under the terms
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * of the Common Development and Distribution License Version 1.0
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * VirtualBox OSE distribution, in which case the provisions of the
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * CDDL are applicable instead of those of the GPL.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * You may elect to license modified versions of this file under the
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * terms and conditions of either the GPL or the CDDL or both.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Clara, CA 95054 USA or visit http://www.sun.com if you need
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * additional information or have any questions.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore/** @defgroup grp_rt_test RTTest - Testcase Framework.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @ingroup grp_rt
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore/** A test handle. */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore/** A pointer to a test handle. */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore/** A const pointer to a test handle. */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore/** A NIL Test handle. */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Test message importance level.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore /** Invalid 0. */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore /** Message should always be printed. */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore /** Failure message. */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore /** Sub-test banner. */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore /** Info message. */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore /** Debug message. */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore /** The last (invalid). */
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Creates a test instance.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns IPRT status code.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pszTest The test name.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param phTest Where to store the test instance handle.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestCreate(const char *pszTest, PRTTEST phTest);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Destroys a test instance previously created by RTTestCreate.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns IPRT status code.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. NIL_RTTEST is ignored.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Allocate a block of guarded memory.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns IPRT status code.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param cb The amount of memory to allocate.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param cbAlign The alignment of the returned block.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param fHead Head or tail optimized guard.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param ppvUser Where to return the pointer to the block.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestGuardedAlloc(RTTEST hTest, size_t cb, uint32_t cbAlign, bool fHead, void **ppvUser);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Allocates a block of guarded memory where the guarded is immediately after
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * the user memory.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns Pointer to the allocated memory. NULL on failure.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param cb The amount of memory to allocate.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(void *) RTTestGuardedAllocTail(RTTEST hTest, size_t cb);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Allocates a block of guarded memory where the guarded is right in front of
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * the user memory.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns Pointer to the allocated memory. NULL on failure.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param cb The amount of memory to allocate.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(void *) RTTestGuardedAllocHead(RTTEST hTest, size_t cb);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Frees a block of guarded memory.
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems * @returns IPRT status code.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pv The memory. NULL is ignored.
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun MicrosystemsRTR3DECL(int) RTTestGuardedFree(RTTEST hTest, void *pv);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Test vprintf making sure the output starts on a new line.
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems * @returns Number of chars printed.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param enmLevel Message importance level.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pszFormat The message.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param va Arguments.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestPrintfNlV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Test printf making sure the output starts on a new line.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns Number of chars printed.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param enmLevel Message importance level.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pszFormat The message.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param ... Arguments.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestPrintfNl(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Test vprintf, makes sure lines are prefixed and so forth.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns Number of chars printed.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param enmLevel Message importance level.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pszFormat The message.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param va Arguments.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestPrintfV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Test printf, makes sure lines are prefixed and so forth.
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems * @returns Number of chars printed.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param enmLevel Message importance level.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pszFormat The message.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param ... Arguments.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestPrintf(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Prints the test banner.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns Number of chars printed.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Summaries the test, destroys the test instance and return an exit code.
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems * @returns Test program exit code.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestSummaryAndDestroy(RTTEST hTest);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Starts a sub-test.
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems * This will perform an implicit RTTestSubDone() call if that has not been done
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems * since the last RTTestSub call.
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems * @returns Number of chars printed.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pszSubTest The sub-test name
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestSub(RTTEST hTest, const char *pszSubTest);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Completes a sub-test.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns Number of chars printed.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Increments the error counter.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns IPRT status code.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Increments the error counter and prints a failure message.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns IPRT status code.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pszFormat The message. No trailing newline.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param va The arguments.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestFailedV(RTTEST hTest, const char *pszFormat, va_list va);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Increments the error counter and prints a failure message.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns IPRT status code.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pszFormat The message. No trailing newline.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param ... The arguments.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestFailed(RTTEST hTest, const char *pszFormat, ...);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore/** @def RTTEST_CHECK
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Check whether a boolean expression holds true.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * If the expression is false, call RTTestFailed giving the line number and expression.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param expr The expression to evaluate.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore do { if (!(expr)) { RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); } } while (0)
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore/** @def RTTEST_CHECK_MSG
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Check whether a boolean expression holds true.
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems * If the expression is false, call RTTestFailed giving the line number and expression.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param expr The expression to evaluate.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param TestPrintfArgs Argument list for RTTestPrintf, including
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * parenthesis.
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems#define RTTEST_CHECK_MSG(hTest, expr, TestPrintfArgs) \
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore do { if (!(expr)) { \
a33ad26ef1f3b7a3fcf2fad564e6bd3798fdcbaeZhao Edgar Liu - Sun Microsystems RTTestFailed((hTest), "line %u: %s", __LINE__, #expr); \
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Prints an extended PASSED message, optional.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * This does not conclude the sub-test, it could be used to report the passing
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * of a sub-sub-to-the-power-of-N-test.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns IPRT status code.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pszFormat The message. No trailing newline.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param va The arguments.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestPassedV(RTTEST hTest, const char *pszFormat, va_list va);
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * Prints an extended PASSED message, optional.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * This does not conclude the sub-test, it could be used to report the passing
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * of a sub-sub-to-the-power-of-N-test.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @returns IPRT status code.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param hTest The test handle. If NIL_RTTEST we'll use the one
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * associated with the calling thread.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param pszFormat The message. No trailing newline.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'Amore * @param ... The arguments.
88447a05f537aabe9a1bc3d5313f22581ec992a7Garrett D'AmoreRTR3DECL(int) RTTestPassed(RTTEST hTest, const char *pszFormat, ...);