============== Unity Test API ============== ------------- Running Tests ------------- RUN_TEST(func) 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. TEST_WRAP(function) If the test functions call helper functions and those helper functions have the ability to make assertions, calls to those helpers should be wrapped in a TEST_WRAP macro. This macro aborts the test if the helper triggered a failure. -------------- Ignoring Tests -------------- 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. TEST_IGNORE() Ignore this test and return immediately TEST_IGNORE_MESSAGE (message) Ignore this test and return immediately. Output a message stating why the test was ignored. -------------- Aborting Tests -------------- 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. TEST_PROTECT() Setup and Catch macro TEST_ABORT() Abort Test macro Example: main() { if (TEST_PROTECT() == 0) { MyTest(); } } If MyTest calls TEST_ABORT, program control will immediately return to TEST_PROTECT with a non-zero return value. ======================= Unity Assertion Summary ======================= -------------------- Basic Validity Tests -------------------- TEST_ASSERT_TRUE(condition) Evaluates whatever code is in condition and fails if it evaluates to false TEST_ASSERT_FALSE(condition) Evaluates whatever code is in condition and fails if it evaluates to true TEST_ASSERT(condition) Another way of calling TEST_ASSERT_TRUE TEST_ASSERT_UNLESS(condition) Another way of calling TEST_ASSERT_FALSE TEST_FAIL(message) This test is automatically marked as a failure. The message is output stating why. ------------------------------ Numerical Assertions: Integers ------------------------------ TEST_ASSERT_EQUAL(expected, actual) Another way of calling TEST_ASSERT_EQUAL_INT TEST_ASSERT_EQUAL_INT(expected, actual) Compare two integers for equality and display errors as signed integers. TEST_ASSERT_EQUAL_UINT(expected, actual) Compare two integers for equality and display errors as unsigned integers. TEST_ASSERT_EQUAL_HEX8(expected, actual) Compare two integers for equality and display errors as an 8-bit hex value TEST_ASSERT_EQUAL_HEX16(expected, actual) Compare two integers for equality and display errors as an 16-bit hex value TEST_ASSERT_EQUAL_HEX32(expected, actual) Compare two integers for equality and display errors as an 32-bit hex value TEST_ASSERT_EQUAL_HEX(expected, actual) Another way of calling TEST_ASSERT_EQUAL_HEX32 TEST_ASSERT_INT_WITHIN(delta, expected, actual) Asserts that the actual value is within plus or minus delta of the expected value. TEST_ASSERT_EQUAL_MESSAGE(expected, actual, message) Another way of calling TEST_ASSERT_EQUAL_INT_MESSAGE TEST_ASSERT_EQUAL_INT_MESSAGE(expected, actual, message) Compare two integers for equality and display errors as signed integers. Outputs a custom message on failure. TEST_ASSERT_EQUAL_UINT_MESSAGE(expected, actual, message) Compare two integers for equality and display errors as unsigned integers. Outputs a custom message on failure. TEST_ASSERT_EQUAL_HEX8_MESSAGE(expected, actual, message) Compare two integers for equality and display errors as an 8-bit hex value. Outputs a custom message on failure. TEST_ASSERT_EQUAL_HEX16_MESSAGE(expected, actual, message) Compare two integers for equality and display errors as an 16-bit hex value. Outputs a custom message on failure. TEST_ASSERT_EQUAL_HEX32_MESSAGE(expected, actual, message) Compare two integers for equality and display errors as an 32-bit hex value. Outputs a custom message on failure. TEST_ASSERT_EQUAL_HEX_MESSAGE(expected, actual, message) Another way of calling TEST_ASSERT_EQUAL_HEX32_MESSAGE ----------------------------- Numerical Assertions: Bitwise ----------------------------- TEST_ASSERT_BITS(mask, expected, actual) 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. TEST_ASSERT_BITS_HIGH(mask, actual) 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. TEST_ASSERT_BITS_LOW(mask, actual) 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. TEST_ASSERT_BIT_HIGH(bit, actual) Test a single bit and verify that it is high. The bit is specified 0-31 for a 32-bit integer. TEST_ASSERT_BIT_LOW(bit, actual) Test a single bit and verify that it is low. The bit is specified 0-31 for a 32-bit integer. ---------------------------- Numerical Assertions: Floats ---------------------------- TEST_ASSERT_FLOAT_WITHIN(delta, expected, actual) Asserts that the actual value is within plus or minus delta of the expected value. ----------------- String Assertions ----------------- TEST_ASSERT_EQUAL_STRING(expected, actual) Compare two null-terminate strings. Fail if any character is different or if the lengths are different. TEST_ASSERT_EQUAL_STRING_MESSAGE(expected, actual, message) Compare two null-terminate strings. Fail if any character is different or if the lengths are different. Output a custom message on failure. ------------------ Pointer Assertions ------------------ Most pointer operations can be performed by simply using the integer comparisons above. However, a couple of special cases are added for clarity. TEST_ASSERT_NULL(pointer) Fails if the pointer is not equal to NULL TEST_ASSERT_NOT_NULL(pointer) Fails if the pointer is equal to NULL