icuSources/tools/ctestfw/unicode/ctest.h

   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  * 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