Various updates to the unit test API.

1) It occurred to me that the difference in usage between the error ast_str and
the ast_test_update_status() usage has turned out to be a bit ambiguous in
practice.  In a lot of cases, the same message was being sent to both.
In other cases, it was only sent to one or the other.  My opinion now is that
in every case, I think it makes sense to do both; we should output it to the
CLI as well as save it off for logging purposes.

This change results in most of the changes in this diff, since it required
changes to all existing unit tests.  It also allowed for some simplifications
of unit test API implementation code.

2) Update ast_test_status_update() to include the file, function, and line
number for the code providing the update.

3) There are some formatting tweaks here and there.  Hopefully they aren't too
distracting for code review purposes.  Reviewboard's diff viewer seems to do a
pretty good job of pointing out when something is a whitespace change.

4) I moved the md5_test and sha1_test into the test_utils module.  It seemed
like a better approach since these tests are so tiny.

5) I changed the number of nodes used in heap_test_2 from 1 million to
100 thousand.  The only reason for this was to reduce the time it took
for this test to run.

6) Remove an unused function prototype that was at the bottom of utils.h.

7) Simplify test_insert() using the LIST_INSERT_SORTALPHA() macro.  The one
minor difference in behavior is that it no longer checks for a test registered
with the same name.

8) Expand the code in test_alloc() to provide specific error messages for each
failure case, to clearly inform developers if they forget to set the name,
summary, description, etc.

9) Tweak the output of the "test show registered" CLI command.  I swapped the
name and category to have the category first.  It seemed more natural since
that is the sort key.

10) Don't output the status ast_str in the "test show results" CLI command.
This is going to tend to be pretty verbose, so just leave that for the
detailed test logs (test generate results).

Review: https://reviewboard.asterisk.org/r/493/


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@245864 f38db490-d61c-443f-a65b-d21fe96a405b

2 files changed, 29 insertions, 37 deletions

diff --git a/include/asterisk/test.h b/include/asterisk/test.h
index 82610cdd4..f97df80d7 100644
--- a/include/asterisk/test.h
+++ b/include/asterisk/test.h
@@ -1,9 +1,10 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 2009, Digium, Inc.
+ * 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
@@ -23,6 +24,7 @@
  * 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_
@@ -46,7 +48,7 @@
    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_args *args
+       \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.
@@ -72,7 +74,7 @@
       .
       .
       if (fail) {                 \\ the following is just some example logic
-          ast_str_set(&args->ast_test_error_str, 0 , "an error occured because...");
+          ast_test_status_update(test, "an error occured because...");
           res = AST_RESULT_FAIL;
       } else {
           res = AST_RESULT_PASS
@@ -81,10 +83,8 @@
    }
 \endcode
 
-   Every callback function is passed an ast_test_args object which contains
-   an ast_str allowing the function to provide an optional short description of
-   what went wrong if the test failed. This is done by writing to
-   args->ast_test_error_str.
+      Details of the test execution, especially failure details, should be provided
+      by using the ast_test_status_update() function.
 
 \subsection RegisterTest Register a Test 
 
@@ -117,13 +117,13 @@
 /*! 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_args *args)
+#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_args *args)
+#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...)
@@ -142,34 +142,23 @@ enum ast_test_command {
 };
 
 /*!
- *  This struct is passed to ast_test_status_update() providing a place to push
- *  the update to. In the future this structure may expand beyond simply being
- *  a wrapper for cli args to including other status update options as well.
+ * \brief An Asterisk unit test.
+ *
+ * This is an opaque type.
  */
-struct ast_test_status_args {
-	/*! pointer to cli arg used for updating status */
-	struct ast_cli_args *cli;
-};
+struct ast_test;
 
 /*!
- * tools made available to the callback function during test execution
- */
-struct ast_test_args {
-	struct ast_str *ast_test_error_str;  /*! optional error str to describe error result */
-	struct ast_test_status_args status_update;
-};
-
-/*!
- * Contains all the initilization information required to store a new test definition
+ * \brief Contains all the initialization information required to store a new test definition
  */
 struct ast_test_info {
-	/*! name of test, unique to category */
+	/*! \brief name of test, unique to category */
 	const char *name;
-	/*! test category */
+	/*! \brief test category */
 	const char *category;
-	/*! optional short summary of test */
+	/*! \brief optional short summary of test */
 	const char *summary;
-	/*! optional brief detailed description of test */
+	/*! \brief optional brief detailed description of test */
 	const char *description;
 };
 
@@ -182,7 +171,8 @@ struct ast_test_info {
  * \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_args *args);
+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
@@ -207,13 +197,19 @@ int ast_test_register(ast_test_cb_t *cb);
 /*!
  * \brief update test's status during testing.
  *
- * \param ast_test_status_args defines everywhere the update should go.
+ * \param test currently executing test
  *
  * \retval 0 success
  * \retval -1 failure
  */
-int ast_test_status_update(struct ast_test_status_args *args, const char *fmt, ...)
-__attribute__((format(printf, 2, 3)));
+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 */
diff --git a/include/asterisk/utils.h b/include/asterisk/utils.h
index 1ea9a6085..a0208e7f2 100644
--- a/include/asterisk/utils.h
+++ b/include/asterisk/utils.h
@@ -758,8 +758,4 @@ int ast_str_to_eid(struct ast_eid *eid, const char *s);
  */
 int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
 
-/*!
- * \brief Registers util api unit tests
- */
-void ast_utils_register_tests(void);
 #endif /* _ASTERISK_UTILS_H */