|
1 /************************************************************************ |
|
2 * |
|
3 * driver.h - testsuite driver declarations |
|
4 * |
|
5 * $Id: driver.h 287304 2005-09-15 00:41:16Z sebor $ |
|
6 * |
|
7 *************************************************************************** |
|
8 * |
|
9 * Copyright (c) 1994-2005 Quovadx, Inc., acting through its Rogue Wave |
|
10 * Software division. Licensed under the Apache License, Version 2.0 (the |
|
11 * "License"); you may not use this file except in compliance with the |
|
12 * License. You may obtain a copy of the License at |
|
13 * http://www.apache.org/licenses/LICENSE-2.0. Unless required by |
|
14 * applicable law or agreed to in writing, software distributed under |
|
15 * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR |
|
16 * CONDITIONS OF ANY KIND, either express or implied. See the License |
|
17 * for the specific language governing permissions and limitations under |
|
18 * the License. |
|
19 * |
|
20 **************************************************************************/ |
|
21 |
|
22 #ifndef RW_DRIVER_H_INCLUDED |
|
23 #define RW_DRIVER_H_INCLUDED |
|
24 |
|
25 #include <testdefs.h> // for test config macros |
|
26 extern int failures; |
|
27 |
|
28 /** |
|
29 * Initializes the test driver, passes program arguments to it, processes |
|
30 * command line arguments, any arguments specified in the environment |
|
31 * variable RWSTD_TESTOPTS, and if successful, invokes the program-supplied |
|
32 * callback function. |
|
33 * |
|
34 * @param argc The number of non-null elements in the argv array. |
|
35 * @param argv A null-terminated array of command line arguments. |
|
36 * If (argc == 0) the argument may be null. |
|
37 * @param filename The name of the source file name, typically |
|
38 * the __FILE__ macro. The argument may be null. |
|
39 * @param clause The clause exercised by the program, such as |
|
40 * lib.basic.string. The argument may be null. |
|
41 * @param comment An optional comment describing in more detail |
|
42 * the functionality of the program. The argument may be null. |
|
43 * @param testfun A pointer to a callback function to call by the |
|
44 * driver after successful initialization. The argument must |
|
45 * not be null. |
|
46 * @param optspec An optional character string describing command |
|
47 * line options accepted by the program. The argument may |
|
48 * be null. |
|
49 * @param ... Optional list of handlers of command line options |
|
50 * corresponding to the optspec. |
|
51 * |
|
52 * @return If initialization is successful, returns the value returned |
|
53 * by the callback function. Otherwise, returns the non-zero |
|
54 * value returned by the last initialization function or |
|
55 * command line option handler. |
|
56 * |
|
57 * After the driver has been initialzied the user-supplied callback function |
|
58 * may call any of the driver diagnostic functions to record and perhaps also |
|
59 * issue diagnostic messages of varying severity. |
|
60 * |
|
61 * There are 10 levels of severity with 0 being the lowest and 9 the highest. |
|
62 * Diagnostics of all levels of severity come in two states: active and |
|
63 * inactive. All diagnostics are recorded but normally only active diagnostics |
|
64 * of severity 4 or above are issued. It is possible to cause diagnostics of |
|
65 * lower severity levels to be issued via a command line option to the driver. |
|
66 * Choosing to issue severity 0 diagnostics has the effect of issuing inactive |
|
67 * diagnostics. |
|
68 * |
|
69 * After the callback function returns the driver displays a summary detailing |
|
70 * the number of recorded diagnostics in each of the two states (active and |
|
71 * inactive). |
|
72 * |
|
73 */ |
|
74 _TEST_EXPORT int |
|
75 rw_test (int argc, |
|
76 char* argv[], |
|
77 const char* filename, |
|
78 const char* clause, |
|
79 const char* comment, |
|
80 int (*testfun)(int, char**), |
|
81 const char* optspec, |
|
82 ...); |
|
83 |
|
84 /** |
|
85 * Records and optionally issues a diagnostic of the highest severity 9. |
|
86 * |
|
87 * @param expr A zero value denoting an active diagnostic or any non-zero |
|
88 * vaue denoting an inactive diagnostic. |
|
89 * @param filename An optional name of the file invoking the function. |
|
90 * The argument may be null. |
|
91 * @param line When positive, denotes the line number of the location |
|
92 * relevant to the diagnostic. Negative values are ignored. |
|
93 * @param fmtspec A printf format specifier (with extensions) used |
|
94 * to format the text of the diagnostic. |
|
95 * @param ... Optional list of values to format. |
|
96 * |
|
97 * @return Returns the value of expr passed to it. |
|
98 * |
|
99 * Every diagnostic is recorded but only active diagnostics may be issued, |
|
100 * depending on the setting of the diagnosable severity. The value of the |
|
101 * first argument determines whether a diagnostc is active or inactive. |
|
102 * Unlike the remaining diagnostic functions, rw_fatal doesn't return to |
|
103 * the caller when expr is 0 (i.e., when the diagnostic is active). |
|
104 * Instead, it causes the driver the exit the process with the staus equal |
|
105 * to 9, the severity of the diagnostic. |
|
106 */ |
|
107 _TEST_EXPORT int |
|
108 rw_fatal (int expr, |
|
109 const char* filename, |
|
110 int line, |
|
111 const char* fmtspec, |
|
112 ...); |
|
113 |
|
114 /** |
|
115 * Records and optionally issues a diagnostic of severity 8. |
|
116 * |
|
117 * @see #rw_fatal |
|
118 */ |
|
119 _TEST_EXPORT int |
|
120 rw_error (int, const char*, int, const char*, ...); |
|
121 |
|
122 /** |
|
123 * Records and optionally issues a diagnostic of severity 7. |
|
124 * |
|
125 * @see #rw_fatal |
|
126 */ |
|
127 _TEST_EXPORT int |
|
128 rw_assert (int, const char*, int, const char*, ...); |
|
129 |
|
130 /** |
|
131 * Records and optionally issues a diagnostic of severity 5. |
|
132 * |
|
133 * @see #rw_fatal |
|
134 */ |
|
135 _TEST_EXPORT int |
|
136 rw_warn (int, const char*, int, const char*, ...); |
|
137 |
|
138 /** |
|
139 * Records and optionally issues a diagnostic of severity 2. |
|
140 * |
|
141 * @see #rw_fatal |
|
142 */ |
|
143 _TEST_EXPORT int |
|
144 rw_note (int, const char*, int, const char*, ...); |
|
145 |
|
146 /** |
|
147 * Records and optionally issues a diagnostic of severity 1. |
|
148 * |
|
149 * @see #rw_fatal |
|
150 */ |
|
151 _TEST_EXPORT int |
|
152 rw_info (int, const char*, int, const char*, ...); |
|
153 |
|
154 #endif // RW_DRIVER_H_INCLUDED |