README.md
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
