1/* 2 * Copyright © 2015 Samsung Electronics Co., Ltd 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining 5 * a copy of this software and associated documentation files (the 6 * "Software"), to deal in the Software without restriction, including 7 * without limitation the rights to use, copy, modify, merge, publish, 8 * distribute, sublicense, and/or sell copies of the Software, and to 9 * permit persons to whom the Software is furnished to do so, subject to 10 * the following conditions: 11 * 12 * The above copyright notice and this permission notice (including the 13 * next paragraph) shall be included in all copies or substantial 14 * portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 19 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 20 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 21 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 23 * SOFTWARE. 24 */ 25 26/** 27@page zunitc zunitc 28 29- @ref zunitc_overview 30 - @ref zunitc_overview_return 31- @ref zunitc_execution 32 - @ref zunitc_execution_commandline 33 - @ref zunitc_execution_matching 34 - @ref zunitc_execution_wildcards 35 - @ref zunitc_execution_repeat 36 - @ref zunitc_execution_randomize 37- @ref zunitc_fixtures 38- @ref zunitc_functions 39 40@section zunitc_overview Overview 41 42A simple test framework in plain C suitable for basic unit and integration 43testing. 44 45The main rationale for creating this framework was to have a simple to use 46testing framework with tests implemented in C using common patterns and under a 47compatible license. The structure of the test code and macro use is intended to 48follow common patterns established by frameworks such as Boost Test and Google 49Test. 50 51 52To get started, one or more tests should be defined via ZUC_TEST() and/or 53ZUC_TEST_F(), which set up automatic test registration via gcc extensions. 54To actually execute tests, ZUC_RUN_TESTS() should be called. 55 56 57Tests can use several ZUC_ASSERT_* or ZUC_ASSERTG_* checks to validate 58conditions. The ZUC_ASSERT_* ones upon failure will mark the current test 59as failing and immediately execute a return. On the other hand, the 60ZUC_ASSERTG_* tests will mark the current test as failed and then execute a 61'goto' targeting the specified label. See @ref zunitc_overview_return for more 62detail. 63 64The set of fatal test checks are 65 66- ZUC_ASSERT_TRUE() 67- ZUC_ASSERT_FALSE() 68- ZUC_ASSERT_NULL() 69- ZUC_ASSERT_NOT_NULL() 70- ZUC_ASSERT_EQ() 71- ZUC_ASSERT_NE() 72- ZUC_ASSERT_LT() 73- ZUC_ASSERT_LE() 74- ZUC_ASSERT_GT() 75- ZUC_ASSERT_GE() 76- ZUC_ASSERT_STREQ() 77- ZUC_ASSERT_STRNE() 78 79and 80 81- ZUC_ASSERTG_TRUE() 82- ZUC_ASSERTG_FALSE() 83- ZUC_ASSERTG_NULL() 84- ZUC_ASSERTG_NOT_NULL() 85- ZUC_ASSERTG_EQ() 86- ZUC_ASSERTG_NE() 87- ZUC_ASSERTG_LT() 88- ZUC_ASSERTG_LE() 89- ZUC_ASSERTG_GT() 90- ZUC_ASSERTG_GE() 91- ZUC_ASSERTG_STREQ() 92- ZUC_ASSERTG_STRNE() 93 94Unconditional test values for logging and termination are 95- ZUC_SKIP() 96- ZUC_FATAL() 97 98Unconditional message logging for failure cases only is 99- ZUC_TRACEPOINT() 100 101@subsection zunitc_overview_return Test Termination and Return 102 103One key point where this framework differs from some others (especially many 104common ad hoc test programs) is that it does not use assert() nor exceptions. 105 106- does not use assert() 107- can not use throw 108 109One main implication of this is that when a check fails the current function 110will be terminated via a 'return' statement and control passed back to the 111calling function. If the check fails in an individual ZUC_TEST() or ZUC_TEST_F() 112test function then control is returned to the framework and the current test is 113deemed completed (either successfully or with failure). 114 115On the other hand, if a check fails that is being executed in a function called 116by an individual test, then control will stay in the current test. In order to 117successfully exit the current test a follow-up check needs to be done after 118calling functions that might cause a failure. 119 120@code{.c} 121... 122 123 /* Call a function that might contain ZUC_ASSERT_* use. */ 124 some_helper_function(); 125 126 /* Stop the current test if something failed. */ 127 ZUC_ASSERT_FALSE(zuc_has_failure()); 128 129 /* execution will only reach this point if no failures occurred. */ 130 131... 132@endcode 133 134Use of the ZUC_ASSERTG_*() variants can help in certain situations as check 135failure will trigger a 'goto' statement as opposed to a general 'return'. 136 137@code{.c} 138... 139 140 /* Call a function that might contain ZUC_ASSERT_* use. */ 141 some_helper_function(); 142 143 /* Stop the current test if something failed. */ 144 ZUC_ASSERTG_FALSE(zuc_has_failure(), err); 145 146 /* execution will only reach this point if no failures occurred. */ 147... 148 149err: 150 free(str_a); 151} 152... 153@endcode 154 155@section zunitc_execution Controlling Execution 156 157To control execution, the various zuc_set_* functions can be called 158before invoking ZUC_RUN_TESTS(). 159 160@subsection zunitc_execution_commandline Command-line Parameters 161 162The current implementation defers processing of command-line parameters 163to the main application hosting the testing. It is possible that a 164helper function to process certain parameters may be added. 165 166@subsection zunitc_execution_matching Matching Patterns for Tests 167 168The function zuc_set_filter() can be used to specify a pattern for 169matching or excluding tests from a run. The general form is 170 match1[:match2[:match3..n]][:-exclude1[:exclude2[:exclude3..n]]] 171 172@subsection zunitc_execution_wildcards Matching Wildcards 173 174Wildcards can be used in the match/exclude patterns and recognize the 175following two special characters: 176- '*' matches any number of characters including zero. 177- '?' matches any single character. 178 179This pattern matching is consistent with other testing frameworks and 180has been chosen in order to make it easier for developers to move 181between different testing frameworks. 182 183Calling zuc_list_tests() after zuc_set_filter() can be done to show the 184effects of the matching without needing to actually run tests. 185 186@subsection zunitc_execution_repeat Repeating Tests 187 188Setting the repeat count higher than 1 ( via zuc_set_repeat() ) will 189cause the tests to be executed several times in a row. This can be 190useful for stress testing, checking for leaks, etc. 191 192@subsection zunitc_execution_randomize Randomizing Tests 193 194Test ordering can be randomized by setting a non-zero positive value to 195zuc_set_random(). Setting it to 1 will cause the framework to pick a 196random seed based on the time. A value greater than 1 will be taken as a 197random seed itself. And setting it to 0 will disable randomization and 198allow the tests to be executed in their natural ordering. 199 200@section zunitc_fixtures Fixtures 201 202Per-suite and per-test setup and teardown fixtures can be implemented by 203defining an instance of struct zuc_fixture and using it as the first 204parameter to ZUC_TEST_F(). 205 206@section zunitc_functions Functions 207 208- ZUC_TEST() 209- ZUC_TEST_F() 210- ZUC_RUN_TESTS() 211- zuc_cleanup() 212- zuc_list_tests() 213- zuc_set_filter() 214- zuc_set_random() 215- zuc_set_spawn() 216- zuc_set_output_junit() 217- zuc_has_skip() 218- zuc_has_failure() 219 220*/ 221