• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (C) 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
315