[PATCH weston v2] zunitc: Clarify documentation on return behavior.
Bryce Harrington
bryce at osg.samsung.com
Thu Oct 22 13:31:49 PDT 2015
On Thu, Oct 22, 2015 at 01:25:54PM -0700, Jon A. Cruz wrote:
> * 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.
>
> Changes since v1:
>
> * Incorporated grammatical feedback.
>
> Signed-off-by: Jon A. Cruz <jonc at osg.samsung.com>
Reviewed-by: Bryce Harrington <bryce at osg.samsung.com>
> ---
> tools/zunitc/doc/zunitc.dox | 77 ++++++++++++++++++++++++++++----
> tools/zunitc/inc/zunitc/zunitc.h | 94 +++++++++++++++++++++++++++-------------
> 2 files changed, 132 insertions(+), 39 deletions(-)
>
> diff --git a/tools/zunitc/doc/zunitc.dox b/tools/zunitc/doc/zunitc.dox
> index cef6c34..6fc6858 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,66 @@ 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 ad hoc test programs) is that it does not use assert() nor exceptions.
> +
> +- 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 +176,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
> +has 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 +213,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
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list