ctest.h (8995B)
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 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 * This is used to set or get the option value for WRITE_GOLDEN_DATA. 86 * Set to 1 to overwrite golden data files, such as those in testdata/ucptrie. 87 * Use with set/getTestOption(). 88 */ 89 #define WRITE_GOLDEN_DATA_OPTION 7 90 91 /** 92 * Maximum amount of memory uprv_malloc should allocate before returning NULL. 93 * 94 * @internal 95 */ 96 extern T_CTEST_EXPORT_API size_t MAX_MEMORY_ALLOCATION; 97 98 /** 99 * If memory tracing was enabled, contains the number of unfreed allocations. 100 * 101 * @internal 102 */ 103 extern T_CTEST_EXPORT_API int32_t ALLOCATION_COUNT; 104 105 /** 106 * Pass to setTestOption to decrement the test option value. 107 * 108 * @internal 109 */ 110 #define DECREMENT_OPTION_VALUE -99 111 112 /** 113 * Gets the test option set on commandline. 114 * 115 * @param testOption macro definition for the individual test option 116 * @return value of test option, zero if option is not set or off 117 * @internal Internal APIs for testing purpose only 118 */ 119 T_CTEST_API int32_t T_CTEST_EXPORT2 120 getTestOption ( int32_t testOption ); 121 122 /** 123 * Sets the test option with value given on commandline. 124 * 125 * @param testOption macro definition for the individual test option 126 * @param value to set the test option to 127 * @internal Internal APIs for testing purpose only 128 */ 129 T_CTEST_API void T_CTEST_EXPORT2 130 setTestOption ( int32_t testOption, int32_t value); 131 132 /** 133 * Show the names of all nodes. 134 * 135 * @param root Subtree of tests. 136 * @internal Internal APIs for testing purpose only 137 */ 138 T_CTEST_API void T_CTEST_EXPORT2 139 showTests ( const TestNode *root); 140 141 /** 142 * Run a subtree of tests. 143 * 144 * @param root Subtree of tests. 145 * @internal Internal APIs for testing purpose only 146 */ 147 T_CTEST_API void T_CTEST_EXPORT2 148 runTests ( const TestNode* root); 149 150 /** 151 * Add a test to the subtree. 152 * Example usage: 153 * <PRE> 154 * TestNode* root=NULL; 155 * addTest(&root, &mytest, "/a/b/mytest" ); 156 * </PRE> 157 * @param root Pointer to the root pointer. 158 * @param test Pointer to 'void function(void)' for actual test. 159 * @param path Path from root under which test will be placed. Ex. '/a/b/mytest' 160 * @internal Internal APIs for testing purpose only 161 */ 162 T_CTEST_API void T_CTEST_EXPORT2 163 addTest(TestNode** root, 164 TestFunctionPtr test, 165 const char *path); 166 167 /** 168 * Clean up any allocated memory. 169 * Conditions for calling this function are the same as u_cleanup(). 170 * @see u_cleanup 171 * @internal Internal APIs for testing purpose only 172 */ 173 T_CTEST_API void T_CTEST_EXPORT2 174 cleanUpTestTree(TestNode *tn); 175 176 /** 177 * Retrieve a specific subtest. (subtree). 178 * 179 * @param root Pointer to the root. 180 * @param path Path relative to the root, Ex. '/a/b' 181 * @return The subtest, or NULL on failure. 182 * @internal Internal APIs for testing purpose only 183 */ 184 T_CTEST_API const TestNode* T_CTEST_EXPORT2 185 getTest(const TestNode* root, 186 const char *path); 187 188 189 /** 190 * Log an error message. (printf style) 191 * @param pattern printf-style format string 192 * @internal Internal APIs for testing purpose only 193 */ 194 T_CTEST_API void T_CTEST_EXPORT2 195 log_err(const char* pattern, ...); 196 197 T_CTEST_API void T_CTEST_EXPORT2 198 log_err_status(UErrorCode status, const char* pattern, ...); 199 /** 200 * Log an informational message. (printf style) 201 * @param pattern printf-style format string 202 * @internal Internal APIs for testing purpose only 203 */ 204 T_CTEST_API void T_CTEST_EXPORT2 205 log_info(const char* pattern, ...); 206 207 /** 208 * Log an informational message. (vprintf style) 209 * @param prefix a string that is output before the pattern and without formatting 210 * @param pattern printf-style format string 211 * @param ap variable-arguments list 212 * @internal Internal APIs for testing purpose only 213 */ 214 T_CTEST_API void T_CTEST_EXPORT2 215 vlog_info(const char *prefix, const char *pattern, va_list ap); 216 217 /** 218 * Log a verbose informational message. (printf style) 219 * This message will only appear if the global VERBOSITY is nonzero 220 * @param pattern printf-style format string 221 * @internal Internal APIs for testing purpose only 222 */ 223 T_CTEST_API void T_CTEST_EXPORT2 224 log_verbose(const char* pattern, ...); 225 226 /** 227 * Log an error message concerning missing data. (printf style) 228 * If WARN_ON_MISSING_DATA is nonzero, this will case a log_info (warning) to be 229 * printed, but if it is zero this will produce an error (log_err). 230 * @param pattern printf-style format string 231 * @internal Internal APIs for testing purpose only 232 */ 233 T_CTEST_API void T_CTEST_EXPORT2 234 log_data_err(const char *pattern, ...); 235 236 /** 237 * Log a known issue. 238 * @param ticket ticket number such as "ICU-12345" for ICU tickets or "CLDR-6636" for CLDR tickets. 239 * @param fmt ... sprintf-style format, optional message. can be NULL. 240 * @return true if known issue test should be skipped, false if it should be run 241 */ 242 T_CTEST_API UBool 243 T_CTEST_EXPORT2 244 log_knownIssue(const char *ticket, const char *fmt, ...); 245 246 /** 247 * Initialize the variables above. This allows the test to set up accordingly 248 * before running the tests. 249 * This must be called before runTests. 250 */ 251 T_CTEST_API int T_CTEST_EXPORT2 252 initArgs( int argc, const char* const argv[], ArgHandlerPtr argHandler, void *context); 253 254 /** 255 * Processes the command line arguments. 256 * This is a sample implementation 257 * <PRE>Usage: %s [ -l ] [ -v ] [ -? ] [ /path/to/test ] 258 * -l List only, do not run\ 259 * -v turn OFF verbosity 260 * -? print this message</PRE> 261 * @param root Testnode root with tests already attached to it 262 * @param argv argument list from main (stdio.h) 263 * @param argc argument list count from main (stdio.h) 264 * @return positive for error count, 0 for success, negative for illegal argument 265 * @internal Internal APIs for testing purpose only 266 */ 267 T_CTEST_API int T_CTEST_EXPORT2 268 runTestRequest(const TestNode* root, 269 int argc, 270 const char* const argv[]); 271 272 273 T_CTEST_API const char* T_CTEST_EXPORT2 274 getTestName(void); 275 276 /** 277 * Append a time delta to str if it is significant (>5 ms) otherwise no change 278 * @param delta a delta in millis 279 * @param str a string to append to. 280 */ 281 T_CTEST_API void T_CTEST_EXPORT2 282 str_timeDelta(char *str, UDate delta); 283 284 285 /* ======== XML (JUnit output) ========= */ 286 287 /** 288 * Set the filename for the XML output. 289 * @param fileName file name. Caller must retain storage. 290 * @return 0 on success, 1 on failure. 291 */ 292 T_CTEST_API int32_t T_CTEST_EXPORT2 293 ctest_xml_setFileName(const char *fileName); 294 295 296 /** 297 * Init XML subsystem. Call ctest_xml_setFileName first 298 * @param rootName the test root name to be written 299 * @return 0 on success, 1 on failure. 300 */ 301 T_CTEST_API int32_t T_CTEST_EXPORT2 302 ctest_xml_init(const char *rootName); 303 304 305 /** 306 * Set the filename for the XML output. Caller must retain storage. 307 * @return 0 on success, 1 on failure. 308 */ 309 T_CTEST_API int32_t T_CTEST_EXPORT2 310 ctest_xml_fini(void); 311 312 313 /** 314 * report a test case 315 * @return 0 on success, 1 on failure. 316 */ 317 T_CTEST_API int32_t 318 T_CTEST_EXPORT2 319 ctest_xml_testcase(const char *classname, const char *name, const char *time, const char *failMsg); 320 321 #endif