[PATCH weston v2] zunitc: Clarify documentation on return behavior.
Bryce Harrington
bryce at osg.samsung.com
Fri Oct 23 13:53:57 PDT 2015
On Thu, Oct 22, 2015 at 01:31:49PM -0700, Bryce Harrington wrote:
> 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>
Pushed:
remote: I: patch #62647 updated using rev 2ffb0afecbf4dcef5899100bbd723fd4d0699c22
remote: I: 1 patch(es) updated to state Accepted.
To ssh://git.freedesktop.org/git/wayland/weston
46812b6..2ffb0af master -> master
> > ---
> > 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
> _______________________________________________
> 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