← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to unittest/mytap/tap.h

  • Committer: brian
  • Date: 2008-06-25 05:29:13 UTC
  • Revision ID: brian@localhost.localdomain-20080625052913-6upwo0jsrl4lnapl
clean slate

Show diffs side-by-side

added added

removed removed

Lines of Context:
unittest/mytap/tap.h
 
1
/* Copyright (C) 2006 MySQL AB
 
2
 
 
3
   This program is free software; you can redistribute it and/or modify
 
4
   it under the terms of the GNU General Public License as published by
 
5
   the Free Software Foundation; version 2 of the License.
 
6
 
 
7
   This program is distributed in the hope that it will be useful,
 
8
   but WITHOUT ANY WARRANTY; without even the implied warranty of
 
9
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
10
   GNU General Public License for more details.
 
11
 
 
12
   You should have received a copy of the GNU General Public License
 
13
   along with this program; if not, write to the Free Software
 
14
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
15
 
 
16
   Library for providing TAP support for testing C and C++ was written
 
17
   by Mats Kindahl <mats@mysql.com>.
 
18
*/
 
19
 
 
20
#ifndef TAP_H
 
21
#define TAP_H
 
22
 
 
23
#include "my_global.h"
 
24
 
 
25
/*
 
26
  @defgroup MyTAP MySQL support for performing unit tests according to
 
27
  the Test Anything Protocol (TAP).
 
28
*/
 
29
 
 
30
#define NO_PLAN  (0)
 
31
 
 
32
/**
 
33
   Data about test plan.
 
34
 
 
35
   @ingroup MyTAP_Internal
 
36
 
 
37
   @internal We are using the "typedef struct X { ... } X" idiom to
 
38
   create class/struct X both in C and C++.
 
39
 */
 
40
 
 
41
typedef struct TEST_DATA {
 
42
  /**
 
43
     Number of tests that is planned to execute.
 
44
 
 
45
     Can be zero (<code>NO_PLAN</code>) meaning that the plan string
 
46
     will be printed at the end of test instead.
 
47
  */
 
48
  int plan;
 
49
 
 
50
  /** Number of last test that was done or skipped. */
 
51
  int last;
 
52
 
 
53
  /** Number of tests that failed. */
 
54
  int failed;
 
55
 
 
56
  /** Todo reason. */
 
57
  char todo[128];
 
58
} TEST_DATA;
 
59
 
 
60
#ifdef __cplusplus
 
61
extern "C" {
 
62
#endif
 
63
 
 
64
/**
 
65
  @defgroup MyTAP_API MyTAP API
 
66
 
 
67
  MySQL support for performing unit tests according to TAP.
 
68
 
 
69
  @{
 
70
*/
 
71
 
 
72
/**
 
73
   Set number of tests that is planned to execute.
 
74
 
 
75
   The function also accepts the predefined constant
 
76
   <code>NO_PLAN</code>.  If the function is not called, it is as if
 
77
   it was called with <code>NO_PLAN</code>, i.e., the test plan will
 
78
   be printed after all the test lines.
 
79
 
 
80
   The plan() function will install signal handlers for all signals
 
81
   that generate a core, so if you want to override these signals, do
 
82
   it <em>after</em> you have called the plan() function.
 
83
 
 
84
   @param count The planned number of tests to run. 
 
85
*/
 
86
 
 
87
void plan(int const count);
 
88
 
 
89
 
 
90
/**
 
91
   Report test result as a TAP line.
 
92
 
 
93
   Function used to write status of an individual test.  Call this
 
94
   function in the following manner:
 
95
 
 
96
   @code
 
97
   ok(ducks == paddling,
 
98
      "%d ducks did not paddle", ducks - paddling);
 
99
   @endcode
 
100
 
 
101
   @param pass Zero if the test failed, non-zero if it passed.
 
102
   @param fmt  Format string in printf() format. NULL is allowed, in
 
103
               which case nothing is printed.
 
104
*/
 
105
 
 
106
void ok(int const pass, char const *fmt, ...)
 
107
  __attribute__((format(printf,2,3)));
 
108
 
 
109
 
 
110
/**
 
111
   Skip a determined number of tests.
 
112
 
 
113
   Function to print that <em>how_many</em> tests have been skipped.
 
114
   The reason is printed for each skipped test.  Observe that this
 
115
   function does not do the actual skipping for you, it just prints
 
116
   information that tests have been skipped. This function is not
 
117
   usually used, but rather the macro @c SKIP_BLOCK_IF, which does the
 
118
   skipping for you.
 
119
 
 
120
   It shall be used in the following manner:
 
121
 
 
122
   @code
 
123
   if (ducks == 0) {
 
124
     skip(2, "No ducks in the pond");
 
125
   } else {
 
126
      int i;
 
127
      for (i = 0 ; i < 2 ; ++i)
 
128
        ok(duck[i] == paddling, "is duck %d paddling?", i);
 
129
   }
 
130
   @endcode
 
131
 
 
132
   @see SKIP_BLOCK_IF
 
133
 
 
134
   @param how_many   Number of tests that are to be skipped.
 
135
   @param reason     A reason for skipping the tests
 
136
 */
 
137
 
 
138
void skip(int how_many, char const *const reason, ...)
 
139
    __attribute__((format(printf,2,3)));
 
140
 
 
141
 
 
142
/**
 
143
   Helper macro to skip a block of code.  The macro can be used to
 
144
   simplify conditionally skipping a block of code.  It is used in the
 
145
   following manner:
 
146
 
 
147
   @code
 
148
   SKIP_BLOCK_IF(ducks == 0, 2, "No ducks in the pond")
 
149
   {
 
150
     int i;
 
151
     for (i = 0 ; i < 2 ; ++i)
 
152
       ok(duck[i] == paddling, "is duck %d paddling?", i);
 
153
   }
 
154
   @endcode
 
155
 
 
156
   @see skip
 
157
 */
 
158
 
 
159
#define SKIP_BLOCK_IF(SKIP_IF_TRUE, COUNT, REASON) \
 
160
  if (SKIP_IF_TRUE) skip((COUNT),(REASON)); else
 
161
 
 
162
 
 
163
/**
 
164
   Print a diagnostics message.
 
165
 
 
166
   @param fmt  Diagnostics message in printf() format.
 
167
 */
 
168
 
 
169
void diag(char const *fmt, ...)
 
170
  __attribute__((format(printf,1,2)));
 
171
 
 
172
 
 
173
/**
 
174
   Print a bail out message.
 
175
 
 
176
   A bail out message can be issued when no further testing can be
 
177
   done, e.g., when there are missing dependencies.
 
178
 
 
179
   The test will exit with status 255.  This function does not return.
 
180
 
 
181
   @code
 
182
   BAIL_OUT("Lost connection to server %s", server_name);
 
183
   @endcode
 
184
 
 
185
   @note A bail out message is printed if a signal that generates a
 
186
   core is raised.
 
187
 
 
188
   @param fmt Bail out message in printf() format.
 
189
*/
 
190
 
 
191
void BAIL_OUT(char const *fmt, ...)
 
192
  __attribute__((noreturn, format(printf,1,2)));
 
193
 
 
194
 
 
195
/**
 
196
   Print summary report and return exit status.
 
197
 
 
198
   This function will print a summary report of how many tests passed,
 
199
   how many were skipped, and how many remains to do.  The function
 
200
   should be called after all tests are executed in the following
 
201
   manner:
 
202
 
 
203
   @code
 
204
   return exit_status();
 
205
   @endcode
 
206
 
 
207
   @returns @c EXIT_SUCCESS if all tests passed, @c EXIT_FAILURE if
 
208
   one or more tests failed.
 
209
 */
 
210
 
 
211
int exit_status(void);
 
212
 
 
213
 
 
214
/**
 
215
   Skip entire test suite.
 
216
 
 
217
   To skip the entire test suite, use this function. It will
 
218
   automatically call exit(), so there is no need to have checks
 
219
   around it.
 
220
 */
 
221
 
 
222
void skip_all(char const *reason, ...)
 
223
  __attribute__((noreturn, format(printf, 1, 2)));
 
224
 
 
225
 
 
226
/**
 
227
   Start section of tests that are not yet ready.
 
228
 
 
229
   To start a section of tests that are not ready and are expected to
 
230
   fail, use this function and todo_end() in the following manner:
 
231
 
 
232
   @code
 
233
   todo_start("Not ready yet");
 
234
   ok(is_rocketeering(duck), "Rocket-propelled ducks");
 
235
   ok(is_kamikaze(duck), "Kamikaze ducks");
 
236
   todo_end();
 
237
   @endcode
 
238
 
 
239
   @see todo_end
 
240
 
 
241
   @note
 
242
   It is not possible to nest todo sections.
 
243
 
 
244
   @param message Message that will be printed before the todo tests.
 
245
*/
 
246
 
 
247
void todo_start(char const *message, ...)
 
248
  __attribute__((format(printf, 1, 2)));
 
249
 
 
250
 
 
251
/**
 
252
   End a section of tests that are not yet ready.
 
253
*/
 
254
 
 
255
void todo_end();
 
256
 
 
257
/** @} */
 
258
 
 
259
#ifdef __cplusplus
 
260
}
 
261
#endif
 
262
 
 
263
#endif /* TAP_H */