1 // Copyright (C) 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 21 U_CDECL_BEGIN 22 typedef void (U_CALLCONV *TestFunctionPtr)(void); 23 typedef int (U_CALLCONV *ArgHandlerPtr)(int arg, int argc, const char* const argv[], void *context); 24 typedef struct TestNode TestNode; 25 U_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 */ 89 extern 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 */ 96 extern 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 */ 112 T_CTEST_API int32_t T_CTEST_EXPORT2 113 getTestOption ( 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 */ 122 T_CTEST_API void T_CTEST_EXPORT2 123 setTestOption ( 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 */ 131 T_CTEST_API void T_CTEST_EXPORT2 132 showTests ( 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 */ 140 T_CTEST_API void T_CTEST_EXPORT2 141 runTests ( 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 */ 155 T_CTEST_API void T_CTEST_EXPORT2 156 addTest(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 */ 166 T_CTEST_API void T_CTEST_EXPORT2 167 cleanUpTestTree(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 */ 177 T_CTEST_API const TestNode* T_CTEST_EXPORT2 178 getTest(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 */ 187 T_CTEST_API void T_CTEST_EXPORT2 188 log_err(const char* pattern, ...); 189 190 T_CTEST_API void T_CTEST_EXPORT2 191 log_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 */ 197 T_CTEST_API void T_CTEST_EXPORT2 198 log_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 */ 207 T_CTEST_API void T_CTEST_EXPORT2 208 vlog_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 */ 216 T_CTEST_API void T_CTEST_EXPORT2 217 log_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 */ 226 T_CTEST_API void T_CTEST_EXPORT2 227 log_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 */ 235 T_CTEST_API UBool 236 T_CTEST_EXPORT2 237 log_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 */ 244 T_CTEST_API int T_CTEST_EXPORT2 245 initArgs( 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 */ 260 T_CTEST_API int T_CTEST_EXPORT2 261 runTestRequest(const TestNode* root, 262 int argc, 263 const char* const argv[]); 264 265 266 T_CTEST_API const char* T_CTEST_EXPORT2 267 getTestName(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 */ 274 T_CTEST_API void T_CTEST_EXPORT2 275 str_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 */ 285 T_CTEST_API int32_t T_CTEST_EXPORT2 286 ctest_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 */ 294 T_CTEST_API int32_t T_CTEST_EXPORT2 295 ctest_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 */ 302 T_CTEST_API int32_t T_CTEST_EXPORT2 303 ctest_xml_fini(void); 304 305 306 /** 307 * report a test case 308 * @return 0 on success, 1 on failure. 309 */ 310 T_CTEST_API int32_t 311 T_CTEST_EXPORT2 312 ctest_xml_testcase(const char *classname, const char *name, const char *time, const char *failMsg); 313 314 #endif 315