Asterisk - The Open Source Telephony Project GIT-master-7921072
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 <dvossel@digium.com>
7 * Russell Bryant <russell@digium.com>
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 <dvossel@digium.com>
27 * \author Russell Bryant <russell@digium.com>
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 every 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
137struct stasis_topic;
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 */
147struct 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 */
156struct 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 */
162struct ast_test_suite_message_payload;
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 */
170struct ast_json *ast_test_suite_get_blob(struct ast_test_suite_message_payload *payload);
171
172/*!
173 * \brief Notifies the test suite of a change in application state
174 *
175 * Raises a TestEvent manager event with a subtype of StateChange. Additional parameters
176 * The fmt parameter allows additional parameters to be added to the manager event using
177 * printf style statement formatting.
178 *
179 * \param s The state the application has changed to
180 * \param f The message with format parameters to add to the manager event
181 */
182#define ast_test_suite_event_notify(s, f, ...) \
183 __ast_test_suite_event_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, (s), (f), ## __VA_ARGS__)
184void __ast_test_suite_event_notify(const char *file, const char *func, int line, const char *state, const char *fmt, ...)
185 __attribute__((format(printf, 5, 6)));
186
187#else
188
189#define ast_test_suite_event_notify(s, f, ...)
190
191#endif
192
197};
198
202};
203
204/*!
205 * \brief An Asterisk unit test.
206 *
207 * This is an opaque type.
208 */
209struct ast_test;
210
211/*!
212 * \brief A capture of running an external process.
213 *
214 * This contains a buffer holding stdout, another containing stderr,
215 * the process id of the child, and its exit code.
216 */
218 /*! \brief buffer holding stdout */
219 char *outbuf;
220 /*! \brief length of buffer holding stdout */
221 size_t outlen;
222 /*! \brief buffer holding stderr */
223 char *errbuf;
224 /*! \brief length of buffer holding stderr */
225 size_t errlen;
226 /*! \brief process id of child */
227 pid_t pid;
228 /*! \brief exit code of child */
230};
231
232/*!
233 * \brief Contains all the initialization information required to store a new test definition
234 */
236 /*! \brief name of test, unique to category */
237 const char *name;
238 /*!
239 * \brief test category
240 *
241 * \details
242 * Tests are categorized in a directory tree style hierarchy. It is expected that
243 * this string have both a leading and trailing forward slash ('/').
244 */
245 const char *category;
246 /*!
247 * \brief Short summary of test
248 *
249 * \note The summary must not end with a newline.
250 */
251 const char *summary;
252 /*!
253 * \brief More detailed description of test
254 *
255 * \note The description must not end with a newline.
256 */
257 const char *description;
258 /*!
259 * \brief Only run if explicitly named
260 *
261 * \details
262 * Run this test only if it's explicitly named on the command line.
263 * Do NOT run it as part of an execute category or execute all command.
264 */
265 unsigned int explicit_only;
266};
267
268#ifdef TEST_FRAMEWORK
269/*!
270 * \brief Generic test callback function
271 *
272 * \param info The test info object
273 * \param cmd What to perform in the test
274 * \param test The actual test object being manipulated
275 *
276 * \retval AST_TEST_PASS for pass
277 * \retval AST_TEST_FAIL for failure
278 */
279typedef enum ast_test_result_state (ast_test_cb_t)(struct ast_test_info *info,
280 enum ast_test_command cmd, struct ast_test *test);
281
282/*!
283 * \since 12
284 * \brief A test initialization callback function
285 *
286 * \param info The test info object
287 * \param test The actual test object that will be manipulated
288 *
289 * \retval 0 success
290 * \retval other failure. This will fail the test.
291 */
292typedef int (ast_test_init_cb_t)(struct ast_test_info *info, struct ast_test *test);
293
294/*!
295 * \since 12
296 * \brief A test cleanup callback function
297 *
298 * \param info The test info object
299 * \param test The actual test object that was executed
300 *
301 * \retval 0 success
302 * \retval other failure. This will fail the test.
303 */
304typedef int (ast_test_cleanup_cb_t)(struct ast_test_info *info, struct ast_test *test);
305
306/*!
307 * \brief unregisters a test with the test framework
308 *
309 * \param cb callback function (required)
310 *
311 * \retval 0 success
312 * \retval -1 failure
313 */
314int ast_test_unregister(ast_test_cb_t *cb);
315
316/*!
317 * \brief registers a test with the test framework
318 *
319 * \param cb callback function (required)
320 *
321 * \retval 0 success
322 * \retval -1 failure
323 */
324int ast_test_register(ast_test_cb_t *cb);
325
326/*!
327 * \since 12
328 * \brief Register an initialization function to be run before each test
329 * executes
330 *
331 * This function lets a registered test have an initialization function that
332 * will be run prior to test execution. Each category may have a single init
333 * function.
334 *
335 * If the initialization function returns a non-zero value, the test will not
336 * be executed and the result will be set to \ref AST_TEST_FAIL.
337 *
338 * \retval 0 success
339 * \retval other failure
340 */
341int ast_test_register_init(const char *category, ast_test_init_cb_t *cb);
342
343/*!
344 * \since 12
345 * \brief Register a cleanup function to be run after each test executes
346 *
347 * This function lets a registered test have a cleanup function that will be
348 * run immediately after test execution. Each category may have a single
349 * cleanup function.
350 *
351 * If the cleanup function returns a non-zero value, the test result will be
352 * set to \ref AST_TEST_FAIL.
353 *
354 * \retval 0 success
355 * \retval other failure
356 */
357int ast_test_register_cleanup(const char *category, ast_test_cleanup_cb_t *cb);
358
359
360/*!
361 * \brief Unit test debug output.
362 * \since 12.0.0
363 *
364 * \param test Unit test control structure.
365 * \param fmt printf type format string.
366 */
367void ast_test_debug(struct ast_test *test, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
368
369/*!
370 * \brief Set the result of a test.
371 *
372 * If the caller of this function sets the result to AST_TEST_FAIL, returning
373 * AST_TEST_PASS from the test will not pass the test. This lets a test writer
374 * end and fail a test and continue on with logic, catching multiple failure
375 * conditions within a single test.
376 */
377void ast_test_set_result(struct ast_test *test, enum ast_test_result_state state);
378
379
380/*!
381 * \brief update test's status during testing.
382 *
383 * \param t currently executing test
384 * \param f printf type format string
385 *
386 * \retval 0 success
387 * \retval -1 failure
388 */
389#define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__)
390int __ast_test_status_update(const char *file, const char *func, int line, struct ast_test *test, const char *fmt, ...)
391 __attribute__((format(printf, 5, 6)));
392
393/*!
394 * \brief Check a test condition, failing the test if it's not true.
395 *
396 * \since 12.0.0
397 *
398 * This macro evaluates \a condition. If the condition evaluates to true (non-zero),
399 * nothing happens. If it evaluates to false (zero), then the failure is printed
400 * using \ref ast_test_status_update, and the current test is ended with AST_TEST_FAIL.
401 *
402 * Sadly, the name 'ast_test_assert' was already taken.
403 *
404 * Note that since this macro returns from the current test, there must not be any
405 * cleanup work to be done before returning. Use \ref RAII_VAR for test cleanup.
406 *
407 * \param test Currently executing test
408 * \param condition Boolean condition to check.
409 */
410#define ast_test_validate(test, condition, ...) \
411 do { \
412 if (!(condition)) { \
413 __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (test), "%s: %s\n", strlen(#__VA_ARGS__) ? #__VA_ARGS__ : "Condition failed", #condition); \
414 return AST_TEST_FAIL; \
415 } \
416 } while(0)
417
418/*!
419 * \brief Check a test condition, report error and goto cleanup label if failed.
420 *
421 * \since 13.4.0
422 *
423 * This macro evaluates \a condition. If the condition evaluates to true (non-zero),
424 * nothing happens. If it evaluates to false (zero), then the failure is printed
425 * using \ref ast_test_status_update, the variable \a rc_variable is set to AST_TEST_FAIL,
426 * and a goto to \a cleanup_label is executed.
427 *
428 * \param test Currently executing test
429 * \param condition Boolean condition to check.
430 * \param rc_variable Variable to receive AST_TEST_FAIL.
431 * \param cleanup_label The label to go to on failure.
432 */
433#define ast_test_validate_cleanup(test, condition, rc_variable, cleanup_label) ({ \
434 if (!(condition)) { \
435 ast_test_status_update((test), "%s: %s\n", "Condition failed", #condition); \
436 rc_variable = AST_TEST_FAIL; \
437 goto cleanup_label; \
438 } \
439})
440
441/*!
442 * \brief Initialize the capture structure.
443 *
444 * \since 16.30.0, 18.16.0, 19.8.0, 20.1.0
445 *
446 * \param capture The structure describing the child process and its
447 * associated output.
448 */
449void ast_test_capture_init(struct ast_test_capture *capture);
450
451/*!
452 * \brief Release the storage (buffers) associated with capturing
453 * the output of an external child process.
454 *
455 * \since 19.4.0
456 *
457 * \param capture The structure describing the child process and its
458 * associated output.
459 */
460void ast_test_capture_free(struct ast_test_capture *capture);
461
462/*!
463 * \brief Run a child process and capture its output and exit code.
464 *
465 * \!since 19.4.0
466 *
467 * \param capture The structure describing the child process and its
468 * associated output.
469 *
470 * \param file The name of the file to execute (uses $PATH to locate).
471 *
472 * \param argv The NULL-terminated array of arguments to pass to the
473 * child process, starting with the command name itself.
474 *
475 * \param data The buffer of input to be sent to child process's stdin;
476 * optional and may be NULL.
477 *
478 * \param datalen The length of the buffer, if not NULL, otherwise zero.
479 *
480 * \retval 1 for success
481 * \retval other failure
482 */
483
484int ast_test_capture_command(struct ast_test_capture *capture, const char *file, char *const argv[], const char *data, unsigned datalen);
485
486#endif /* TEST_FRAMEWORK */
487#endif /* _AST_TEST_H */
Standard Command Line Interface.
def info(msg)
String manipulation functions.
Abstract JSON element (object, array, string, int, ...).
A capture of running an external process.
Definition: test.h:217
char * outbuf
buffer holding stdout
Definition: test.h:219
char * errbuf
buffer holding stderr
Definition: test.h:223
size_t errlen
length of buffer holding stderr
Definition: test.h:225
pid_t pid
process id of child
Definition: test.h:227
size_t outlen
length of buffer holding stdout
Definition: test.h:221
int exitcode
exit code of child
Definition: test.h:229
Contains all the initialization information required to store a new test definition.
Definition: test.h:235
const char * summary
Short summary of test.
Definition: test.h:251
const char * category
test category
Definition: test.h:245
unsigned int explicit_only
Only run if explicitly named.
Definition: test.h:265
const char * description
More detailed description of test.
Definition: test.h:257
const char * name
name of test, unique to category
Definition: test.h:237
ast_test_command
Definition: test.h:199
@ TEST_INIT
Definition: test.h:200
@ TEST_EXECUTE
Definition: test.h:201
#define ast_test_debug(test, fmt,...)
Definition: test.h:130
ast_test_result_state
Definition: test.h:193
@ AST_TEST_PASS
Definition: test.h:195
@ AST_TEST_FAIL
Definition: test.h:196
@ AST_TEST_NOT_RUN
Definition: test.h:194