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