include/asterisk/test.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2009-2013, 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 #define ast_test_debug(test, fmt, ...)  ast_cli         /* Dummy function that should not be called. */
 131
 132 #endif
 133
 134 /*! Macros used for the Asterisk Test Suite AMI events */
 135 #ifdef TEST_FRAMEWORK
 136
 137 struct stasis_topic;
 138 struct stasis_message_type;
 139
 140 /*!
 141  * \since 12
 142  * \brief Obtain the \ref stasis_topic for \ref ast_test_suite_event_notify
 143  * messages
 144  *
 145  * \retval A stasis topic
 146  */
 147 struct stasis_topic *ast_test_suite_topic(void);
 148
 149 /*!
 150  * \since 12
 151  * \brief Obtain the \ref stasis_message_type for \ref ast_test_suite_event_notify
 152  * messages
 153  *
 154  * \retval A stasis message type
 155  */
 156 struct stasis_message_type *ast_test_suite_message_type(void);
 157
 158 /*!
 159  * \since 12
 160  * \brief The message payload in a \ref ast_test_suite_message_type
 161  */
 162 struct ast_test_suite_message_payload;
 163
 164 /*!
 165  * \since 12
 166  * \brief Get the JSON for a \ref ast_test_suite_message_payload
 167  *
 168  * \retval An \ref ast_json object
 169  */
 170 struct ast_json *ast_test_suite_get_blob(struct ast_test_suite_message_payload *payload);
 171
 172 /*!
 173  * \brief Notifies the test suite of a change in application state
 174  *
 175  * \details
 176  * Raises a TestEvent manager event with a subtype of StateChange.  Additional parameters
 177  * The fmt parameter allows additional parameters to be added to the manager event using
 178  * printf style statement formatting.
 179  *
 180  * \param state         The state the application has changed to
 181  * \param fmt           The message with format parameters to add to the manager event
 182  *
 183  * \return Nothing
 184  */
 185 void __ast_test_suite_event_notify(const char *file, const char *func, int line, const char *state, const char *fmt, ...)
 186         __attribute__((format(printf, 5, 6)));
 187
 188 /*!
 189  * \ref __ast_test_suite_event_notify()
 190  */
 191 #define ast_test_suite_event_notify(s, f, ...) \
 192         __ast_test_suite_event_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, (s), (f), ## __VA_ARGS__)
 193
 194 #else
 195
 196 #define ast_test_suite_event_notify(s, f, ...)
 197
 198 #endif
 199
 200 enum ast_test_result_state {
 201         AST_TEST_NOT_RUN,
 202         AST_TEST_PASS,
 203         AST_TEST_FAIL,
 204 };
 205
 206 enum ast_test_command {
 207         TEST_INIT,
 208         TEST_EXECUTE,
 209 };
 210
 211 /*!
 212  * \brief An Asterisk unit test.
 213  *
 214  * This is an opaque type.
 215  */
 216 struct ast_test;
 217
 218 /*!
 219  * \brief Contains all the initialization information required to store a new test definition
 220  */
 221 struct ast_test_info {
 222         /*! \brief name of test, unique to category */
 223         const char *name;
 224         /*!
 225          * \brief test category
 226          *
 227          * Tests are categorized in a directory tree style hierarchy.  It is expected that
 228          * this string have both a leading and trailing forward slash ('/').
 229          */
 230         const char *category;
 231         /*! \brief optional short summary of test */
 232         const char *summary;
 233         /*! \brief optional brief detailed description of test */
 234         const char *description;
 235 };
 236
 237 #ifdef TEST_FRAMEWORK
 238 /*!
 239  * \brief Generic test callback function
 240  *
 241  * \param error buffer string for failure results
 242  *
 243  * \retval AST_TEST_PASS for pass
 244  * \retval AST_TEST_FAIL for failure
 245  */
 246 typedef enum ast_test_result_state (ast_test_cb_t)(struct ast_test_info *info,
 247         enum ast_test_command cmd, struct ast_test *test);
 248
 249 /*!
 250  * \brief unregisters a test with the test framework
 251  *
 252  * \param test callback function (required)
 253  *
 254  * \retval 0 success
 255  * \retval -1 failure
 256  */
 257 int ast_test_unregister(ast_test_cb_t *cb);
 258
 259 /*!
 260  * \brief registers a test with the test framework
 261  *
 262  * \param test callback function (required)
 263  *
 264  * \retval 0 success
 265  * \retval -1 failure
 266  */
 267 int ast_test_register(ast_test_cb_t *cb);
 268
 269 /*!
 270  * \brief Unit test debug output.
 271  * \since 12.0.0
 272  *
 273  * \param test Unit test control structure.
 274  * \param fmt printf type format string.
 275  *
 276  * \return Nothing
 277  */
 278 void ast_test_debug(struct ast_test *test, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
 279
 280 /*!
 281  * \brief update test's status during testing.
 282  *
 283  * \param test currently executing test
 284  *
 285  * \retval 0 success
 286  * \retval -1 failure
 287  */
 288 int __ast_test_status_update(const char *file, const char *func, int line, struct ast_test *test, const char *fmt, ...)
 289         __attribute__((format(printf, 5, 6)));
 290
 291 /*!
 292  * \ref __ast_test_status_update()
 293  */
 294 #define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__)
 295
 296 /*!
 297  * \brief Check a test condition, failing the test if it's not true.
 298  *
 299  * \since 12.0.0
 300  *
 301  * This macro evaluates \a condition. If the condition evaluates to true (non-zero),
 302  * nothing happens. If it evaluates to false (zero), then the failure is printed
 303  * using \ref ast_test_status_update, and the current test is ended with AST_TEST_FAIL.
 304  *
 305  * Sadly, the name 'ast_test_assert' was already taken.
 306  *
 307  * Note that since this macro returns from the current test, there must not be any
 308  * cleanup work to be done before returning. Use \ref RAII_VAR for test cleanup.
 309  *
 310  * \param test Currently executing test
 311  * \param condition Boolean condition to check.
 312  */
 313 #define ast_test_validate(test, condition)                              \
 314         do {                                                            \
 315                 if (!(condition)) {                                     \
 316                         __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (test), "Condition failed: %s\n", #condition); \
 317                         return AST_TEST_FAIL;                           \
 318                 }                                                       \
 319         } while(0)
 320
 321
 322 #endif /* TEST_FRAMEWORK */
 323 #endif /* _AST_TEST_H */