michael@0: /*
michael@0:  ********************************************************************************
michael@0:  *
michael@0:  *   Copyright (C) 1996-2013, International Business Machines
michael@0:  *   Corporation and others.  All Rights Reserved.
michael@0:  *
michael@0:  ********************************************************************************
michael@0:  */
michael@0: 
michael@0: #ifndef CTEST_H
michael@0: #define CTEST_H
michael@0: 
michael@0: #include "unicode/testtype.h"
michael@0: #include "unicode/utrace.h"
michael@0: 
michael@0: 
michael@0: /* prototypes *********************************/
michael@0: 
michael@0: U_CDECL_BEGIN
michael@0: typedef void (U_CALLCONV *TestFunctionPtr)(void);
michael@0: typedef int (U_CALLCONV *ArgHandlerPtr)(int arg, int argc, const char* const argv[], void *context);
michael@0: typedef struct TestNode TestNode;
michael@0: U_CDECL_END
michael@0: 
michael@0: /**
michael@0:  * This is use to set or get the option value for REPEAT_TESTS.
michael@0:  * Use with set/getTestOption().
michael@0:  *
michael@0:  * @internal
michael@0:  */
michael@0: #define REPEAT_TESTS_OPTION 1
michael@0: 
michael@0: /**
michael@0:  * This is use to set or get the option value for VERBOSITY.
michael@0:  * When option is set to zero to disable log_verbose() messages.
michael@0:  * Otherwise nonzero to see log_verbose() messages.
michael@0:  * Use with set/getTestOption().
michael@0:  *
michael@0:  * @internal
michael@0:  */
michael@0: #define VERBOSITY_OPTION 2
michael@0: 
michael@0: /**
michael@0:  * This is use to set or get the option value for ERR_MSG.
michael@0:  * Use with set/getTestOption().
michael@0:  *
michael@0:  * @internal
michael@0:  */
michael@0: #define ERR_MSG_OPTION 3
michael@0: 
michael@0: /**
michael@0:  * This is use to set or get the option value for QUICK.
michael@0:  * When option is zero, disable some of the slower tests.
michael@0:  * Otherwise nonzero to run the slower tests.
michael@0:  * Use with set/getTestOption().
michael@0:  *
michael@0:  * @internal
michael@0:  */
michael@0: #define QUICK_OPTION 4
michael@0: 
michael@0: /**
michael@0:  * This is use to set or get the option value for WARN_ON_MISSING_DATA.
michael@0:  * When option is nonzero, warn on missing data.
michael@0:  * Otherwise, errors are propagated when data is not available.
michael@0:  * Affects the behavior of log_dataerr.
michael@0:  * Use with set/getTestOption().
michael@0:  *
michael@0:  * @see log_data_err
michael@0:  * @internal
michael@0:  */
michael@0: #define WARN_ON_MISSING_DATA_OPTION 5
michael@0: 
michael@0: /**
michael@0:  * This is use to set or get the option value for ICU_TRACE.
michael@0:  * ICU tracing level, is set by command line option.
michael@0:  * Use with set/getTestOption().
michael@0:  *
michael@0:  * @internal
michael@0:  */
michael@0: #define ICU_TRACE_OPTION 6
michael@0: 
michael@0: /**
michael@0:  * Maximum amount of memory uprv_malloc should allocate before returning NULL.
michael@0:  *
michael@0:  * @internal
michael@0:  */
michael@0: extern T_CTEST_EXPORT_API size_t MAX_MEMORY_ALLOCATION;
michael@0: 
michael@0: /**
michael@0:  * If memory tracing was enabled, contains the number of unfreed allocations.
michael@0:  *
michael@0:  * @internal
michael@0:  */
michael@0: extern T_CTEST_EXPORT_API int32_t ALLOCATION_COUNT;
michael@0: 
michael@0: /**
michael@0:  * Pass to setTestOption to decrement the test option value.
michael@0:  *
michael@0:  * @internal
michael@0:  */
michael@0: #define DECREMENT_OPTION_VALUE -99
michael@0: 
michael@0: /**
michael@0:  * Gets the test option set on commandline.
michael@0:  *
michael@0:  * @param testOption macro definition for the individual test option
michael@0:  * @return value of test option, zero if option is not set or off
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API int32_t T_CTEST_EXPORT2
michael@0: getTestOption ( int32_t testOption );
michael@0: 
michael@0: /**
michael@0:  * Sets the test option with value given on commandline.
michael@0:  *
michael@0:  * @param testOption macro definition for the individual test option
michael@0:  * @param value to set the test option to
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: setTestOption ( int32_t testOption, int32_t value);
michael@0: 
michael@0: /**
michael@0:  * Show the names of all nodes.
michael@0:  *
michael@0:  * @param root Subtree of tests.
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: showTests ( const TestNode *root);
michael@0: 
michael@0: /**
michael@0:  * Run a subtree of tests.
michael@0:  *
michael@0:  * @param root Subtree of tests.
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: runTests ( const TestNode* root);
michael@0: 
michael@0: /**
michael@0:  * Add a test to the subtree.
michael@0:  * Example usage:
michael@0:  * <PRE>
michael@0:  *     TestNode* root=NULL;
michael@0:  *     addTest(&root, &mytest, "/a/b/mytest" );
michael@0:  * </PRE>
michael@0:  * @param root Pointer to the root pointer.
michael@0:  * @param test Pointer to 'void function(void)' for actual test.
michael@0:  * @param path Path from root under which test will be placed. Ex. '/a/b/mytest'
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: addTest(TestNode** root,
michael@0:         TestFunctionPtr test,
michael@0:         const char *path);
michael@0: 
michael@0: /**
michael@0:  * Clean up any allocated memory.
michael@0:  * Conditions for calling this function are the same as u_cleanup().
michael@0:  * @see u_cleanup
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: cleanUpTestTree(TestNode *tn);
michael@0: 
michael@0: /**
michael@0:  * Retreive a specific subtest. (subtree).
michael@0:  *
michael@0:  * @param root Pointer to the root.
michael@0:  * @param path Path relative to the root, Ex. '/a/b'
michael@0:  * @return The subtest, or NULL on failure.
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API const TestNode* T_CTEST_EXPORT2
michael@0: getTest(const TestNode* root,
michael@0:         const char *path);
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * Log an error message. (printf style)
michael@0:  * @param pattern printf-style format string
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: log_err(const char* pattern, ...);
michael@0: 
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: log_err_status(UErrorCode status, const char* pattern, ...);
michael@0: /**
michael@0:  * Log an informational message. (printf style)
michael@0:  * @param pattern printf-style format string
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: log_info(const char* pattern, ...);
michael@0: 
michael@0: /**
michael@0:  * Log an informational message. (vprintf style)
michael@0:  * @param prefix a string that is output before the pattern and without formatting
michael@0:  * @param pattern printf-style format string
michael@0:  * @param ap variable-arguments list
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: vlog_info(const char *prefix, const char *pattern, va_list ap);
michael@0: 
michael@0: /**
michael@0:  * Log a verbose informational message. (printf style)
michael@0:  * This message will only appear if the global VERBOSITY is nonzero
michael@0:  * @param pattern printf-style format string
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: log_verbose(const char* pattern, ...);
michael@0: 
michael@0: /**
michael@0:  * Log an error message concerning missing data. (printf style)
michael@0:  * If WARN_ON_MISSING_DATA is nonzero, this will case a log_info (warning) to be
michael@0:  * printed, but if it is zero this will produce an error (log_err).
michael@0:  * @param pattern printf-style format string
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: log_data_err(const char *pattern, ...);
michael@0: 
michael@0: /**
michael@0:  * Log a known issue.
michael@0:  * @param ticket ticket number such as "12345" for ICU tickets or "cldrbug:6636" for CLDR tickets.
michael@0:  * @param fmt ...  sprintf-style format, optional message. can be NULL.
michael@0:  * @return TRUE if known issue test should be skipped, FALSE if it should be run
michael@0:  */
michael@0: T_CTEST_API UBool
michael@0: T_CTEST_EXPORT2
michael@0: log_knownIssue(const char *ticket, const char *fmt, ...);
michael@0: 
michael@0: /**
michael@0:  * Initialize the variables above. This allows the test to set up accordingly
michael@0:  * before running the tests.
michael@0:  * This must be called before runTests.
michael@0:  */
michael@0: T_CTEST_API int T_CTEST_EXPORT2 
michael@0: initArgs( int argc, const char* const argv[], ArgHandlerPtr argHandler, void *context);
michael@0: 
michael@0: /**
michael@0:  * Processes the command line arguments.
michael@0:  * This is a sample implementation
michael@0:  * <PRE>Usage: %s [ -l ] [ -v ] [ -? ] [ /path/to/test ]
michael@0:  *        -l List only, do not run\
michael@0:  *        -v turn OFF verbosity
michael@0:  *        -? print this message</PRE>
michael@0:  * @param root Testnode root with tests already attached to it
michael@0:  * @param argv argument list from main (stdio.h)
michael@0:  * @param argc argument list count from main (stdio.h)
michael@0:  * @return positive for error count, 0 for success, negative for illegal argument
michael@0:  * @internal Internal APIs for testing purpose only
michael@0:  */
michael@0: T_CTEST_API int T_CTEST_EXPORT2 
michael@0: runTestRequest(const TestNode* root,
michael@0:             int argc,
michael@0:             const char* const argv[]);
michael@0: 
michael@0: 
michael@0: T_CTEST_API const char* T_CTEST_EXPORT2
michael@0: getTestName(void);
michael@0: 
michael@0: /**
michael@0:  * Append a time delta to str if it is significant (>5 ms) otherwise no change
michael@0:  * @param delta a delta in millis
michael@0:  * @param str a string to append to.
michael@0:  */
michael@0: T_CTEST_API void T_CTEST_EXPORT2
michael@0: str_timeDelta(char *str, UDate delta);
michael@0: 
michael@0: 
michael@0: /* ======== XML (JUnit output) ========= */
michael@0: 
michael@0: /**
michael@0:  * Set the filename for the XML output. 
michael@0:  * @param fileName file name. Caller must retain storage.
michael@0:  * @return 0 on success, 1 on failure.
michael@0:  */
michael@0: T_CTEST_API int32_t T_CTEST_EXPORT2
michael@0: ctest_xml_setFileName(const char *fileName);
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * Init XML subsystem. Call ctest_xml_setFileName first
michael@0:  * @param rootName the test root name to be written
michael@0:  * @return 0 on success, 1 on failure.
michael@0:  */
michael@0: T_CTEST_API int32_t T_CTEST_EXPORT2
michael@0: ctest_xml_init(const char *rootName);
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * Set the filename for the XML output. Caller must retain storage.
michael@0:  * @return 0 on success, 1 on failure.
michael@0:  */
michael@0: T_CTEST_API int32_t T_CTEST_EXPORT2
michael@0: ctest_xml_fini(void);
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * report a test case
michael@0:  * @return 0 on success, 1 on failure.
michael@0:  */
michael@0: T_CTEST_API int32_t
michael@0: T_CTEST_EXPORT2
michael@0: ctest_xml_testcase(const char *classname, const char *name, const char *time, const char *failMsg);
michael@0: 
michael@0: #endif