tools/zunitc/doc/zunitc.dox

/*
 * Copyright © 2015 Samsung Electronics Co., Ltd
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice (including the
 * next paragraph) shall be included in all copies or substantial
 * portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/**
@page zunitc zunitc

- @ref zunitc_overview
- @ref zunitc_execution
  - @ref zunitc_execution_commandline
  - @ref zunitc_execution_matching
  - @ref zunitc_execution_wildcards
  - @ref zunitc_execution_repeat
  - @ref zunitc_execution_randomize
- @ref zunitc_fixtures
- @ref zunitc_functions

@section zunitc_overview Overview

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


To get started, one or more tests should be defined via ZUC_TEST() and/or
ZUC_TEST_F(), which set up automatic test registration via gcc extensions.
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
ZUC_ASSERTG_* tests will mark the current test as failed and then execute a
'goto' targeting the specified label.

The set of fatal test checks are

- ZUC_ASSERT_TRUE()
- ZUC_ASSERT_FALSE()
- ZUC_ASSERT_NULL()
- ZUC_ASSERT_NOT_NULL()
- ZUC_ASSERT_EQ()
- ZUC_ASSERT_NE()
- ZUC_ASSERT_LT()
- ZUC_ASSERT_LE()
- ZUC_ASSERT_GT()
- ZUC_ASSERT_GE()
- ZUC_ASSERT_STREQ()
- ZUC_ASSERT_STRNE()

and

- ZUC_ASSERTG_TRUE()
- ZUC_ASSERTG_FALSE()
- ZUC_ASSERTG_NULL()
- ZUC_ASSERTG_NOT_NULL()
- ZUC_ASSERTG_EQ()
- ZUC_ASSERTG_NE()
- ZUC_ASSERTG_LT()
- ZUC_ASSERTG_LE()
- ZUC_ASSERTG_GT()
- ZUC_ASSERTG_GE()
- ZUC_ASSERTG_STREQ()
- ZUC_ASSERTG_STRNE()

Unconditional test values for logging and termination are
- ZUC_SKIP()
- ZUC_FATAL()

Unconditional message logging for failure cases only is
- ZUC_TRACEPOINT()

@section zunitc_execution Controlling Execution

To control execution, the various zuc_set_* functions can be called
before invoking ZUC_RUN_TESTS().

@subsection zunitc_execution_commandline Commandline Parameters

The current implementation defers processing of command-line parameters
to the main application hosting the testing. It is possible that a
helper function to process certain parameters may be added.

@subsection zunitc_execution_matching Matching Patterns for Tests

The function zuc_set_filter() can be used to specify a pattern for
matching or excluding tests from a run. The general form is
 match1[:match2[:match3..n]][:-exclude1[:exclude2[:exclude3..n]]]

@subsection zunitc_execution_wildcards Matching Wildcards

Wildcards can be used in the match/exclude patterns and recognize the
following two special characters:
- '*' matches any number of characters including zero.
- '?' matches any single character.

Calling zuc_list_tests() after zuc_set_filter() can be done to show the
effects of the matching without needing to actually run tests.

@subsection zunitc_execution_repeat Repeating Tests

Setting the repeat count higher than 1 ( via zuc_set_repeat() ) will
cause the tests to be executed several times in a row. This can be
useful for stress testing, checking for leaks, etc.

@subsection zunitc_execution_randomize Randomizing Tests

Test ordering can be randomized by setting a non-zero positive value to
zuc_set_random(). Setting it to 1 will cause the framework to pick a
random seed based on the time. A value greater than 1 will be taken as a
random seed itself. And setting it to 0 will disable randomization and
allow the tests to be executed in their natural ordering.

@section zunitc_fixtures Fixtures

Per-suite and per-test setup and teardown fixtures can be implemented by
defining an instance of struct zuc_fixture and using it as the first
parameter to ZUC_TEST_F().

@section zunitc_functions Functions

- ZUC_TEST()
- ZUC_TEST_F()
- ZUC_RUN_TESTS()
- zuc_cleanup()
- zuc_list_tests()
- zuc_set_filter()
- zuc_set_random()
- zuc_set_spawn()
- zuc_set_output_tap()
- zuc_set_output_junit()
- zuc_has_skip()
- zuc_has_failure()

*/