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 enum ast_test_result_state { 00134 AST_TEST_NOT_RUN, 00135 AST_TEST_PASS, 00136 AST_TEST_FAIL, 00137 }; 00138 00139 enum ast_test_command { 00140 TEST_INIT, 00141 TEST_EXECUTE, 00142 }; 00143 00144 /*! 00145 * \brief An Asterisk unit test. 00146 * 00147 * This is an opaque type. 00148 */ 00149 struct ast_test; 00150 00151 /*! 00152 * \brief Contains all the initialization information required to store a new test definition 00153 */ 00154 struct ast_test_info { 00155 /*! \brief name of test, unique to category */ 00156 const char *name; 00157 /*! 00158 * \brief test category 00159 * 00160 * Tests are categorized in a directory tree style hierarchy. It is expected that 00161 * this string have both a leading and trailing forward slash ('/'). 00162 */ 00163 const char *category; 00164 /*! \brief optional short summary of test */ 00165 const char *summary; 00166 /*! \brief optional brief detailed description of test */ 00167 const char *description; 00168 }; 00169 00170 #ifdef TEST_FRAMEWORK 00171 /*! 00172 * \brief Generic test callback function 00173 * 00174 * \param error buffer string for failure results 00175 * 00176 * \retval AST_TEST_PASS for pass 00177 * \retval AST_TEST_FAIL for failure 00178 */ 00179 typedef enum ast_test_result_state (ast_test_cb_t)(struct ast_test_info *info, 00180 enum ast_test_command cmd, struct ast_test *test); 00181 00182 /*! 00183 * \brief unregisters a test with the test framework 00184 * 00185 * \param test callback function (required) 00186 * 00187 * \retval 0 success 00188 * \retval -1 failure 00189 */ 00190 int ast_test_unregister(ast_test_cb_t *cb); 00191 00192 /*! 00193 * \brief registers a test with the test framework 00194 * 00195 * \param test callback function (required) 00196 * 00197 * \retval 0 success 00198 * \retval -1 failure 00199 */ 00200 int ast_test_register(ast_test_cb_t *cb); 00201 00202 /*! 00203 * \brief update test's status during testing. 00204 * 00205 * \param test currently executing test 00206 * 00207 * \retval 0 success 00208 * \retval -1 failure 00209 */ 00210 int __ast_test_status_update(const char *file, const char *func, int line, 00211 struct ast_test *test, const char *fmt, ...) 00212 __attribute__((format(printf, 5, 6))); 00213 00214 /*! 00215 * \ref __ast_test_status_update() 00216 */ 00217 #define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__) 00218 00219 #endif /* TEST_FRAMEWORK */ 00220 #endif /* _AST_TEST_H */