1Unity Test API 2============== 3 4[](https://travis-ci.org/ThrowTheSwitch/Unity) 5__Copyright (c) 2007 - 2017 Unity Project by Mike Karlesky, Mark VanderVoord, and Greg Williams__ 6 7Running Tests 8------------- 9 10 RUN_TEST(func, linenum) 11 12Each Test is run within the macro `RUN_TEST`. This macro performs necessary setup before the test is called and handles cleanup and result tabulation afterwards. 13 14Ignoring Tests 15-------------- 16 17There are times when a test is incomplete or not valid for some reason. At these times, TEST_IGNORE can be called. Control will immediately be returned to the caller of the test, and no failures will be returned. 18 19 TEST_IGNORE() 20 21Ignore this test and return immediately 22 23 TEST_IGNORE_MESSAGE (message) 24 25Ignore this test and return immediately. Output a message stating why the test was ignored. 26 27Aborting Tests 28-------------- 29 30There are times when a test will contain an infinite loop on error conditions, or there may be reason to escape from the test early without executing the rest of the test. A pair of macros support this functionality in Unity. The first `TEST_PROTECT` sets up the feature, and handles emergency abort cases. `TEST_ABORT` can then be used at any time within the tests to return to the last `TEST_PROTECT` call. 31 32 TEST_PROTECT() 33 34Setup and Catch macro 35 36 TEST_ABORT() 37 38Abort Test macro 39 40Example: 41 42 main() 43 { 44 if (TEST_PROTECT()) 45 { 46 MyTest(); 47 } 48 } 49 50If MyTest calls `TEST_ABORT`, program control will immediately return to `TEST_PROTECT` with a return value of zero. 51 52 53Unity Assertion Summary 54======================= 55 56Basic Validity Tests 57-------------------- 58 59 TEST_ASSERT_TRUE(condition) 60 61Evaluates whatever code is in condition and fails if it evaluates to false 62 63 TEST_ASSERT_FALSE(condition) 64 65Evaluates whatever code is in condition and fails if it evaluates to true 66 67 TEST_ASSERT(condition) 68 69Another way of calling `TEST_ASSERT_TRUE` 70 71 TEST_ASSERT_UNLESS(condition) 72 73Another way of calling `TEST_ASSERT_FALSE` 74 75 TEST_FAIL() 76 TEST_FAIL_MESSAGE(message) 77 78This test is automatically marked as a failure. The message is output stating why. 79 80Numerical Assertions: Integers 81------------------------------ 82 83 TEST_ASSERT_EQUAL_INT(expected, actual) 84 TEST_ASSERT_EQUAL_INT8(expected, actual) 85 TEST_ASSERT_EQUAL_INT16(expected, actual) 86 TEST_ASSERT_EQUAL_INT32(expected, actual) 87 TEST_ASSERT_EQUAL_INT64(expected, actual) 88 89Compare two integers for equality and display errors as signed integers. A cast will be performed 90to your natural integer size so often this can just be used. When you need to specify the exact size, 91like when comparing arrays, you can use a specific version: 92 93 TEST_ASSERT_EQUAL_UINT(expected, actual) 94 TEST_ASSERT_EQUAL_UINT8(expected, actual) 95 TEST_ASSERT_EQUAL_UINT16(expected, actual) 96 TEST_ASSERT_EQUAL_UINT32(expected, actual) 97 TEST_ASSERT_EQUAL_UINT64(expected, actual) 98 99Compare two integers for equality and display errors as unsigned integers. Like INT, there are 100variants for different sizes also. 101 102 TEST_ASSERT_EQUAL_HEX(expected, actual) 103 TEST_ASSERT_EQUAL_HEX8(expected, actual) 104 TEST_ASSERT_EQUAL_HEX16(expected, actual) 105 TEST_ASSERT_EQUAL_HEX32(expected, actual) 106 TEST_ASSERT_EQUAL_HEX64(expected, actual) 107 108Compares two integers for equality and display errors as hexadecimal. Like the other integer comparisons, 109you can specify the size... here the size will also effect how many nibbles are shown (for example, `HEX16` 110will show 4 nibbles). 111 112 TEST_ASSERT_EQUAL(expected, actual) 113 114Another way of calling TEST_ASSERT_EQUAL_INT 115 116 TEST_ASSERT_INT_WITHIN(delta, expected, actual) 117 118Asserts that the actual value is within plus or minus delta of the expected value. This also comes in 119size specific variants. 120 121 122 TEST_ASSERT_GREATER_THAN(threshold, actual) 123 124Asserts that the actual value is greater than the threshold. This also comes in size specific variants. 125 126 127 TEST_ASSERT_LESS_THAN(threshold, actual) 128 129Asserts that the actual value is less than the threshold. This also comes in size specific variants. 130 131 132Arrays 133------ 134 135 _ARRAY 136 137You can append `_ARRAY` to any of these macros to make an array comparison of that type. Here you will 138need to care a bit more about the actual size of the value being checked. You will also specify an 139additional argument which is the number of elements to compare. For example: 140 141 TEST_ASSERT_EQUAL_HEX8_ARRAY(expected, actual, elements) 142 143 _EACH_EQUAL 144 145Another array comparison option is to check that EVERY element of an array is equal to a single expected 146value. You do this by specifying the EACH_EQUAL macro. For example: 147 148 TEST_ASSERT_EACH_EQUAL_INT32(expected, actual, elements) 149 150Numerical Assertions: Bitwise 151----------------------------- 152 153 TEST_ASSERT_BITS(mask, expected, actual) 154 155Use an integer mask to specify which bits should be compared between two other integers. High bits in the mask are compared, low bits ignored. 156 157 TEST_ASSERT_BITS_HIGH(mask, actual) 158 159Use an integer mask to specify which bits should be inspected to determine if they are all set high. High bits in the mask are compared, low bits ignored. 160 161 TEST_ASSERT_BITS_LOW(mask, actual) 162 163Use an integer mask to specify which bits should be inspected to determine if they are all set low. High bits in the mask are compared, low bits ignored. 164 165 TEST_ASSERT_BIT_HIGH(bit, actual) 166 167Test a single bit and verify that it is high. The bit is specified 0-31 for a 32-bit integer. 168 169 TEST_ASSERT_BIT_LOW(bit, actual) 170 171Test a single bit and verify that it is low. The bit is specified 0-31 for a 32-bit integer. 172 173Numerical Assertions: Floats 174---------------------------- 175 176 TEST_ASSERT_FLOAT_WITHIN(delta, expected, actual) 177 178Asserts that the actual value is within plus or minus delta of the expected value. 179 180 TEST_ASSERT_EQUAL_FLOAT(expected, actual) 181 TEST_ASSERT_EQUAL_DOUBLE(expected, actual) 182 183Asserts that two floating point values are "equal" within a small % delta of the expected value. 184 185String Assertions 186----------------- 187 188 TEST_ASSERT_EQUAL_STRING(expected, actual) 189 190Compare two null-terminate strings. Fail if any character is different or if the lengths are different. 191 192 TEST_ASSERT_EQUAL_STRING_LEN(expected, actual, len) 193 194Compare two strings. Fail if any character is different, stop comparing after len characters. 195 196 TEST_ASSERT_EQUAL_STRING_MESSAGE(expected, actual, message) 197 198Compare two null-terminate strings. Fail if any character is different or if the lengths are different. Output a custom message on failure. 199 200 TEST_ASSERT_EQUAL_STRING_LEN_MESSAGE(expected, actual, len, message) 201 202Compare two strings. Fail if any character is different, stop comparing after len characters. Output a custom message on failure. 203 204Pointer Assertions 205------------------ 206 207Most pointer operations can be performed by simply using the integer comparisons above. However, a couple of special cases are added for clarity. 208 209 TEST_ASSERT_NULL(pointer) 210 211Fails if the pointer is not equal to NULL 212 213 TEST_ASSERT_NOT_NULL(pointer) 214 215Fails if the pointer is equal to NULL 216 217Memory Assertions 218----------------- 219 220 TEST_ASSERT_EQUAL_MEMORY(expected, actual, len) 221 222Compare two blocks of memory. This is a good generic assertion for types that can't be coerced into acting like 223standard types... but since it's a memory compare, you have to be careful that your data types are packed. 224 225_MESSAGE 226-------- 227 228you can append _MESSAGE to any of the macros to make them take an additional argument. This argument 229is a string that will be printed at the end of the failure strings. This is useful for specifying more 230information about the problem. 231 232
){kind=link}