diff options
author | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2010-06-25 18:58:37 +0000 |
---|---|---|
committer | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2010-06-25 18:58:37 +0000 |
commit | a3a4d3061dc9bbfae8f387fe9295a1cbe94db748 (patch) | |
tree | af460717bd24b7267eca56910c9dae1e9d8d1bc3 /include/asterisk | |
parent | af204cb6e6ccd0702d6da0ab960f3222d9590091 (diff) |
Backport unit test API from trunk.
Also, update existing test modules that were already in this branch but had
been converted to the unit test API in trunk.
Review: https://reviewboard.asterisk.org/r/748/
git-svn-id: http://svn.digium.com/svn/asterisk/branches/1.6.2@272531 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to 'include/asterisk')
-rw-r--r-- | include/asterisk/_private.h | 1 | ||||
-rw-r--r-- | include/asterisk/test.h | 215 |
2 files changed, 216 insertions, 0 deletions
diff --git a/include/asterisk/_private.h b/include/asterisk/_private.h index b630375fc..eb3950a6b 100644 --- a/include/asterisk/_private.h +++ b/include/asterisk/_private.h @@ -42,6 +42,7 @@ int ast_timing_init(void); /*!< Provided by timing.c */ int ast_indications_init(void); /*!< Provided by indications.c */ int ast_indications_reload(void);/*!< Provided by indications.c */ int ast_ssl_init(void); /*!< Porvided by ssl.c */ +int ast_test_init(void); /*!< Provided by test.c */ /*! * \brief Reload asterisk modules. diff --git a/include/asterisk/test.h b/include/asterisk/test.h new file mode 100644 index 000000000..f97df80d7 --- /dev/null +++ b/include/asterisk/test.h @@ -0,0 +1,215 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2009-2010, Digium, Inc. + * + * David Vossel <dvossel@digium.com> + * Russell Bryant <russell@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! + * \file + * \brief Test Framework API + * + * For an overview on how to use the test API, see \ref AstUnitTestAPI + * + * \author David Vossel <dvossel@digium.com> + * \author Russell Bryant <russell@digium.com> + */ + +#ifndef _AST_TEST_H_ +#define _AST_TEST_H_ + +#ifdef TEST_FRAMEWORK +#include "asterisk/cli.h" +#include "asterisk/strings.h" +#endif + +/*! + +\page AstUnitTestAPI Asterisk Unit Test API + +\section UnitTestAPIUsage How to Use the Unit Test API + +\subsection DefineTest Define a Test + + Create a callback function for the test using the AST_TEST_DEFINE macro. + + Each defined test has three arguments avaliable to it's test code. + \param struct ast_test_info *info + \param enum ast_test_command cmd + \param struct ast_test *test + + While these arguments are not visible they are passed to every test function + defined using the AST_TEST_DEFINE macro. + + Below is an example of how to define and write a test function. + +\code + AST_TEST_DEFINE(sample_test_cb) \\The name of the callback function + { \\The the function's body + switch (cmd) { + case TEST_INIT: + info->name = "sample_test"; + info->category = "main/test/"; + info->summary = "sample test for example purpose"; + info->description = "This demonstrates how to initialize a test function"; + + return AST_TEST_NOT_RUN; + case TEST_EXECUTE: + break; + } + \test code + . + . + . + if (fail) { \\ the following is just some example logic + ast_test_status_update(test, "an error occured because..."); + res = AST_RESULT_FAIL; + } else { + res = AST_RESULT_PASS + } + return res; \\ result must be of type enum ast_test_result_state + } +\endcode + + Details of the test execution, especially failure details, should be provided + by using the ast_test_status_update() function. + +\subsection RegisterTest Register a Test + + Register the test using the AST_TEST_REGISTER macro. + + AST_TEST_REGISTER uses the callback function to retrieve all the information + pertaining to a test, so the callback function is the only argument required + for registering a test. + + AST_TEST_REGISTER(sample_test_cb); \\ Test callback function defined by AST_TEST_DEFINE + + Tests are unregestered by using the AST_TEST_UNREGISTER macro. + + AST_TEST_UNREGISTER(sample_test_cb); \\ Remove a registered test by callback function + +\subsection ExecuteTest Execute a Test + + Execute and generate test results via CLI commands + + CLI Examples: +\code + 'test show registered all' will show every registered test. + 'test execute all' will execute every registered test. + 'test show results all' will show detailed results for ever executed test + 'test generate results xml' will generate a test report in xml format + 'test generate results txt' will generate a test report in txt format +\endcode +*/ + +/*! Macros used for defining and registering a test */ +#ifdef TEST_FRAMEWORK + +#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) +#define AST_TEST_REGISTER(cb) ast_test_register(cb) +#define AST_TEST_UNREGISTER(cb) ast_test_unregister(cb) + +#else + +#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) +#define AST_TEST_REGISTER(cb) +#define AST_TEST_UNREGISTER(cb) +#define ast_test_status_update(a,b,c...) + +#endif + +enum ast_test_result_state { + AST_TEST_NOT_RUN, + AST_TEST_PASS, + AST_TEST_FAIL, +}; + +enum ast_test_command { + TEST_INIT, + TEST_EXECUTE, +}; + +/*! + * \brief An Asterisk unit test. + * + * This is an opaque type. + */ +struct ast_test; + +/*! + * \brief Contains all the initialization information required to store a new test definition + */ +struct ast_test_info { + /*! \brief name of test, unique to category */ + const char *name; + /*! \brief test category */ + const char *category; + /*! \brief optional short summary of test */ + const char *summary; + /*! \brief optional brief detailed description of test */ + const char *description; +}; + +#ifdef TEST_FRAMEWORK +/*! + * \brief Generic test callback function + * + * \param error buffer string for failure results + * + * \retval AST_TEST_PASS for pass + * \retval AST_TEST_FAIL for failure + */ +typedef enum ast_test_result_state (ast_test_cb_t)(struct ast_test_info *info, + enum ast_test_command cmd, struct ast_test *test); + +/*! + * \brief unregisters a test with the test framework + * + * \param test callback function (required) + * + * \retval 0 success + * \retval -1 failure + */ +int ast_test_unregister(ast_test_cb_t *cb); + +/*! + * \brief registers a test with the test framework + * + * \param test callback function (required) + * + * \retval 0 success + * \retval -1 failure + */ +int ast_test_register(ast_test_cb_t *cb); + +/*! + * \brief update test's status during testing. + * + * \param test currently executing test + * + * \retval 0 success + * \retval -1 failure + */ +int __ast_test_status_update(const char *file, const char *func, int line, + struct ast_test *test, const char *fmt, ...) + __attribute__((format(printf, 5, 6))); + +/*! + * \ref __ast_test_status_update() + */ +#define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__) + +#endif /* TEST_FRAMEWORK */ +#endif /* _AST_TEST_H */ |