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