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