[asterisk-commits] dvossel: branch dvossel/test_api r234614 - in /team/dvossel/test_api: include...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Mon Dec 14 10:38:58 CST 2009
Author: dvossel
Date: Mon Dec 14 10:38:54 2009
New Revision: 234614
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=234614
Log:
updated test framework documentation
Modified:
team/dvossel/test_api/include/asterisk/test.h
team/dvossel/test_api/main/test.c
Modified: team/dvossel/test_api/include/asterisk/test.h
URL: http://svnview.digium.com/svn/asterisk/team/dvossel/test_api/include/asterisk/test.h?view=diff&rev=234614&r1=234613&r2=234614
==============================================================================
--- team/dvossel/test_api/include/asterisk/test.h (original)
+++ team/dvossel/test_api/include/asterisk/test.h Mon Dec 14 10:38:54 2009
@@ -22,14 +22,13 @@
* \brief Test Framework API
*/
-/* Macros used for for test API
+/* How to use the test API
-How to use the test API
+1. DEFINE TEST: Create a callback function for the test
+ using the AST_TEST_DEFINE macro.
-1. DEFINE TEST: Create a callback function for the test using the AST_TEST_DEFINE macro.
-
-AST_TEST_DEFINE(sample_test_cb, \\<--- The first argument is the name of the callback function
-{ \\<--- The second argument is the functions body
+AST_TEST_DEFINE(sample_test_cb, \\The first argument is the name of the callback function
+{ \\The second argument is the function's body
\test code
.
.
@@ -37,30 +36,33 @@
return res ? AST_RESULT_FAIL : AST_RESULT_PASS;
})
-Every callback function is passed a char buffer, errbuf, which allows
-the function to provide an optional short discription of what when wrong
-if the test failed.
+Every callback function is passed a char buffer which allows
+the function to provide an optional short description of
+what went wrong if the test failed.
2. REGISTER TEST: Register the test using the AST_TEST_REGISTER macro.
+AST_TEST_REGISTER("sample_test", \\ Test's Name
+ "main/test", \\ Test's Catagory
+ "this is sample test", \\ Brief summary of test
+ "Sample test designed for test purposes", \\ Verbose discription of test
+ sample_test_cb); \\ Test callback function defined by AST_TEST_DEFINE
-AST_TEST_REGISTER("sample_test", \\<--- Test's Name
- "main/test", \\<--- Test's Catagory
- "this is sample test", \\<--- Brief summary of test
- "Sample test designed for test purposes", \\<--- Verbose discription of test
- sample_test_cb); \\<--- Test callback function defined by AST_TEST_DEFINE
+Tests are unregestered by using the AST_TEST_UNREGISTER macro.
-Tests can optionally be unregestered as well by using the AST_TEST_REGISTER macro.
-
-AST_TEST_REGISTER(sample_test_cb);
+AST_TEST_REGISTER(sample_test_cb); \\ Test callback function to match registered test
3. EXECUTE: Execute and generate test results via CLI commands
-'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
+CLI Examples:
+'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
+*/
-*/
+/*! Macros used for defining and registering a test */
#ifdef TEST_FRAMEWORK
#define AST_TEST_DEFINE(hdr, body) int hdr(char *errbuf, int len); int hdr(char *errbuf, int len) body
#define AST_TEST_REGISTER(name, cat, sum, des, cb) ast_test_register(name, cat, sum, des, cb)
@@ -79,22 +81,40 @@
/*!
* \brief Generic test callback function
*
- * \param error buffer on failure
+ * \param error buffer for failure results
* \param length of error buffer
*
- * \return 0 for pass, 1 for failure
+ * \return AST_TEST_PASS for pass, AST_TEST_FAIL for failure
*/
typedef int (ast_test_cb_t)(char *errbuf, int len);
/*!
* \brief Initializes test framework.
*
- * \return 0 on success, 1 on failure.
+ * \return 0 on success, -1 on failure.
*/
int ast_test_init(void);
+/*!
+ * \brief registers a test with the test framework
+ *
+ * \param name of test (required)
+ * \param test catagory (required)
+ * \param test summary (optional)
+ * \param test description (optional)
+ * \param test callback function (required)
+ *
+ * \return 0 for pass, -1 for failure
+ */
int ast_test_register(const char *name, const char *catagory, const char *summary, const char *description, ast_test_cb_t *cb);
+/*!
+ * \brief unregisters a test with the test framework
+ *
+ * \param test callback function (required)
+ *
+ * \return 0 for pass, -1 for failure
+ */
int ast_test_unregister(ast_test_cb_t *cb);
/*!
@@ -121,28 +141,14 @@
* \param path to xml file to generate. (optional)
* \param path to txt file to generate, (optional)
*
- * \return 0 if results were generated, 1 if error
+ * \return 0 if results were generated, -1 if error
*
* \note This function has three modes of operation.
- * 1. Given both a name and catagory results will be generated for that single test.
- * 2. Given only a catagory results for every test within the catagory will be generated
- * 3. If given no name or catagory results for every registered test will be generated.
+ * 1. When given both a name and catagory, results will be generated for that single test.
+ * 2. When given only a catagory, results for every test within the catagory will be generated.
+ * 3. When given no name or catagory, results for every registered test will be generated.
*
- * In order for the results to be generated, an xml and or txt file path must be provided
- *
+ * In order for the results to be generated, an xml and or txt file path must be provided.
*/
int ast_test_generate_results(const char *name, const char *catagory, const char *xml_path, const char *txt_path);
-
-
#endif
-
-
-
-
-
-
-
-
-
-
-
Modified: team/dvossel/test_api/main/test.c
URL: http://svnview.digium.com/svn/asterisk/team/dvossel/test_api/main/test.c?view=diff&rev=234614&r1=234613&r2=234614
==============================================================================
--- team/dvossel/test_api/main/test.c (original)
+++ team/dvossel/test_api/main/test.c Mon Dec 14 10:38:54 2009
@@ -18,7 +18,7 @@
/*! \file
*
- * \brief Internal Test Framework
+ * \brief Unit Test Framework
*
* \author David Vossel <dvossel at digium.com>
*/
@@ -64,7 +64,7 @@
char *catagory; /*! test catagory */
char *summary; /*! optional short summary of test */
char *description; /*! optional brief detailed description of test */
- struct ast_test_result result; /*! stores the last ran result */
+ struct ast_test_result result; /*! stores the latest results */
ast_test_cb_t *cb; /*! test call back function */
AST_LIST_ENTRY(ast_test) entry;
};
@@ -87,7 +87,6 @@
static struct ast_test *test_free(struct ast_test *test);
static int test_insert(struct ast_test *test);
static struct ast_test *test_remove(ast_test_cb_t *cb);
-/*static int test_generate_xml(void);*/
int ast_test_register(const char *name, const char *catagory, const char *summary, const char *description, ast_test_cb_t *cb)
{
@@ -127,6 +126,7 @@
return 0;
}
+/*! \brief executes a single test, storing the results in the test->result structure. */
static void __test_execute(struct ast_test *test)
{
struct timeval begin;
More information about the asterisk-commits
mailing list