00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2009-2010, Digium, Inc. 00005 * 00006 * David Vossel <dvossel@digium.com> 00007 * Russell Bryant <russell@digium.com> 00008 * 00009 * See http://www.asterisk.org for more information about 00010 * the Asterisk project. Please do not directly contact 00011 * any of the maintainers of this project for assistance; 00012 * the project provides a web site, mailing lists and IRC 00013 * channels for your use. 00014 * 00015 * This program is free software, distributed under the terms of 00016 * the GNU General Public License Version 2. See the LICENSE file 00017 * at the top of the source tree. 00018 */ 00019 00020 /*! 00021 * \file 00022 * \brief Test Framework API 00023 * 00024 * For an overview on how to use the test API, see \ref AstUnitTestAPI 00025 * 00026 * \author David Vossel <dvossel@digium.com> 00027 * \author Russell Bryant <russell@digium.com> 00028 */ 00029 00030 #ifndef _AST_TEST_H_ 00031 #define _AST_TEST_H_ 00032 00033 #ifdef TEST_FRAMEWORK 00034 #include "asterisk/cli.h" 00035 #include "asterisk/strings.h" 00036 #endif 00037 00038 /*! 00039 00040 \page AstUnitTestAPI Asterisk Unit Test API 00041 00042 \section UnitTestAPIUsage How to Use the Unit Test API 00043 00044 \subsection DefineTest Define a Test 00045 00046 Create a callback function for the test using the AST_TEST_DEFINE macro. 00047 00048 Each defined test has three arguments avaliable to it's test code. 00049 \param struct ast_test_info *info 00050 \param enum ast_test_command cmd 00051 \param struct ast_test *test 00052 00053 While these arguments are not visible they are passed to every test function 00054 defined using the AST_TEST_DEFINE macro. 00055 00056 Below is an example of how to define and write a test function. 00057 00058 \code 00059 AST_TEST_DEFINE(sample_test_cb) \\The name of the callback function 00060 { \\The the function's body 00061 switch (cmd) { 00062 case TEST_INIT: 00063 info->name = "sample_test"; 00064 info->category = "main/test/"; 00065 info->summary = "sample test for example purpose"; 00066 info->description = "This demonstrates how to initialize a test function"; 00067 00068 return AST_TEST_NOT_RUN; 00069 case TEST_EXECUTE: 00070 break; 00071 } 00072 \test code 00073 . 00074 . 00075 . 00076 if (fail) { \\ the following is just some example logic 00077 ast_test_status_update(test, "an error occured because..."); 00078 res = AST_RESULT_FAIL; 00079 } else { 00080 res = AST_RESULT_PASS 00081 } 00082 return res; \\ result must be of type enum ast_test_result_state 00083 } 00084 \endcode 00085 00086 Details of the test execution, especially failure details, should be provided 00087 by using the ast_test_status_update() function. 00088 00089 \subsection RegisterTest Register a Test 00090 00091 Register the test using the AST_TEST_REGISTER macro. 00092 00093 AST_TEST_REGISTER uses the callback function to retrieve all the information 00094 pertaining to a test, so the callback function is the only argument required 00095 for registering a test. 00096 00097 AST_TEST_REGISTER(sample_test_cb); \\ Test callback function defined by AST_TEST_DEFINE 00098 00099 Tests are unregestered by using the AST_TEST_UNREGISTER macro. 00100 00101 AST_TEST_UNREGISTER(sample_test_cb); \\ Remove a registered test by callback function 00102 00103 \subsection ExecuteTest Execute a Test 00104 00105 Execute and generate test results via CLI commands 00106 00107 CLI Examples: 00108 \code 00109 'test show registered all' will show every registered test. 00110 'test execute all' will execute every registered test. 00111 'test show results all' will show detailed results for ever executed test 00112 'test generate results xml' will generate a test report in xml format 00113 'test generate results txt' will generate a test report in txt format 00114 \endcode 00115 */ 00116 00117 /*! Macros used for defining and registering a test */ 00118 #ifdef TEST_FRAMEWORK 00119 00120 #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) 00121 #define AST_TEST_REGISTER(cb) ast_test_register(cb) 00122 #define AST_TEST_UNREGISTER(cb) ast_test_unregister(cb) 00123 00124 #else 00125 00126 #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) 00127 #define AST_TEST_REGISTER(cb) 00128 #define AST_TEST_UNREGISTER(cb) 00129 #define ast_test_status_update(a,b,c...) 00130 00131 #endif 00132 00133 /*! Macros used for the Asterisk Test Suite AMI events */ 00134 #ifdef TEST_FRAMEWORK 00135 00136 /*! 00137 * \brief Notifies the test suite of a change in application state 00138 * 00139 * \details 00140 * Raises a TestEvent manager event with a subtype of StateChange. Additional parameters 00141 * The fmt parameter allows additional parameters to be added to the manager event using 00142 * printf style statement formatting. 00143 * 00144 * \param state The state the application has changed to 00145 * \param fmt The message with format parameters to add to the manager event 00146 * 00147 * \returns 0 on success 00148 * \returns any other value on failure 00149 */ 00150 int __ast_test_suite_event_notify(const char *file, const char *func, int line, 00151 const char *state, const char *fmt, ...) 00152 __attribute__((format(printf, 5, 6))); 00153 00154 /*! 00155 * \brief Notifies the test suite of a failed assert on an expression 00156 * 00157 * \details 00158 * If the expression provided evaluates to true, no action is taken. If the expression 00159 * evaluates to a false, a TestEvent manager event is raised with a subtype of Assert, notifying 00160 * the test suite that the expression failed to evaluate to true. 00161 * 00162 * \param exp The expression to evaluate 00163 * 00164 * \returns 0 on success 00165 * \returns any other value on failure 00166 */ 00167 int __ast_test_suite_assert_notify(const char *file, const char *func, int line, 00168 const char *exp); 00169 00170 /*! 00171 * \ref __ast_test_suite_event_notify() 00172 */ 00173 #define ast_test_suite_event_notify(s, f, ...) \ 00174 __ast_test_suite_event_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, (s), (f), ## __VA_ARGS__) 00175 00176 /*! 00177 * \ref __ast_test_suite_assert_notify() 00178 */ 00179 #define ast_test_suite_assert(exp) \ 00180 ( (exp) ? (void)0 : __ast_test_suite_assert_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, #exp)) 00181 00182 #else 00183 00184 #define ast_test_suite_event_notify(s, f, ...) (void)0; 00185 #define ast_test_suite_assert(exp) (void)0; 00186 00187 #endif 00188 00189 enum ast_test_result_state { 00190 AST_TEST_NOT_RUN, 00191 AST_TEST_PASS, 00192 AST_TEST_FAIL, 00193 }; 00194 00195 enum ast_test_command { 00196 TEST_INIT, 00197 TEST_EXECUTE, 00198 }; 00199 00200 /*! 00201 * \brief An Asterisk unit test. 00202 * 00203 * This is an opaque type. 00204 */ 00205 struct ast_test; 00206 00207 /*! 00208 * \brief Contains all the initialization information required to store a new test definition 00209 */ 00210 struct ast_test_info { 00211 /*! \brief name of test, unique to category */ 00212 const char *name; 00213 /*! 00214 * \brief test category 00215 * 00216 * Tests are categorized in a directory tree style hierarchy. It is expected that 00217 * this string have both a leading and trailing forward slash ('/'). 00218 */ 00219 const char *category; 00220 /*! \brief optional short summary of test */ 00221 const char *summary; 00222 /*! \brief optional brief detailed description of test */ 00223 const char *description; 00224 }; 00225 00226 #ifdef TEST_FRAMEWORK 00227 /*! 00228 * \brief Generic test callback function 00229 * 00230 * \param error buffer string for failure results 00231 * 00232 * \retval AST_TEST_PASS for pass 00233 * \retval AST_TEST_FAIL for failure 00234 */ 00235 typedef enum ast_test_result_state (ast_test_cb_t)(struct ast_test_info *info, 00236 enum ast_test_command cmd, struct ast_test *test); 00237 00238 /*! 00239 * \brief unregisters a test with the test framework 00240 * 00241 * \param test callback function (required) 00242 * 00243 * \retval 0 success 00244 * \retval -1 failure 00245 */ 00246 int ast_test_unregister(ast_test_cb_t *cb); 00247 00248 /*! 00249 * \brief registers a test with the test framework 00250 * 00251 * \param test callback function (required) 00252 * 00253 * \retval 0 success 00254 * \retval -1 failure 00255 */ 00256 int ast_test_register(ast_test_cb_t *cb); 00257 00258 /*! 00259 * \brief update test's status during testing. 00260 * 00261 * \param test currently executing test 00262 * 00263 * \retval 0 success 00264 * \retval -1 failure 00265 */ 00266 int __ast_test_status_update(const char *file, const char *func, int line, 00267 struct ast_test *test, const char *fmt, ...) 00268 __attribute__((format(printf, 5, 6))); 00269 00270 /*! 00271 * \ref __ast_test_status_update() 00272 */ 00273 #define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__) 00274 00275 #endif /* TEST_FRAMEWORK */ 00276 #endif /* _AST_TEST_H */