Asterisk - The Open Source Telephony Project  18.5.0
test.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2009-2013, Digium, Inc.
5  *
6  * David Vossel <[email protected]>
7  * Russell Bryant <[email protected]>
8  *
9  * See http://www.asterisk.org for more information about
10  * the Asterisk project. Please do not directly contact
11  * any of the maintainers of this project for assistance;
12  * the project provides a web site, mailing lists and IRC
13  * channels for your use.
14  *
15  * This program is free software, distributed under the terms of
16  * the GNU General Public License Version 2. See the LICENSE file
17  * at the top of the source tree.
18  */
19 
20 /*!
21  * \file
22  * \brief Test Framework API
23  *
24  * For an overview on how to use the test API, see \ref AstUnitTestAPI
25  *
26  * \author David Vossel <[email protected]>
27  * \author Russell Bryant <[email protected]>
28  */
29 
30 #ifndef _AST_TEST_H_
31 #define _AST_TEST_H_
32 
33 #ifdef TEST_FRAMEWORK
34 #include "asterisk/cli.h"
35 #include "asterisk/strings.h"
36 #endif
37 
38 /*!
39 
40 \page AstUnitTestAPI Asterisk Unit Test API
41 
42 \section UnitTestAPIUsage How to Use the Unit Test API
43 
44 \subsection DefineTest Define a Test
45 
46  Create a callback function for the test using the AST_TEST_DEFINE macro.
47 
48  Each defined test has three arguments available to it's test code.
49  \param struct ast_test_info *info
50  \param enum ast_test_command cmd
51  \param struct ast_test *test
52 
53  While these arguments are not visible they are passed to every test function
54  defined using the AST_TEST_DEFINE macro.
55 
56  Below is an example of how to define and write a test function.
57 
58 \code
59  AST_TEST_DEFINE(sample_test_cb) \\The name of the callback function
60  { \\The the function's body
61  switch (cmd) {
62  case TEST_INIT:
63  info->name = "sample_test";
64  info->category = "main/test/";
65  info->summary = "sample test for example purpose";
66  info->description = "This demonstrates how to initialize a test function";
67 
68  return AST_TEST_NOT_RUN;
69  case TEST_EXECUTE:
70  break;
71  }
72  \test code
73  .
74  .
75  .
76  if (fail) { \\ the following is just some example logic
77  ast_test_status_update(test, "an error occured because...");
78  res = AST_RESULT_FAIL;
79  } else {
80  res = AST_RESULT_PASS
81  }
82  return res; \\ result must be of type enum ast_test_result_state
83  }
84 \endcode
85 
86  Details of the test execution, especially failure details, should be provided
87  by using the ast_test_status_update() function.
88 
89 \subsection RegisterTest Register a Test
90 
91  Register the test using the AST_TEST_REGISTER macro.
92 
93  AST_TEST_REGISTER uses the callback function to retrieve all the information
94  pertaining to a test, so the callback function is the only argument required
95  for registering a test.
96 
97  AST_TEST_REGISTER(sample_test_cb); \\ Test callback function defined by AST_TEST_DEFINE
98 
99  Tests are unregestered by using the AST_TEST_UNREGISTER macro.
100 
101  AST_TEST_UNREGISTER(sample_test_cb); \\ Remove a registered test by callback function
102 
103 \subsection ExecuteTest Execute a Test
104 
105  Execute and generate test results via CLI commands
106 
107  CLI Examples:
108 \code
109  'test show registered all' will show every registered test.
110  'test execute all' will execute every registered test.
111  'test show results all' will show detailed results for ever executed test
112  'test generate results xml' will generate a test report in xml format
113  'test generate results txt' will generate a test report in txt format
114 \endcode
115 */
116 
117 /*! Macros used for defining and registering a test */
118 #ifdef TEST_FRAMEWORK
119 
120 #define AST_TEST_DEFINE(hdr) static enum ast_test_result_state hdr(struct ast_test_info *info, enum ast_test_command cmd, struct ast_test *test)
121 #define AST_TEST_REGISTER(cb) ast_test_register(cb)
122 #define AST_TEST_UNREGISTER(cb) ast_test_unregister(cb)
123 
124 #else
125 
126 #define AST_TEST_DEFINE(hdr) static enum ast_test_result_state attribute_unused hdr(struct ast_test_info *info, enum ast_test_command cmd, struct ast_test *test)
127 #define AST_TEST_REGISTER(cb)
128 #define AST_TEST_UNREGISTER(cb)
129 #define ast_test_status_update(a,b,c...)
130 #define ast_test_debug(test, fmt, ...) ast_cli /* Dummy function that should not be called. */
131 
132 #endif
133 
134 /*! Macros used for the Asterisk Test Suite AMI events */
135 #ifdef TEST_FRAMEWORK
136 
137 struct stasis_topic;
138 struct stasis_message_type;
139 
140 /*!
141  * \since 12
142  * \brief Obtain the \ref stasis_topic for \ref ast_test_suite_event_notify
143  * messages
144  *
145  * \retval A stasis topic
146  */
147 struct stasis_topic *ast_test_suite_topic(void);
148 
149 /*!
150  * \since 12
151  * \brief Obtain the \ref stasis_message_type for \ref ast_test_suite_event_notify
152  * messages
153  *
154  * \retval A stasis message type
155  */
156 struct stasis_message_type *ast_test_suite_message_type(void);
157 
158 /*!
159  * \since 12
160  * \brief The message payload in a \ref ast_test_suite_message_type
161  */
163 
164 /*!
165  * \since 12
166  * \brief Get the JSON for a \ref ast_test_suite_message_payload
167  *
168  * \retval An \ref ast_json object
169  */
171 
172 /*!
173  * \brief Notifies the test suite of a change in application state
174  *
175  * \details
176  * Raises a TestEvent manager event with a subtype of StateChange. Additional parameters
177  * The fmt parameter allows additional parameters to be added to the manager event using
178  * printf style statement formatting.
179  *
180  * \param state The state the application has changed to
181  * \param fmt The message with format parameters to add to the manager event
182  *
183  * \return Nothing
184  */
185 void __ast_test_suite_event_notify(const char *file, const char *func, int line, const char *state, const char *fmt, ...)
186  __attribute__((format(printf, 5, 6)));
187 
188 /*!
189  * \ref __ast_test_suite_event_notify()
190  */
191 #define ast_test_suite_event_notify(s, f, ...) \
192  __ast_test_suite_event_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, (s), (f), ## __VA_ARGS__)
193 
194 #else
195 
196 #define ast_test_suite_event_notify(s, f, ...)
197 
198 #endif
199 
204 };
205 
209 };
210 
211 /*!
212  * \brief An Asterisk unit test.
213  *
214  * This is an opaque type.
215  */
216 struct ast_test;
217 
218 /*!
219  * \brief Contains all the initialization information required to store a new test definition
220  */
222  /*! \brief name of test, unique to category */
223  const char *name;
224  /*!
225  * \brief test category
226  *
227  * \details
228  * Tests are categorized in a directory tree style hierarchy. It is expected that
229  * this string have both a leading and trailing forward slash ('/').
230  */
231  const char *category;
232  /*!
233  * \brief Short summary of test
234  *
235  * \note The summary must not end with a newline.
236  */
237  const char *summary;
238  /*!
239  * \brief More detailed description of test
240  *
241  * \note The description must not end with a newline.
242  */
243  const char *description;
244  /*!
245  * \brief Only run if explicitly named
246  *
247  * \details
248  * Run this test only if it's explicitly named on the command line.
249  * Do NOT run it as part of an execute category or execute all command.
250  */
251  unsigned int explicit_only;
252 };
253 
254 #ifdef TEST_FRAMEWORK
255 /*!
256  * \brief Generic test callback function
257  *
258  * \param info The test info object
259  * \param cmd What to perform in the test
260  * \param test The actual test object being manipulated
261  *
262  * \retval AST_TEST_PASS for pass
263  * \retval AST_TEST_FAIL for failure
264  */
265 typedef enum ast_test_result_state (ast_test_cb_t)(struct ast_test_info *info,
266  enum ast_test_command cmd, struct ast_test *test);
267 
268 /*!
269  * \since 12
270  * \brief A test initialization callback function
271  *
272  * \param info The test info object
273  * \param test The actual test object that will be manipulated
274  *
275  * \retval 0 success
276  * \retval other failure. This will fail the test.
277  */
278 typedef int (ast_test_init_cb_t)(struct ast_test_info *info, struct ast_test *test);
279 
280 /*!
281  * \since 12
282  * \brief A test cleanup callback function
283  *
284  * \param info The test info object
285  * \param test The actual test object that was executed
286  *
287  * \retval 0 success
288  * \retval other failure. This will fail the test.
289  */
290 typedef int (ast_test_cleanup_cb_t)(struct ast_test_info *info, struct ast_test *test);
291 
292 /*!
293  * \brief unregisters a test with the test framework
294  *
295  * \param test callback function (required)
296  *
297  * \retval 0 success
298  * \retval -1 failure
299  */
300 int ast_test_unregister(ast_test_cb_t *cb);
301 
302 /*!
303  * \brief registers a test with the test framework
304  *
305  * \param test callback function (required)
306  *
307  * \retval 0 success
308  * \retval -1 failure
309  */
310 int ast_test_register(ast_test_cb_t *cb);
311 
312 /*!
313  * \since 12
314  * \brief Register an initialization function to be run before each test
315  * executes
316  *
317  * This function lets a registered test have an initialization function that
318  * will be run prior to test execution. Each category may have a single init
319  * function.
320  *
321  * If the initialization function returns a non-zero value, the test will not
322  * be executed and the result will be set to \ref AST_TEST_FAIL.
323  *
324  * \retval 0 success
325  * \retval other failure
326  */
327 int ast_test_register_init(const char *category, ast_test_init_cb_t *cb);
328 
329 /*!
330  * \since 12
331  * \brief Register a cleanup function to be run after each test executes
332  *
333  * This function lets a registered test have a cleanup function that will be
334  * run immediately after test execution. Each category may have a single
335  * cleanup function.
336  *
337  * If the cleanup function returns a non-zero value, the test result will be
338  * set to \ref AST_TEST_FAIL.
339  *
340  * \retval 0 success
341  * \retval other failure
342  */
343 int ast_test_register_cleanup(const char *category, ast_test_cleanup_cb_t *cb);
344 
345 
346 /*!
347  * \brief Unit test debug output.
348  * \since 12.0.0
349  *
350  * \param test Unit test control structure.
351  * \param fmt printf type format string.
352  *
353  * \return Nothing
354  */
355 void ast_test_debug(struct ast_test *test, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
356 
357 /*!
358  * \brief Set the result of a test.
359  *
360  * If the caller of this function sets the result to AST_TEST_FAIL, returning
361  * AST_TEST_PASS from the test will not pass the test. This lets a test writer
362  * end and fail a test and continue on with logic, catching multiple failure
363  * conditions within a single test.
364  */
365 void ast_test_set_result(struct ast_test *test, enum ast_test_result_state state);
366 
367 
368 /*!
369  * \brief update test's status during testing.
370  *
371  * \param test currently executing test
372  *
373  * \retval 0 success
374  * \retval -1 failure
375  */
376 int __ast_test_status_update(const char *file, const char *func, int line, struct ast_test *test, const char *fmt, ...)
377  __attribute__((format(printf, 5, 6)));
378 
379 /*!
380  * \ref __ast_test_status_update()
381  */
382 #define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__)
383 
384 /*!
385  * \brief Check a test condition, failing the test if it's not true.
386  *
387  * \since 12.0.0
388  *
389  * This macro evaluates \a condition. If the condition evaluates to true (non-zero),
390  * nothing happens. If it evaluates to false (zero), then the failure is printed
391  * using \ref ast_test_status_update, and the current test is ended with AST_TEST_FAIL.
392  *
393  * Sadly, the name 'ast_test_assert' was already taken.
394  *
395  * Note that since this macro returns from the current test, there must not be any
396  * cleanup work to be done before returning. Use \ref RAII_VAR for test cleanup.
397  *
398  * \param test Currently executing test
399  * \param condition Boolean condition to check.
400  */
401 #define ast_test_validate(test, condition, ...) \
402  do { \
403  if (!(condition)) { \
404  __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (test), "%s: %s\n", strlen(#__VA_ARGS__) ? #__VA_ARGS__ : "Condition failed", #condition); \
405  return AST_TEST_FAIL; \
406  } \
407  } while(0)
408 
409 /*!
410  * \brief Check a test condition, report error and goto cleanup label if failed.
411  *
412  * \since 13.4.0
413  *
414  * This macro evaluates \a condition. If the condition evaluates to true (non-zero),
415  * nothing happens. If it evaluates to false (zero), then the failure is printed
416  * using \ref ast_test_status_update, the variable \a rc_variable is set to AST_TEST_FAIL,
417  * and a goto to \a cleanup_label is executed.
418  *
419  * \param test Currently executing test
420  * \param condition Boolean condition to check.
421  * \param rc_variable Variable to receive AST_TEST_FAIL.
422  * \param cleanup_label The label to go to on failure.
423  */
424 #define ast_test_validate_cleanup(test, condition, rc_variable, cleanup_label) ({ \
425  if (!(condition)) { \
426  ast_test_status_update((test), "%s: %s\n", "Condition failed", #condition); \
427  rc_variable = AST_TEST_FAIL; \
428  goto cleanup_label; \
429  } \
430 })
431 
432 #endif /* TEST_FRAMEWORK */
433 #endif /* _AST_TEST_H */
Contains all the initialization information required to store a new test definition.
Definition: test.h:221
const char * summary
Short summary of test.
Definition: test.h:237
void __ast_test_suite_event_notify(const char *file, const char *func, int line, const char *state, const char *fmt,...)
Definition: test.c:1145
String manipulation functions.
int ast_test_unregister(ast_test_cb_t *cb)
Definition: test.c:218
int ast_test_register_init(const char *category, ast_test_init_cb_t *cb)
Definition: test.c:160
int ast_test_register(ast_test_cb_t *cb)
Definition: test.c:194
struct ast_json * ast_test_suite_get_blob(struct ast_test_suite_message_payload *payload)
Definition: test.c:1095
int __ast_test_status_update(const char *file, const char *func, int line, struct ast_test *test, const char *fmt,...)
Definition: test.c:134
const char * description
More detailed description of test.
Definition: test.h:243
const char * name
name of test, unique to category
Definition: test.h:223
int ast_test_register_cleanup(const char *category, ast_test_cleanup_cb_t *cb)
Definition: test.c:177
def info(msg)
struct stasis_topic * ast_test_suite_topic(void)
Definition: test.c:1069
ast_test_command
Definition: test.h:206
const char * category
test category
Definition: test.h:231
void ast_test_set_result(struct ast_test *test, enum ast_test_result_state state)
Definition: test.c:262
unsigned int explicit_only
Only run if explicitly named.
Definition: test.h:251
A wrapper object that can be ao2 ref counted around an ast_json blob.
Definition: test.c:1078
ast_test_cb_t * cb
Definition: test.c:80
#define ast_test_debug(test, fmt,...)
Definition: test.h:130
Definition: test.c:65
Standard Command Line Interface.
Abstract JSON element (object, array, string, int, ...).
static snd_pcm_format_t format
Definition: chan_alsa.c:102
ast_test_result_state
Definition: test.h:200
static struct ast_test * test
Definition: localtime.c:115