[PATCH weston] zunitc: Clarify documentation on return behavior.
Jon A. Cruz
jonc at osg.samsung.com
Wed Oct 21 16:59:28 PDT 2015
* Clarify documentation on ZUC_ASSERT_* behavior in regards to return
vs. abort()
* Added overview section on return behavior.
* Fixed spelling
* Removed outdated reference to tap function.
Signed-off-by: Jon A. Cruz <jonc at osg.samsung.com>
---
tools/zunitc/doc/zunitc.dox | 80 ++++++++++++++++++++++++++++++----
tools/zunitc/inc/zunitc/zunitc.h | 94 +++++++++++++++++++++++++++-------------
2 files changed, 135 insertions(+), 39 deletions(-)
diff --git a/tools/zunitc/doc/zunitc.dox b/tools/zunitc/doc/zunitc.dox
index cef6c34..31a1ced 100644
--- a/tools/zunitc/doc/zunitc.dox
+++ b/tools/zunitc/doc/zunitc.dox
@@ -27,6 +27,7 @@
@page zunitc zunitc
- @ref zunitc_overview
+ - @ref zunitc_overview_return
- @ref zunitc_execution
- @ref zunitc_execution_commandline
- @ref zunitc_execution_matching
@@ -38,12 +39,14 @@
@section zunitc_overview Overview
-A simple test framework in plain C suitable for basic unit and integration testing.
+A simple test framework in plain C suitable for basic unit and integration
+testing.
-The main rationale for creating this framework was to have a simple to use testing
-framework with tests implemented in C using common patterns and under a
+The main rationale for creating this framework was to have a simple to use
+testing framework with tests implemented in C using common patterns and under a
compatible license. The structure of the test code and macro use is intended to
-follow common patterns established by frameworks such as Boost Test and Google Test.
+follow common patterns established by frameworks such as Boost Test and Google
+Test.
To get started, one or more tests should be defined via ZUC_TEST() and/or
@@ -53,9 +56,10 @@ To actually execute tests, ZUC_RUN_TESTS() should be called.
Tests can use several ZUC_ASSERT_* or ZUC_ASSERTG_* checks to validate
conditions. The ZUC_ASSERT_* ones upon failure will mark the current test
-as failing and immediatly execute a return. On the other hand, the
+as failing and immediately execute a return. On the other hand, the
ZUC_ASSERTG_* tests will mark the current test as failed and then execute a
-'goto' targeting the specified label.
+'goto' targeting the specified label. See @ref zunitc_overview_return for more
+detail.
The set of fatal test checks are
@@ -94,12 +98,69 @@ Unconditional test values for logging and termination are
Unconditional message logging for failure cases only is
- ZUC_TRACEPOINT()
+ at subsection zunitc_overview_return Test Termination and Return
+
+One key point where this framework differs from some others (especially many
+common more ad hoc test programs) is that it does not use assert() nor
+exceptions. (The latter is blocked by being C based, of course. However users
+might have habits expecting exception-like behavior from experience with other
+frameworks)
+
+- does not use assert()
+- can not use throw
+
+One main implication of this is that when a check fails the current function
+will be terminated via a 'return' statement and control passed back to the
+calling function. If the check fails in an individual ZUC_TEST() or ZUC_TEST_F()
+test function then control is returned to the framework and the current test is
+deemed completed (either successfully or with failure).
+
+On the other hand, if a check fails that is being executed in a function called
+by an individual test, then control will stay in the current test. In order to
+successfully exit the current test a follow-up check needs to be done after
+calling functions that might cause a failure.
+
+ at code{.c}
+...
+
+ /* Call a function that might contain ZUC_ASSERT_* use. */
+ some_helper_function();
+
+ /* Stop the current test if something failed. */
+ ZUC_ASSERT_FALSE(zuc_has_failure());
+
+ /* execution will only reach this point if no failures occurred. */
+
+...
+ at endcode
+
+Use of the ZUC_ASSERTG_*() variants can help in certain situations as check
+failure will trigger a 'goto' statement as opposed to a general 'return'.
+
+ at code{.c}
+...
+
+ /* Call a function that might contain ZUC_ASSERT_* use. */
+ some_helper_function();
+
+ /* Stop the current test if something failed. */
+ ZUC_ASSERTG_FALSE(zuc_has_failure(), err);
+
+ /* execution will only reach this point if no failures occurred. */
+...
+
+err:
+ free(str_a);
+}
+...
+ at endcode
+
@section zunitc_execution Controlling Execution
To control execution, the various zuc_set_* functions can be called
before invoking ZUC_RUN_TESTS().
- at subsection zunitc_execution_commandline Commandline Parameters
+ at subsection zunitc_execution_commandline Command-line Parameters
The current implementation defers processing of command-line parameters
to the main application hosting the testing. It is possible that a
@@ -118,6 +179,10 @@ following two special characters:
- '*' matches any number of characters including zero.
- '?' matches any single character.
+This pattern matching is consistent with other testing frameworks and
+had been chosen in order to make it easier for developers to move
+between different testing frameworks.
+
Calling zuc_list_tests() after zuc_set_filter() can be done to show the
effects of the matching without needing to actually run tests.
@@ -151,7 +216,6 @@ parameter to ZUC_TEST_F().
- zuc_set_filter()
- zuc_set_random()
- zuc_set_spawn()
-- zuc_set_output_tap()
- zuc_set_output_junit()
- zuc_has_skip()
- zuc_has_failure()
diff --git a/tools/zunitc/inc/zunitc/zunitc.h b/tools/zunitc/inc/zunitc/zunitc.h
index d8c3cb0..d04b599 100644
--- a/tools/zunitc/inc/zunitc/zunitc.h
+++ b/tools/zunitc/inc/zunitc/zunitc.h
@@ -299,6 +299,7 @@ zuc_set_output_junit(bool enable);
* @return true if there is currently a test executing and it has
* encountered any skips.
* @see zuc_has_failure
+ * @see ZUC_SKIP()
*/
bool
zuc_has_skip(void);
@@ -314,7 +315,10 @@ bool
zuc_has_failure(void);
/**
- * Terminates the current test without marking it as failed.
+ * Marks the running test as skipped without marking it as failed, and returns
+ * from the current function.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param message the message to log as to why the test has been skipped.
*/
@@ -326,7 +330,9 @@ zuc_has_failure(void);
while (0)
/**
- * Terminates the current test and marks it as failed.
+ * Marks the running test as failed and returns from the current function.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param message the message to log as to why the test has failed.
*/
@@ -395,7 +401,9 @@ zuc_has_failure(void);
/**
* Verifies that the specified expression is true, marks the test as failed
- * and terminates the test if it is not.
+ * and exits the current function via 'return' if it is not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param condition the expression that is expected to be true.
* @note it is far better to use a more specific check when possible
@@ -407,7 +415,9 @@ zuc_has_failure(void);
/**
* Verifies that the specified expression is false, marks the test as
- * failed and terminates the test if it is not.
+ * failed and exits the current function via 'return' if it is not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param condition the expression that is expected to be false.
* @note it is far better to use a more specific check when possible
@@ -419,7 +429,9 @@ zuc_has_failure(void);
/**
* Verifies that the specified expression is NULL, marks the test as failed
- * and terminates the test if it is not.
+ * and exits the current function via 'return' if it is not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param condition the expression that is expected to be a NULL pointer.
* @see ZUC_ASSERTG_NULL()
@@ -429,7 +441,9 @@ zuc_has_failure(void);
/**
* Verifies that the specified expression is non-NULL, marks the test as
- * failed and terminates the test if it is not.
+ * failed and exits the current function via 'return' if it is not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param condition the expression that is expected to be a non-NULL pointer.
* @see ZUC_ASSERTG_NOT_NULL()
@@ -439,7 +453,9 @@ zuc_has_failure(void);
/**
* Verifies that the values of the specified expressions match, marks the
- * test as failed and terminates the test if they do not.
+ * test as failed and exits the current function via 'return' if they do not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param expected the value the result should hold.
* @param actual the actual value seen in testing.
@@ -450,7 +466,9 @@ zuc_has_failure(void);
/**
* Verifies that the values of the specified expressions differ, marks the
- * test as failed and terminates the test if they do not.
+ * test as failed and exits the current function via 'return' if they do not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param expected the value the result should not hold.
* @param actual the actual value seen in testing.
@@ -461,8 +479,10 @@ zuc_has_failure(void);
/**
* Verifies that the value of the first expression is less than the value
- * of the second expression, marks the test as failed and terminates the
- * test if it is not.
+ * of the second expression, marks the test as failed and exits the current
+ * function via 'return' if it is not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param lesser the expression whose value should be lesser than the other.
* @param greater the expression whose value should be greater than the other.
@@ -474,7 +494,9 @@ zuc_has_failure(void);
/**
* Verifies that the value of the first expression is less than or equal
* to the value of the second expression, marks the test as failed and
- * terminates the test if it is not.
+ * exits the current function via 'return' if it is not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param lesser the expression whose value should be lesser than or equal to
* the other.
@@ -487,8 +509,10 @@ zuc_has_failure(void);
/**
* Verifies that the value of the first expression is greater than the
- * value of the second expression, marks the test as failed and terminates
- * the test if it is not.
+ * value of the second expression, marks the test as failed and exits the
+ * current function via 'return' if it is not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param greater the expression whose value should be greater than the other.
* @param lesser the expression whose value should be lesser than the other.
@@ -499,8 +523,10 @@ zuc_has_failure(void);
/**
* Verifies that the value of the first expression is greater than or equal
- * to the value of the second expression, marks the test as failed and
- * terminates the test if it is not.
+ * to the value of the second expression, marks the test as failed and exits
+ * the current function via 'return' if it is not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param greater the expression whose value should be greater than or equal to
* the other.
@@ -514,7 +540,9 @@ zuc_has_failure(void);
/**
* Verifies that the values of the specified expressions match when
* compared as null-terminated C-style strings, marks the test as failed
- * and terminates the test if they do not.
+ * and exits the current function via 'return' if they do not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param expected the value the result should hold.
* @param actual the actual value seen in testing.
@@ -526,7 +554,9 @@ zuc_has_failure(void);
/**
* Verifies that the values of the specified expressions differ when
* compared as null-terminated C-style strings, marks the test as failed
- * and terminates the test if they do not.
+ * and exits the current function via 'return' if they do not.
+ *
+ * For details on return and test termination see @ref zunitc_overview_return.
*
* @param expected the value the result should not hold.
* @param actual the actual value seen in testing.
@@ -537,7 +567,7 @@ zuc_has_failure(void);
/**
* Verifies that the specified expression is true, marks the test as failed
- * and terminates the test via a 'goto' if it is not.
+ * and interrupts the current execution via a 'goto' if it is not.
*
* @param condition the expression that is expected to be true.
* @note it is far better to use a more specific check when possible
@@ -550,7 +580,7 @@ zuc_has_failure(void);
/**
* Verifies that the specified expression is false, marks the test as
- * failed and terminates the test via a 'goto' if it is not.
+ * failed and interrupts the current execution via a 'goto' if it is not.
*
* @param condition the expression that is expected to be false.
* @note it is far better to use a more specific check when possible
@@ -563,7 +593,7 @@ zuc_has_failure(void);
/**
* Verifies that the specified expression is NULL, marks the test as failed
- * and terminates the test via a 'goto' if it is not.
+ * and interrupts the current execution via a 'goto' if it is not.
*
* @param condition the expression that is expected to be a NULL pointer.
* @param label the target for 'goto' if the assertion fails.
@@ -574,7 +604,7 @@ zuc_has_failure(void);
/**
* Verifies that the specified expression is non-NULL, marks the test as
- * failed and terminates the test via a 'goto' if it is not.
+ * failed and interrupts the current execution via a 'goto' if it is not.
*
* @param condition the expression that is expected to be a non-NULL pointer.
* @param label the target for 'goto' if the assertion fails.
@@ -585,7 +615,8 @@ zuc_has_failure(void);
/**
* Verifies that the values of the specified expressions match, marks the
- * test as failed and terminates the test via a 'goto' if they do not.
+ * test as failed and interrupts the current execution via a 'goto' if they
+ * do not.
*
* @param expected the value the result should hold.
* @param actual the actual value seen in testing.
@@ -597,7 +628,8 @@ zuc_has_failure(void);
/**
* Verifies that the values of the specified expressions differ, marks the
- * test as failed and terminates the test via a 'goto' if they do not.
+ * test as failed and interrupts the current execution via a 'goto' if they
+ * do not.
*
* @param expected the value the result should not hold.
* @param actual the actual value seen in testing.
@@ -609,8 +641,8 @@ zuc_has_failure(void);
/**
* Verifies that the value of the first expression is less than the value
- * of the second expression, marks the test as failed and terminates the
- * test if it is not.
+ * of the second expression, marks the test as failed and interrupts the
+ * current execution via a 'goto' if it is not.
*
* @param lesser the expression whose value should be lesser than the other.
* @param greater the expression whose value should be greater than the other.
@@ -623,7 +655,7 @@ zuc_has_failure(void);
/**
* Verifies that the value of the first expression is less than or equal
* to the value of the second expression, marks the test as failed and
- * terminates the test via a 'goto' if it is not.
+ * interrupts the current execution via a 'goto' if it is not.
*
* @param lesser the expression whose value should be lesser than or equal to
* the other.
@@ -637,8 +669,8 @@ zuc_has_failure(void);
/**
* Verifies that the value of the first expression is greater than the
- * value of the second expression, marks the test as failed and terminates
- * the test if it is not.
+ * value of the second expression, marks the test as failed and interrupts the
+ * current execution via a 'goto' if it is not.
*
* @param greater the expression whose value should be greater than the other.
* @param lesser the expression whose value should be lesser than the other.
@@ -651,7 +683,7 @@ zuc_has_failure(void);
/**
* Verifies that the value of the first expression is greater than or equal
* to the value of the second expression, marks the test as failed and
- * terminates the test via a 'goto' if it is not.
+ * interrupts the current execution via a 'goto' if it is not.
*
* @param greater the expression whose value should be greater than or equal to
* the other.
@@ -666,7 +698,7 @@ zuc_has_failure(void);
/**
* Verifies that the values of the specified expressions match when
* compared as null-terminated C-style strings, marks the test as failed
- * and terminates the test via a 'goto' if they do not.
+ * and interrupts the current execution via a 'goto' if they do not.
*
* @param expected the value the result should hold.
* @param actual the actual value seen in testing.
@@ -679,7 +711,7 @@ zuc_has_failure(void);
/**
* Verifies that the values of the specified expressions differ when
* compared as null-terminated C-style strings, marks the test as failed
- * and terminates the test via a 'goto' if they do not.
+ * and interrupts the current execution via a 'goto' if they do not.
*
* @param expected the value the result should not hold.
* @param actual the actual value seen in testing.
--
2.1.4
More information about the wayland-devel
mailing list