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