[PATCH weston] zunitc: Clarify documentation on return behavior.

Bryce Harrington bryce at osg.samsung.com
Wed Oct 21 20:05:08 PDT 2015


On Wed, Oct 21, 2015 at 04:59:28PM -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.
> 
> Signed-off-by: Jon A. Cruz <jonc at osg.samsung.com>

Reviewed-by: Bryce Harrington <bryce at osg.samsung.com>

A few grammar suggestions below, nothing too important though.

> ---
>  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

'more' is redundant

> +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)

Pretty sure you can drop this parenthetical...

> +- 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

s/had/has/

> +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

Bryce

> _______________________________________________
> 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