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