1Unity Test API 2============== 3 4[](https://travis-ci.org/ThrowTheSwitch/Unity) 5__Copyright (c) 2007 - 2019 Unity Project by Mike Karlesky, Mark VanderVoord, and Greg Williams__ 6 7Getting Started 8=============== 9The [docs](docs/) folder contains a [getting started guide](docs/UnityGettingStartedGuide.md) 10and much more tips about using Unity. 11 12Unity Assertion Summary 13======================= 14For the full list, see [UnityAssertionsReference.md](docs/UnityAssertionsReference.md). 15 16Basic Validity Tests 17-------------------- 18 19 TEST_ASSERT_TRUE(condition) 20 21Evaluates whatever code is in condition and fails if it evaluates to false 22 23 TEST_ASSERT_FALSE(condition) 24 25Evaluates whatever code is in condition and fails if it evaluates to true 26 27 TEST_ASSERT(condition) 28 29Another way of calling `TEST_ASSERT_TRUE` 30 31 TEST_ASSERT_UNLESS(condition) 32 33Another way of calling `TEST_ASSERT_FALSE` 34 35 TEST_FAIL() 36 TEST_FAIL_MESSAGE(message) 37 38This test is automatically marked as a failure. The message is output stating why. 39 40Numerical Assertions: Integers 41------------------------------ 42 43 TEST_ASSERT_EQUAL_INT(expected, actual) 44 TEST_ASSERT_EQUAL_INT8(expected, actual) 45 TEST_ASSERT_EQUAL_INT16(expected, actual) 46 TEST_ASSERT_EQUAL_INT32(expected, actual) 47 TEST_ASSERT_EQUAL_INT64(expected, actual) 48 49Compare two integers for equality and display errors as signed integers. A cast will be performed 50to your natural integer size so often this can just be used. When you need to specify the exact size, 51like when comparing arrays, you can use a specific version: 52 53 TEST_ASSERT_EQUAL_UINT(expected, actual) 54 TEST_ASSERT_EQUAL_UINT8(expected, actual) 55 TEST_ASSERT_EQUAL_UINT16(expected, actual) 56 TEST_ASSERT_EQUAL_UINT32(expected, actual) 57 TEST_ASSERT_EQUAL_UINT64(expected, actual) 58 59Compare two integers for equality and display errors as unsigned integers. Like INT, there are 60variants for different sizes also. 61 62 TEST_ASSERT_EQUAL_HEX(expected, actual) 63 TEST_ASSERT_EQUAL_HEX8(expected, actual) 64 TEST_ASSERT_EQUAL_HEX16(expected, actual) 65 TEST_ASSERT_EQUAL_HEX32(expected, actual) 66 TEST_ASSERT_EQUAL_HEX64(expected, actual) 67 68Compares two integers for equality and display errors as hexadecimal. Like the other integer comparisons, 69you can specify the size... here the size will also effect how many nibbles are shown (for example, `HEX16` 70will show 4 nibbles). 71 72 TEST_ASSERT_EQUAL(expected, actual) 73 74Another way of calling TEST_ASSERT_EQUAL_INT 75 76 TEST_ASSERT_INT_WITHIN(delta, expected, actual) 77 78Asserts that the actual value is within plus or minus delta of the expected value. This also comes in 79size specific variants. 80 81 82 TEST_ASSERT_GREATER_THAN(threshold, actual) 83 84Asserts that the actual value is greater than the threshold. This also comes in size specific variants. 85 86 87 TEST_ASSERT_LESS_THAN(threshold, actual) 88 89Asserts that the actual value is less than the threshold. This also comes in size specific variants. 90 91 92Arrays 93------ 94 95 _ARRAY 96 97You can append `_ARRAY` to any of these macros to make an array comparison of that type. Here you will 98need to care a bit more about the actual size of the value being checked. You will also specify an 99additional argument which is the number of elements to compare. For example: 100 101 TEST_ASSERT_EQUAL_HEX8_ARRAY(expected, actual, elements) 102 103 _EACH_EQUAL 104 105Another array comparison option is to check that EVERY element of an array is equal to a single expected 106value. You do this by specifying the EACH_EQUAL macro. For example: 107 108 TEST_ASSERT_EACH_EQUAL_INT32(expected, actual, elements) 109 110Numerical Assertions: Bitwise 111----------------------------- 112 113 TEST_ASSERT_BITS(mask, expected, actual) 114 115Use an integer mask to specify which bits should be compared between two other integers. High bits in the mask are compared, low bits ignored. 116 117 TEST_ASSERT_BITS_HIGH(mask, actual) 118 119Use 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. 120 121 TEST_ASSERT_BITS_LOW(mask, actual) 122 123Use 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. 124 125 TEST_ASSERT_BIT_HIGH(bit, actual) 126 127Test a single bit and verify that it is high. The bit is specified 0-31 for a 32-bit integer. 128 129 TEST_ASSERT_BIT_LOW(bit, actual) 130 131Test a single bit and verify that it is low. The bit is specified 0-31 for a 32-bit integer. 132 133Numerical Assertions: Floats 134---------------------------- 135 136 TEST_ASSERT_FLOAT_WITHIN(delta, expected, actual) 137 138Asserts that the actual value is within plus or minus delta of the expected value. 139 140 TEST_ASSERT_EQUAL_FLOAT(expected, actual) 141 TEST_ASSERT_EQUAL_DOUBLE(expected, actual) 142 143Asserts that two floating point values are "equal" within a small % delta of the expected value. 144 145String Assertions 146----------------- 147 148 TEST_ASSERT_EQUAL_STRING(expected, actual) 149 150Compare two null-terminate strings. Fail if any character is different or if the lengths are different. 151 152 TEST_ASSERT_EQUAL_STRING_LEN(expected, actual, len) 153 154Compare two strings. Fail if any character is different, stop comparing after len characters. 155 156 TEST_ASSERT_EQUAL_STRING_MESSAGE(expected, actual, message) 157 158Compare two null-terminate strings. Fail if any character is different or if the lengths are different. Output a custom message on failure. 159 160 TEST_ASSERT_EQUAL_STRING_LEN_MESSAGE(expected, actual, len, message) 161 162Compare two strings. Fail if any character is different, stop comparing after len characters. Output a custom message on failure. 163 164Pointer Assertions 165------------------ 166 167Most pointer operations can be performed by simply using the integer comparisons above. However, a couple of special cases are added for clarity. 168 169 TEST_ASSERT_NULL(pointer) 170 171Fails if the pointer is not equal to NULL 172 173 TEST_ASSERT_NOT_NULL(pointer) 174 175Fails if the pointer is equal to NULL 176 177Memory Assertions 178----------------- 179 180 TEST_ASSERT_EQUAL_MEMORY(expected, actual, len) 181 182Compare two blocks of memory. This is a good generic assertion for types that can't be coerced into acting like 183standard types... but since it's a memory compare, you have to be careful that your data types are packed. 184 185_MESSAGE 186-------- 187 188you can append _MESSAGE to any of the macros to make them take an additional argument. This argument 189is a string that will be printed at the end of the failure strings. This is useful for specifying more 190information about the problem. 191 192
){kind=link}