icuSources/tools/ctestfw/unicode/ctest.h

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