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