[svn-commits] dvossel: branch dvossel/test_api r234368 - /team/dvossel/test_api/include/ast...

[SVN commits to the Digium repositories]

Author: dvossel
Date: Thu Dec 10 17:37:49 2009
New Revision: 234368

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=234368
Log:
test api documentation update in test.h

Modified:
    team/dvossel/test_api/include/asterisk/test.h

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=234368&r1=234367&r2=234368
==============================================================================
--- team/dvossel/test_api/include/asterisk/test.h (original)
+++ team/dvossel/test_api/include/asterisk/test.h Thu Dec 10 17:37:49 2009
@@ -19,14 +19,50 @@
 /*!
  * \file
  * \author David Vossel <dvossel at digium.com>
- * \brief Test Framework api
+ * \brief Test Framework API
  */
-
 
 #define AST_TEST_FRAMEWORK //todohere move to a better place
 
+/* Macros used for for test API
 
-/* Macros used for for test API */
+How to use the test API
+
+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
+	\test code
+	.
+	.
+	.
+	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.
+
+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
+
+Tests can optionally be unregestered as well by using the AST_TEST_REGISTER macro.
+
+AST_TEST_REGISTER(sample_test_cb); 
+
+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
+
+*/
 #ifdef AST_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)