Wed Jan 27 20:02:16 2016

Asterisk developer's documentation


test.h

Go to the documentation of this file.
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 available 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 */

Generated on 27 Jan 2016 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1