1/*
2 ********************************************************************************
3 *
4 *   Copyright (C) 1996-2010, 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
19U_CDECL_BEGIN
20typedef void (U_CALLCONV *TestFunctionPtr)(void);
21typedef int (U_CALLCONV *ArgHandlerPtr)(int arg, int argc, const char* const argv[], void *context);
22typedef struct TestNode TestNode;
23U_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 */
87extern 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 */
94extern 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 */
110T_CTEST_API int32_t T_CTEST_EXPORT2
111getTestOption ( 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 */
120T_CTEST_API void T_CTEST_EXPORT2
121setTestOption ( 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 */
129T_CTEST_API void T_CTEST_EXPORT2
130showTests ( 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 */
138T_CTEST_API void T_CTEST_EXPORT2
139runTests ( 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 */
153T_CTEST_API void T_CTEST_EXPORT2
154addTest(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 */
164T_CTEST_API void T_CTEST_EXPORT2
165cleanUpTestTree(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 */
175T_CTEST_API const TestNode* T_CTEST_EXPORT2
176getTest(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 */
185T_CTEST_API void T_CTEST_EXPORT2
186log_err(const char* pattern, ...);
187
188T_CTEST_API void T_CTEST_EXPORT2
189log_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 */
195T_CTEST_API void T_CTEST_EXPORT2
196log_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 */
205T_CTEST_API void T_CTEST_EXPORT2
206vlog_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 */
214T_CTEST_API void T_CTEST_EXPORT2
215log_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 */
224T_CTEST_API void T_CTEST_EXPORT2
225log_data_err(const char *pattern, ...);
226
227/**
228 * Initialize the variables above. This allows the test to set up accordingly
229 * before running the tests.
230 * This must be called before runTests.
231 */
232T_CTEST_API int T_CTEST_EXPORT2
233initArgs( int argc, const char* const argv[], ArgHandlerPtr argHandler, void *context);
234
235/**
236 * Processes the command line arguments.
237 * This is a sample implementation
238 * <PRE>Usage: %s [ -l ] [ -v ] [ -? ] [ /path/to/test ]
239 *        -l List only, do not run\
240 *        -v turn OFF verbosity
241 *        -? print this message</PRE>
242 * @param root Testnode root with tests already attached to it
243 * @param argv argument list from main (stdio.h)
244 * @param argc argument list count from main (stdio.h)
245 * @return positive for error count, 0 for success, negative for illegal argument
246 * @internal Internal APIs for testing purpose only
247 */
248T_CTEST_API int T_CTEST_EXPORT2
249runTestRequest(const TestNode* root,
250            int argc,
251            const char* const argv[]);
252
253
254T_CTEST_API const char* T_CTEST_EXPORT2
255getTestName(void);
256
257/**
258 * Append a time delta to str if it is significant (>5 ms) otherwise no change
259 * @param delta a delta in millis
260 * @param str a string to append to.
261 */
262T_CTEST_API void T_CTEST_EXPORT2
263str_timeDelta(char *str, UDate delta);
264
265
266/* ======== XML (JUnit output) ========= */
267
268/**
269 * Set the filename for the XML output.
270 * @param fileName file name. Caller must retain storage.
271 * @return 0 on success, 1 on failure.
272 */
273T_CTEST_API int32_t T_CTEST_EXPORT2
274ctest_xml_setFileName(const char *fileName);
275
276
277/**
278 * Init XML subsystem. Call ctest_xml_setFileName first
279 * @param rootName the test root name to be written
280 * @return 0 on success, 1 on failure.
281 */
282T_CTEST_API int32_t T_CTEST_EXPORT2
283ctest_xml_init(const char *rootName);
284
285
286/**
287 * Set the filename for the XML output. Caller must retain storage.
288 * @return 0 on success, 1 on failure.
289 */
290T_CTEST_API int32_t T_CTEST_EXPORT2
291ctest_xml_fini(void);
292
293
294/**
295 * report a test case
296 * @return 0 on success, 1 on failure.
297 */
298T_CTEST_API int32_t
299T_CTEST_EXPORT2
300ctest_xml_testcase(const char *classname, const char *name, const char *time, const char *failMsg);
301
302#endif
303