Merged revisions 275021 via svnmerge from
[asterisk/asterisk.git] / include / asterisk / test.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2009-2010, 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 avaliable 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
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  * \brief An Asterisk unit test.
146  *
147  * This is an opaque type.
148  */
149 struct ast_test;
150
151 /*!
152  * \brief Contains all the initialization information required to store a new test definition
153  */
154 struct ast_test_info {
155         /*! \brief name of test, unique to category */
156         const char *name;
157         /*!
158          * \brief test category
159          *
160          * Tests are categorized in a directory tree style hierarchy.  It is expected that
161          * this string have both a leading and trailing forward slash ('/').
162          */
163         const char *category;
164         /*! \brief optional short summary of test */
165         const char *summary;
166         /*! \brief optional brief detailed description of test */
167         const char *description;
168 };
169
170 #ifdef TEST_FRAMEWORK
171 /*!
172  * \brief Generic test callback function
173  *
174  * \param error buffer string for failure results
175  *
176  * \retval AST_TEST_PASS for pass
177  * \retval AST_TEST_FAIL for failure
178  */
179 typedef enum ast_test_result_state (ast_test_cb_t)(struct ast_test_info *info,
180                 enum ast_test_command cmd, struct ast_test *test);
181
182 /*!
183  * \brief unregisters a test with the test framework
184  *
185  * \param test callback function (required)
186  *
187  * \retval 0 success
188  * \retval -1 failure
189  */
190 int ast_test_unregister(ast_test_cb_t *cb);
191
192 /*!
193  * \brief registers a test with the test framework
194  *
195  * \param test callback function (required)
196  *
197  * \retval 0 success
198  * \retval -1 failure
199  */
200 int ast_test_register(ast_test_cb_t *cb);
201
202 /*!
203  * \brief update test's status during testing.
204  *
205  * \param test currently executing test
206  *
207  * \retval 0 success
208  * \retval -1 failure
209  */
210 int __ast_test_status_update(const char *file, const char *func, int line,
211                 struct ast_test *test, const char *fmt, ...)
212                 __attribute__((format(printf, 5, 6)));
213
214 /*!
215  * \ref __ast_test_status_update()
216  */
217 #define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__)
218
219 #endif /* TEST_FRAMEWORK */
220 #endif /* _AST_TEST_H */