[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