Ram Gandikota / Mbed OS ABCD

A metronome using the FRDM K64F board

pal/Test/Unity/README.md@0:a7a43371b306, 2017-05-14 (annotated)

Committer:
ram54288
Date:
Sun May 14 18:40:18 2017 +0000
Revision:
0:a7a43371b306
Initial commit

Who changed what in which revision?

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