fixes test.c compile issue when TEST_FRAMEWORK is not enabled
[asterisk/asterisk.git] / include / asterisk / test.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2009, Digium, Inc.
5  *
6  * David Vossel <dvossel@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*!
20  * \file
21  * \brief Test Framework API
22  *
23  * For an overview on how to use the test API, see \ref AstUnitTestAPI
24  *
25  * \author David Vossel <dvossel@digium.com>
26  */
27
28 #ifndef _AST_TEST_H_
29 #define _AST_TEST_H_
30
31 #ifdef TEST_FRAMEWORK
32 #include "asterisk/cli.h"
33 #include "asterisk/strings.h"
34 #endif
35
36 /*! 
37
38 \page AstUnitTestAPI Asterisk Unit Test API
39
40 \section UnitTestAPIUsage How to Use the Unit Test API
41
42 \subsection DefineTest Define a Test
43
44    Create a callback function for the test using the AST_TEST_DEFINE macro.
45
46    Each defined test has three arguments avaliable to it's test code.
47        \param struct ast_test_info *info
48        \param enum ast_test_command cmd
49        \param struct ast_test_args *args
50
51    While these arguments are not visible they are passed to every test function
52    defined using the AST_TEST_DEFINE macro.
53
54    Below is an example of how to define and write a test function.
55
56 \code
57    AST_TEST_DEFINE(sample_test_cb) \\The name of the callback function
58    {                               \\The the function's body 
59       switch (cmd) {
60       case TEST_INIT:
61           info->name = "sample_test";
62           info->category = "main/test/";
63           info->summary = "sample test for example purpose";
64           info->description = "This demonstrates how to initialize a test function";
65
66           return AST_TEST_NOT_RUN;
67       case TEST_EXECUTE:
68           break;
69       }
70       \test code
71       .
72       .
73       .
74       if (fail) {                 \\ the following is just some example logic
75           ast_str_set(&args->ast_test_error_str, 0 , "an error occured because...");
76           res = AST_RESULT_FAIL;
77       } else {
78           res = AST_RESULT_PASS
79       }
80       return res;                 \\ result must be of type enum ast_test_result_state
81    }
82 \endcode
83
84    Every callback function is passed an ast_test_args object which contains
85    an ast_str allowing the function to provide an optional short description of
86    what went wrong if the test failed. This is done by writing to
87    args->ast_test_error_str.
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_args *args)
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_args *args)
127 #define AST_TEST_REGISTER(cb)
128 #define AST_TEST_UNREGISTER(cb)
129 #define ast_test_status_update(a,b,c...)
130
131 #endif
132
133 enum ast_test_result_state {
134         AST_TEST_NOT_RUN,
135         AST_TEST_PASS,
136         AST_TEST_FAIL,
137 };
138
139 enum ast_test_command {
140         TEST_INIT,
141         TEST_EXECUTE,
142 };
143
144 /*!
145  *  This struct is passed to ast_test_status_update() providing a place to push
146  *  the update to. In the future this structure may expand beyond simply being
147  *  a wrapper for cli args to including other status update options as well.
148  */
149 struct ast_test_status_args {
150         /*! pointer to cli arg used for updating status */
151         struct ast_cli_args *cli;
152 };
153
154 /*!
155  * tools made available to the callback function during test execution
156  */
157 struct ast_test_args {
158         struct ast_str *ast_test_error_str;  /*! optional error str to describe error result */
159         struct ast_test_status_args status_update;
160 };
161
162 /*!
163  * Contains all the initilization information required to store a new test definition
164  */
165 struct ast_test_info {
166         /*! name of test, unique to category */
167         const char *name;
168         /*! test category */
169         const char *category;
170         /*! optional short summary of test */
171         const char *summary;
172         /*! optional brief detailed description of test */
173         const char *description;
174 };
175
176 #ifdef TEST_FRAMEWORK
177 /*!
178  * \brief Generic test callback function
179  *
180  * \param error buffer string for failure results
181  *
182  * \retval AST_TEST_PASS for pass
183  * \retval AST_TEST_FAIL for failure
184  */
185 typedef enum ast_test_result_state (ast_test_cb_t)(struct ast_test_info *info, enum ast_test_command cmd, struct ast_test_args *args);
186
187 /*!
188  * \brief unregisters a test with the test framework
189  *
190  * \param test callback function (required)
191  *
192  * \retval 0 success
193  * \retval -1 failure
194  */
195 int ast_test_unregister(ast_test_cb_t *cb);
196
197 /*!
198  * \brief registers a test with the test framework
199  *
200  * \param test callback function (required)
201  *
202  * \retval 0 success
203  * \retval -1 failure
204  */
205 int ast_test_register(ast_test_cb_t *cb);
206
207 /*!
208  * \brief update test's status during testing.
209  *
210  * \param ast_test_status_args defines everywhere the update should go.
211  *
212  * \retval 0 success
213  * \retval -1 failure
214  */
215 int ast_test_status_update(struct ast_test_status_args *args, const char *fmt, ...)
216 __attribute__((format(printf, 2, 3)));
217
218 #endif /* TEST_FRAMEWORK */
219 #endif /* _AST_TEST_H */