1// © 2016 and later: Unicode, Inc. and others. 2// License & terms of use: http://www.unicode.org/copyright.html 3/* 4 ******************************************************************************** 5 * 6 * Copyright (C) 1996-2013, International Business Machines 7 * Corporation and others. All Rights Reserved. 8 * 9 ******************************************************************************** 10 */ 11 12#ifndef CTEST_H 13#define CTEST_H 14 15#include "unicode/testtype.h" 16#include "unicode/utrace.h" 17 18 19/* prototypes *********************************/ 20 21U_CDECL_BEGIN 22typedef void (U_CALLCONV *TestFunctionPtr)(void); 23typedef int (U_CALLCONV *ArgHandlerPtr)(int arg, int argc, const char* const argv[], void *context); 24typedef struct TestNode TestNode; 25U_CDECL_END 26 27/** 28 * This is use to set or get the option value for REPEAT_TESTS. 29 * Use with set/getTestOption(). 30 * 31 * @internal 32 */ 33#define REPEAT_TESTS_OPTION 1 34 35/** 36 * This is use to set or get the option value for VERBOSITY. 37 * When option is set to zero to disable log_verbose() messages. 38 * Otherwise nonzero to see log_verbose() messages. 39 * Use with set/getTestOption(). 40 * 41 * @internal 42 */ 43#define VERBOSITY_OPTION 2 44 45/** 46 * This is use to set or get the option value for ERR_MSG. 47 * Use with set/getTestOption(). 48 * 49 * @internal 50 */ 51#define ERR_MSG_OPTION 3 52 53/** 54 * This is use to set or get the option value for QUICK. 55 * When option is zero, disable some of the slower tests. 56 * Otherwise nonzero to run the slower tests. 57 * Use with set/getTestOption(). 58 * 59 * @internal 60 */ 61#define QUICK_OPTION 4 62 63/** 64 * This is use to set or get the option value for WARN_ON_MISSING_DATA. 65 * When option is nonzero, warn on missing data. 66 * Otherwise, errors are propagated when data is not available. 67 * Affects the behavior of log_dataerr. 68 * Use with set/getTestOption(). 69 * 70 * @see log_data_err 71 * @internal 72 */ 73#define WARN_ON_MISSING_DATA_OPTION 5 74 75/** 76 * This is use to set or get the option value for ICU_TRACE. 77 * ICU tracing level, is set by command line option. 78 * Use with set/getTestOption(). 79 * 80 * @internal 81 */ 82#define ICU_TRACE_OPTION 6 83 84/** 85 * Maximum amount of memory uprv_malloc should allocate before returning NULL. 86 * 87 * @internal 88 */ 89extern T_CTEST_EXPORT_API size_t MAX_MEMORY_ALLOCATION; 90 91/** 92 * If memory tracing was enabled, contains the number of unfreed allocations. 93 * 94 * @internal 95 */ 96extern T_CTEST_EXPORT_API int32_t ALLOCATION_COUNT; 97 98/** 99 * Pass to setTestOption to decrement the test option value. 100 * 101 * @internal 102 */ 103#define DECREMENT_OPTION_VALUE -99 104 105/** 106 * Gets the test option set on commandline. 107 * 108 * @param testOption macro definition for the individual test option 109 * @return value of test option, zero if option is not set or off 110 * @internal Internal APIs for testing purpose only 111 */ 112T_CTEST_API int32_t T_CTEST_EXPORT2 113getTestOption ( int32_t testOption ); 114 115/** 116 * Sets the test option with value given on commandline. 117 * 118 * @param testOption macro definition for the individual test option 119 * @param value to set the test option to 120 * @internal Internal APIs for testing purpose only 121 */ 122T_CTEST_API void T_CTEST_EXPORT2 123setTestOption ( int32_t testOption, int32_t value); 124 125/** 126 * Show the names of all nodes. 127 * 128 * @param root Subtree of tests. 129 * @internal Internal APIs for testing purpose only 130 */ 131T_CTEST_API void T_CTEST_EXPORT2 132showTests ( const TestNode *root); 133 134/** 135 * Run a subtree of tests. 136 * 137 * @param root Subtree of tests. 138 * @internal Internal APIs for testing purpose only 139 */ 140T_CTEST_API void T_CTEST_EXPORT2 141runTests ( const TestNode* root); 142 143/** 144 * Add a test to the subtree. 145 * Example usage: 146 * <PRE> 147 * TestNode* root=NULL; 148 * addTest(&root, &mytest, "/a/b/mytest" ); 149 * </PRE> 150 * @param root Pointer to the root pointer. 151 * @param test Pointer to 'void function(void)' for actual test. 152 * @param path Path from root under which test will be placed. Ex. '/a/b/mytest' 153 * @internal Internal APIs for testing purpose only 154 */ 155T_CTEST_API void T_CTEST_EXPORT2 156addTest(TestNode** root, 157 TestFunctionPtr test, 158 const char *path); 159 160/** 161 * Clean up any allocated memory. 162 * Conditions for calling this function are the same as u_cleanup(). 163 * @see u_cleanup 164 * @internal Internal APIs for testing purpose only 165 */ 166T_CTEST_API void T_CTEST_EXPORT2 167cleanUpTestTree(TestNode *tn); 168 169/** 170 * Retreive a specific subtest. (subtree). 171 * 172 * @param root Pointer to the root. 173 * @param path Path relative to the root, Ex. '/a/b' 174 * @return The subtest, or NULL on failure. 175 * @internal Internal APIs for testing purpose only 176 */ 177T_CTEST_API const TestNode* T_CTEST_EXPORT2 178getTest(const TestNode* root, 179 const char *path); 180 181 182/** 183 * Log an error message. (printf style) 184 * @param pattern printf-style format string 185 * @internal Internal APIs for testing purpose only 186 */ 187T_CTEST_API void T_CTEST_EXPORT2 188log_err(const char* pattern, ...); 189 190T_CTEST_API void T_CTEST_EXPORT2 191log_err_status(UErrorCode status, const char* pattern, ...); 192/** 193 * Log an informational message. (printf style) 194 * @param pattern printf-style format string 195 * @internal Internal APIs for testing purpose only 196 */ 197T_CTEST_API void T_CTEST_EXPORT2 198log_info(const char* pattern, ...); 199 200/** 201 * Log an informational message. (vprintf style) 202 * @param prefix a string that is output before the pattern and without formatting 203 * @param pattern printf-style format string 204 * @param ap variable-arguments list 205 * @internal Internal APIs for testing purpose only 206 */ 207T_CTEST_API void T_CTEST_EXPORT2 208vlog_info(const char *prefix, const char *pattern, va_list ap); 209 210/** 211 * Log a verbose informational message. (printf style) 212 * This message will only appear if the global VERBOSITY is nonzero 213 * @param pattern printf-style format string 214 * @internal Internal APIs for testing purpose only 215 */ 216T_CTEST_API void T_CTEST_EXPORT2 217log_verbose(const char* pattern, ...); 218 219/** 220 * Log an error message concerning missing data. (printf style) 221 * If WARN_ON_MISSING_DATA is nonzero, this will case a log_info (warning) to be 222 * printed, but if it is zero this will produce an error (log_err). 223 * @param pattern printf-style format string 224 * @internal Internal APIs for testing purpose only 225 */ 226T_CTEST_API void T_CTEST_EXPORT2 227log_data_err(const char *pattern, ...); 228 229/** 230 * Log a known issue. 231 * @param ticket ticket number such as "12345" for ICU tickets or "cldrbug:6636" for CLDR tickets. 232 * @param fmt ... sprintf-style format, optional message. can be NULL. 233 * @return TRUE if known issue test should be skipped, FALSE if it should be run 234 */ 235T_CTEST_API UBool 236T_CTEST_EXPORT2 237log_knownIssue(const char *ticket, const char *fmt, ...); 238 239/** 240 * Initialize the variables above. This allows the test to set up accordingly 241 * before running the tests. 242 * This must be called before runTests. 243 */ 244T_CTEST_API int T_CTEST_EXPORT2 245initArgs( int argc, const char* const argv[], ArgHandlerPtr argHandler, void *context); 246 247/** 248 * Processes the command line arguments. 249 * This is a sample implementation 250 * <PRE>Usage: %s [ -l ] [ -v ] [ -? ] [ /path/to/test ] 251 * -l List only, do not run\ 252 * -v turn OFF verbosity 253 * -? print this message</PRE> 254 * @param root Testnode root with tests already attached to it 255 * @param argv argument list from main (stdio.h) 256 * @param argc argument list count from main (stdio.h) 257 * @return positive for error count, 0 for success, negative for illegal argument 258 * @internal Internal APIs for testing purpose only 259 */ 260T_CTEST_API int T_CTEST_EXPORT2 261runTestRequest(const TestNode* root, 262 int argc, 263 const char* const argv[]); 264 265 266T_CTEST_API const char* T_CTEST_EXPORT2 267getTestName(void); 268 269/** 270 * Append a time delta to str if it is significant (>5 ms) otherwise no change 271 * @param delta a delta in millis 272 * @param str a string to append to. 273 */ 274T_CTEST_API void T_CTEST_EXPORT2 275str_timeDelta(char *str, UDate delta); 276 277 278/* ======== XML (JUnit output) ========= */ 279 280/** 281 * Set the filename for the XML output. 282 * @param fileName file name. Caller must retain storage. 283 * @return 0 on success, 1 on failure. 284 */ 285T_CTEST_API int32_t T_CTEST_EXPORT2 286ctest_xml_setFileName(const char *fileName); 287 288 289/** 290 * Init XML subsystem. Call ctest_xml_setFileName first 291 * @param rootName the test root name to be written 292 * @return 0 on success, 1 on failure. 293 */ 294T_CTEST_API int32_t T_CTEST_EXPORT2 295ctest_xml_init(const char *rootName); 296 297 298/** 299 * Set the filename for the XML output. Caller must retain storage. 300 * @return 0 on success, 1 on failure. 301 */ 302T_CTEST_API int32_t T_CTEST_EXPORT2 303ctest_xml_fini(void); 304 305 306/** 307 * report a test case 308 * @return 0 on success, 1 on failure. 309 */ 310T_CTEST_API int32_t 311T_CTEST_EXPORT2 312ctest_xml_testcase(const char *classname, const char *name, const char *time, const char *failMsg); 313 314#endif 315