1# Unity Assertions Reference 2 3## Background and Overview 4 5### Super Condensed Version 6 7- An assertion establishes truth (i.e. boolean True) for a single condition. 8Upon boolean False, an assertion stops execution and reports the failure. 9- Unity is mainly a rich collection of assertions and the support to gather up 10and easily execute those assertions. 11- The structure of Unity allows you to easily separate test assertions from 12source code in, well, test code. 13- Unity’s assertions: 14 - Come in many, many flavors to handle different C types and assertion cases. 15 - Use context to provide detailed and helpful failure messages. 16 - Document types, expected values, and basic behavior in your source code for 17free. 18 19### Unity Is Several Things But Mainly It’s Assertions 20 21One way to think of Unity is simply as a rich collection of assertions you can 22use to establish whether your source code behaves the way you think it does. 23Unity provides a framework to easily organize and execute those assertions in 24test code separate from your source code. 25 26### What’s an Assertion? 27 28At their core, assertions are an establishment of truth - boolean truth. Was this 29thing equal to that thing? Does that code doohickey have such-and-such property 30or not? You get the idea. Assertions are executable code. Static analysis is a 31valuable approach to improving code quality, but it is not executing your code 32in the way an assertion can. A failing assertion stops execution and reports an 33error through some appropriate I/O channel (e.g. stdout, GUI, output file, 34blinky light). 35 36Fundamentally, for dynamic verification all you need is a single assertion 37mechanism. In fact, that’s what the [assert() macro][] in C’s standard library 38is for. So why not just use it? Well, we can do far better in the reporting 39department. C’s `assert()` is pretty dumb as-is and is particularly poor for 40handling common data types like arrays, structs, etc. And, without some other 41support, it’s far too tempting to litter source code with C’s `assert()`’s. It’s 42generally much cleaner, manageable, and more useful to separate test and source 43code in the way Unity facilitates. 44 45### Unity’s Assertions: Helpful Messages _and_ Free Source Code Documentation 46 47Asserting a simple truth condition is valuable, but using the context of the 48assertion is even more valuable. For instance, if you know you’re comparing bit 49flags and not just integers, then why not use that context to give explicit, 50readable, bit-level feedback when an assertion fails? 51 52That’s what Unity’s collection of assertions do - capture context to give you 53helpful, meaningful assertion failure messages. In fact, the assertions 54themselves also serve as executable documentation about types and values in your 55source code. So long as your tests remain current with your source and all those 56tests pass, you have a detailed, up-to-date view of the intent and mechanisms in 57your source code. And due to a wondrous mystery, well-tested code usually tends 58to be well designed code. 59 60## Assertion Conventions and Configurations 61 62### Naming and Parameter Conventions 63 64The convention of assertion parameters generally follows this order: 65 66```c 67TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) 68``` 69 70The very simplest assertion possible uses only a single `actual` parameter (e.g. 71a simple null check). 72 73- `Actual` is the value being tested and unlike the other parameters in an 74 assertion construction is the only parameter present in all assertion variants. 75- `Modifiers` are masks, ranges, bit flag specifiers, floating point deltas. 76- `Expected` is your expected value (duh) to compare to an `actual` value; it’s 77 marked as an optional parameter because some assertions only need a single 78 `actual` parameter (e.g. null check). 79- `Size/count` refers to string lengths, number of array elements, etc. 80 81Many of Unity’s assertions are clear duplications in that the same data type 82is handled by several assertions. The differences among these are in how failure 83messages are presented. For instance, a `_HEX` variant of an assertion prints 84the expected and actual values of that assertion formatted as hexadecimal. 85 86#### TEST_ASSERT_X_MESSAGE Variants 87 88_All_ assertions are complemented with a variant that includes a simple string 89message as a final parameter. The string you specify is appended to an assertion 90failure message in Unity output. 91 92For brevity, the assertion variants with a message parameter are not listed 93below. Just tack on `_MESSAGE` as the final component to any assertion name in 94the reference list below and add a string as the final parameter. 95 96_Example:_ 97 98```c 99TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) 100``` 101 102becomes messageified like thus… 103 104```c 105TEST_ASSERT_X_MESSAGE( {modifiers}, {expected}, actual, {size/count}, message ) 106``` 107 108Notes: 109 110- The `_MESSAGE` variants intentionally do not support `printf` style formatting 111 since many embedded projects don’t support or avoid `printf` for various reasons. 112 It is possible to use `sprintf` before the assertion to assemble a complex fail 113 message, if necessary. 114- If you want to output a counter value within an assertion fail message (e.g. from 115 a loop) , building up an array of results and then using one of the `_ARRAY` 116 assertions (see below) might be a handy alternative to `sprintf`. 117 118#### TEST_ASSERT_X_ARRAY Variants 119 120Unity provides a collection of assertions for arrays containing a variety of 121types. These are documented in the Array section below. These are almost on par 122with the `_MESSAGE`variants of Unity’s Asserts in that for pretty much any Unity 123type assertion you can tack on `_ARRAY` and run assertions on an entire block of 124memory. 125 126```c 127 TEST_ASSERT_EQUAL_TYPEX_ARRAY( expected, actual, {size/count} ) 128``` 129 130- `Expected` is an array itself. 131- `Size/count` is one or two parameters necessary to establish the number of array 132 elements and perhaps the length of elements within the array. 133 134Notes: 135 136- The `_MESSAGE` variant convention still applies here to array assertions. The 137 `_MESSAGE` variants of the `_ARRAY` assertions have names ending with 138 `_ARRAY_MESSAGE`. 139- Assertions for handling arrays of floating point values are grouped with float 140 and double assertions (see immediately following section). 141 142### TEST_ASSERT_EACH_EQUAL_X Variants 143 144Unity provides a collection of assertions for arrays containing a variety of 145types which can be compared to a single value as well. These are documented in 146the Each Equal section below. these are almost on par with the `_MESSAGE` 147variants of Unity’s Asserts in that for pretty much any Unity type assertion you 148can inject `_EACH_EQUAL` and run assertions on an entire block of memory. 149 150```c 151TEST_ASSERT_EACH_EQUAL_TYPEX( expected, actual, {size/count} ) 152``` 153 154- `Expected` is a single value to compare to. 155- `Actual` is an array where each element will be compared to the expected value. 156- `Size/count` is one of two parameters necessary to establish the number of array 157 elements and perhaps the length of elements within the array. 158 159Notes: 160 161- The `_MESSAGE` variant convention still applies here to Each Equal assertions. 162- Assertions for handling Each Equal of floating point values are grouped with 163 float and double assertions (see immediately following section). 164 165### Configuration 166 167#### Floating Point Support Is Optional 168 169Support for floating point types is configurable. That is, by defining the 170appropriate preprocessor symbols, floats and doubles can be individually enabled 171or disabled in Unity code. This is useful for embedded targets with no floating 172point math support (i.e. Unity compiles free of errors for fixed point only 173platforms). See Unity documentation for specifics. 174 175#### Maximum Data Type Width Is Configurable 176 177Not all targets support 64 bit wide types or even 32 bit wide types. Define the 178appropriate preprocessor symbols and Unity will omit all operations from 179compilation that exceed the maximum width of your target. See Unity 180documentation for specifics. 181 182## The Assertions in All Their Blessed Glory 183 184### Basic Fail, Pass and Ignore 185 186#### `TEST_FAIL()` 187 188#### `TEST_FAIL_MESSAGE("message")` 189 190This fella is most often used in special conditions where your test code is 191performing logic beyond a simple assertion. That is, in practice, `TEST_FAIL()` 192will always be found inside a conditional code block. 193 194_Examples:_ 195 196- Executing a state machine multiple times that increments a counter your test 197code then verifies as a final step. 198- Triggering an exception and verifying it (as in Try / Catch / Throw - see the 199[CException](https://github.com/ThrowTheSwitch/CException) project). 200 201#### `TEST_PASS()` 202 203#### `TEST_PASS_MESSAGE("message")` 204 205This will abort the remainder of the test, but count the test as a pass. Under 206normal circumstances, it is not necessary to include this macro in your tests… 207a lack of failure will automatically be counted as a `PASS`. It is occasionally 208useful for tests with `#ifdef`s and such. 209 210#### `TEST_IGNORE()` 211 212#### `TEST_IGNORE_MESSAGE("message")` 213 214Marks a test case (i.e. function meant to contain test assertions) as ignored. 215Usually this is employed as a breadcrumb to come back and implement a test case. 216An ignored test case has effects if other assertions are in the enclosing test 217case (see Unity documentation for more). 218 219#### `TEST_MESSAGE(message)` 220 221This can be useful for outputting `INFO` messages into the Unity output stream 222without actually ending the test. Like pass and fail messages, it will be output 223with the filename and line number. 224 225### Boolean 226 227#### `TEST_ASSERT (condition)` 228 229#### `TEST_ASSERT_TRUE (condition)` 230 231#### `TEST_ASSERT_FALSE (condition)` 232 233#### `TEST_ASSERT_UNLESS (condition)` 234 235A simple wording variation on `TEST_ASSERT_FALSE`.The semantics of 236`TEST_ASSERT_UNLESS` aid readability in certain test constructions or 237conditional statements. 238 239#### `TEST_ASSERT_NULL (pointer)` 240 241#### `TEST_ASSERT_NOT_NULL (pointer)` 242 243Verify if a pointer is or is not NULL. 244 245#### `TEST_ASSERT_EMPTY (pointer)` 246 247#### `TEST_ASSERT_NOT_EMPTY (pointer)` 248 249Verify if the first element dereferenced from a pointer is or is not zero. This 250is particularly useful for checking for empty (or non-empty) null-terminated 251C strings, but can be just as easily used for other null-terminated arrays. 252 253### Signed and Unsigned Integers (of all sizes) 254 255Large integer sizes can be disabled for build targets that do not support them. 256For example, if your target only supports up to 16 bit types, by defining the 257appropriate symbols Unity can be configured to omit 32 and 64 bit operations 258that would break compilation (see Unity documentation for more). Refer to 259Advanced Asserting later in this document for advice on dealing with other word 260sizes. 261 262#### `TEST_ASSERT_EQUAL_INT (expected, actual)` 263 264#### `TEST_ASSERT_EQUAL_INT8 (expected, actual)` 265 266#### `TEST_ASSERT_EQUAL_INT16 (expected, actual)` 267 268#### `TEST_ASSERT_EQUAL_INT32 (expected, actual)` 269 270#### `TEST_ASSERT_EQUAL_INT64 (expected, actual)` 271 272#### `TEST_ASSERT_EQUAL_UINT (expected, actual)` 273 274#### `TEST_ASSERT_EQUAL_UINT8 (expected, actual)` 275 276#### `TEST_ASSERT_EQUAL_UINT16 (expected, actual)` 277 278#### `TEST_ASSERT_EQUAL_UINT32 (expected, actual)` 279 280#### `TEST_ASSERT_EQUAL_UINT64 (expected, actual)` 281 282### Unsigned Integers (of all sizes) in Hexadecimal 283 284All `_HEX` assertions are identical in function to unsigned integer assertions 285but produce failure messages with the `expected` and `actual` values formatted 286in hexadecimal. Unity output is big endian. 287 288#### `TEST_ASSERT_EQUAL_HEX (expected, actual)` 289 290#### `TEST_ASSERT_EQUAL_HEX8 (expected, actual)` 291 292#### `TEST_ASSERT_EQUAL_HEX16 (expected, actual)` 293 294#### `TEST_ASSERT_EQUAL_HEX32 (expected, actual)` 295 296#### `TEST_ASSERT_EQUAL_HEX64 (expected, actual)` 297 298### Characters 299 300While you can use the 8-bit integer assertions to compare `char`, another option is 301to use this specialized assertion which will show printable characters as printables, 302otherwise showing the HEX escape code for the characters. 303 304#### `TEST_ASSERT_EQUAL_CHAR (expected, actual)` 305 306### Masked and Bit-level Assertions 307 308Masked and bit-level assertions produce output formatted in hexadecimal. Unity 309output is big endian. 310 311#### `TEST_ASSERT_BITS (mask, expected, actual)` 312 313Only compares the masked (i.e. high) bits of `expected` and `actual` parameters. 314 315#### `TEST_ASSERT_BITS_HIGH (mask, actual)` 316 317Asserts the masked bits of the `actual` parameter are high. 318 319#### `TEST_ASSERT_BITS_LOW (mask, actual)` 320 321Asserts the masked bits of the `actual` parameter are low. 322 323#### `TEST_ASSERT_BIT_HIGH (bit, actual)` 324 325Asserts the specified bit of the `actual` parameter is high. 326 327#### `TEST_ASSERT_BIT_LOW (bit, actual)` 328 329Asserts the specified bit of the `actual` parameter is low. 330 331### Integer Less Than / Greater Than 332 333These assertions verify that the `actual` parameter is less than or greater 334than `threshold` (exclusive). For example, if the threshold value is 0 for the 335greater than assertion will fail if it is 0 or less. There are assertions for 336all the various sizes of ints, as for the equality assertions. Some examples: 337 338#### `TEST_ASSERT_GREATER_THAN_INT8 (threshold, actual)` 339 340#### `TEST_ASSERT_GREATER_OR_EQUAL_INT16 (threshold, actual)` 341 342#### `TEST_ASSERT_LESS_THAN_INT32 (threshold, actual)` 343 344#### `TEST_ASSERT_LESS_OR_EQUAL_UINT (threshold, actual)` 345 346#### `TEST_ASSERT_NOT_EQUAL_UINT8 (threshold, actual)` 347 348### Integer Ranges (of all sizes) 349 350These assertions verify that the `expected` parameter is within +/- `delta` 351(inclusive) of the `actual` parameter. For example, if the expected value is 10 352and the delta is 3 then the assertion will fail for any value outside the range 353of 7 - 13. 354 355#### `TEST_ASSERT_INT_WITHIN (delta, expected, actual)` 356 357#### `TEST_ASSERT_INT8_WITHIN (delta, expected, actual)` 358 359#### `TEST_ASSERT_INT16_WITHIN (delta, expected, actual)` 360 361#### `TEST_ASSERT_INT32_WITHIN (delta, expected, actual)` 362 363#### `TEST_ASSERT_INT64_WITHIN (delta, expected, actual)` 364 365#### `TEST_ASSERT_UINT_WITHIN (delta, expected, actual)` 366 367#### `TEST_ASSERT_UINT8_WITHIN (delta, expected, actual)` 368 369#### `TEST_ASSERT_UINT16_WITHIN (delta, expected, actual)` 370 371#### `TEST_ASSERT_UINT32_WITHIN (delta, expected, actual)` 372 373#### `TEST_ASSERT_UINT64_WITHIN (delta, expected, actual)` 374 375#### `TEST_ASSERT_HEX_WITHIN (delta, expected, actual)` 376 377#### `TEST_ASSERT_HEX8_WITHIN (delta, expected, actual)` 378 379#### `TEST_ASSERT_HEX16_WITHIN (delta, expected, actual)` 380 381#### `TEST_ASSERT_HEX32_WITHIN (delta, expected, actual)` 382 383#### `TEST_ASSERT_HEX64_WITHIN (delta, expected, actual)` 384 385#### `TEST_ASSERT_CHAR_WITHIN (delta, expected, actual)` 386 387### Structs and Strings 388 389#### `TEST_ASSERT_EQUAL_PTR (expected, actual)` 390 391Asserts that the pointers point to the same memory location. 392 393#### `TEST_ASSERT_EQUAL_STRING (expected, actual)` 394 395Asserts that the null terminated (`’\0’`)strings are identical. If strings are 396of different lengths or any portion of the strings before their terminators 397differ, the assertion fails. Two NULL strings (i.e. zero length) are considered 398equivalent. 399 400#### `TEST_ASSERT_EQUAL_MEMORY (expected, actual, len)` 401 402Asserts that the contents of the memory specified by the `expected` and `actual` 403pointers is identical. The size of the memory blocks in bytes is specified by 404the `len` parameter. 405 406### Arrays 407 408`expected` and `actual` parameters are both arrays. `num_elements` specifies the 409number of elements in the arrays to compare. 410 411`_HEX` assertions produce failure messages with expected and actual array 412contents formatted in hexadecimal. 413 414For array of strings comparison behavior, see comments for 415`TEST_ASSERT_EQUAL_STRING` in the preceding section. 416 417Assertions fail upon the first element in the compared arrays found not to 418match. Failure messages specify the array index of the failed comparison. 419 420#### `TEST_ASSERT_EQUAL_INT_ARRAY (expected, actual, num_elements)` 421 422#### `TEST_ASSERT_EQUAL_INT8_ARRAY (expected, actual, num_elements)` 423 424#### `TEST_ASSERT_EQUAL_INT16_ARRAY (expected, actual, num_elements)` 425 426#### `TEST_ASSERT_EQUAL_INT32_ARRAY (expected, actual, num_elements)` 427 428#### `TEST_ASSERT_EQUAL_INT64_ARRAY (expected, actual, num_elements)` 429 430#### `TEST_ASSERT_EQUAL_UINT_ARRAY (expected, actual, num_elements)` 431 432#### `TEST_ASSERT_EQUAL_UINT8_ARRAY (expected, actual, num_elements)` 433 434#### `TEST_ASSERT_EQUAL_UINT16_ARRAY (expected, actual, num_elements)` 435 436#### `TEST_ASSERT_EQUAL_UINT32_ARRAY (expected, actual, num_elements)` 437 438#### `TEST_ASSERT_EQUAL_UINT64_ARRAY (expected, actual, num_elements)` 439 440#### `TEST_ASSERT_EQUAL_HEX_ARRAY (expected, actual, num_elements)` 441 442#### `TEST_ASSERT_EQUAL_HEX8_ARRAY (expected, actual, num_elements)` 443 444#### `TEST_ASSERT_EQUAL_HEX16_ARRAY (expected, actual, num_elements)` 445 446#### `TEST_ASSERT_EQUAL_HEX32_ARRAY (expected, actual, num_elements)` 447 448#### `TEST_ASSERT_EQUAL_HEX64_ARRAY (expected, actual, num_elements)` 449 450#### `TEST_ASSERT_EQUAL_CHAR_ARRAY (expected, actual, num_elements)` 451 452#### `TEST_ASSERT_EQUAL_PTR_ARRAY (expected, actual, num_elements)` 453 454#### `TEST_ASSERT_EQUAL_STRING_ARRAY (expected, actual, num_elements)` 455 456#### `TEST_ASSERT_EQUAL_MEMORY_ARRAY (expected, actual, len, num_elements)` 457 458`len` is the memory in bytes to be compared at each array element. 459 460### Integer Array Ranges (of all sizes) 461 462These assertions verify that the `expected` array parameter is within +/- `delta` 463(inclusive) of the `actual` array parameter. For example, if the expected value is 464\[10, 12\] and the delta is 3 then the assertion will fail for any value 465outside the range of \[7 - 13, 9 - 15\]. 466 467#### `TEST_ASSERT_INT_ARRAY_WITHIN (delta, expected, actual, num_elements)` 468 469#### `TEST_ASSERT_INT8_ARRAY_WITHIN (delta, expected, actual, num_elements)` 470 471#### `TEST_ASSERT_INT16_ARRAY_WITHIN (delta, expected, actual, num_elements)` 472 473#### `TEST_ASSERT_INT32_ARRAY_WITHIN (delta, expected, actual, num_elements)` 474 475#### `TEST_ASSERT_INT64_ARRAY_WITHIN (delta, expected, actual, num_elements)` 476 477#### `TEST_ASSERT_UINT_ARRAY_WITHIN (delta, expected, actual, num_elements)` 478 479#### `TEST_ASSERT_UINT8_ARRAY_WITHIN (delta, expected, actual, num_elements)` 480 481#### `TEST_ASSERT_UINT16_ARRAY_WITHIN (delta, expected, actual, num_elements)` 482 483#### `TEST_ASSERT_UINT32_ARRAY_WITHIN (delta, expected, actual, num_elements)` 484 485#### `TEST_ASSERT_UINT64_ARRAY_WITHIN (delta, expected, actual, num_elements)` 486 487#### `TEST_ASSERT_HEX_ARRAY_WITHIN (delta, expected, actual, num_elements)` 488 489#### `TEST_ASSERT_HEX8_ARRAY_WITHIN (delta, expected, actual, num_elements)` 490 491#### `TEST_ASSERT_HEX16_ARRAY_WITHIN (delta, expected, actual, num_elements)` 492 493#### `TEST_ASSERT_HEX32_ARRAY_WITHIN (delta, expected, actual, num_elements)` 494 495#### `TEST_ASSERT_HEX64_ARRAY_WITHIN (delta, expected, actual, num_elements)` 496 497#### `TEST_ASSERT_CHAR_ARRAY_WITHIN (delta, expected, actual, num_elements)` 498 499### Each Equal (Arrays to Single Value) 500 501`expected` are single values and `actual` are arrays. `num_elements` specifies 502the number of elements in the arrays to compare. 503 504`_HEX` assertions produce failure messages with expected and actual array 505contents formatted in hexadecimal. 506 507Assertions fail upon the first element in the compared arrays found not to 508match. Failure messages specify the array index of the failed comparison. 509 510#### `TEST_ASSERT_EACH_EQUAL_INT (expected, actual, num_elements)` 511 512#### `TEST_ASSERT_EACH_EQUAL_INT8 (expected, actual, num_elements)` 513 514#### `TEST_ASSERT_EACH_EQUAL_INT16 (expected, actual, num_elements)` 515 516#### `TEST_ASSERT_EACH_EQUAL_INT32 (expected, actual, num_elements)` 517 518#### `TEST_ASSERT_EACH_EQUAL_INT64 (expected, actual, num_elements)` 519 520#### `TEST_ASSERT_EACH_EQUAL_UINT (expected, actual, num_elements)` 521 522#### `TEST_ASSERT_EACH_EQUAL_UINT8 (expected, actual, num_elements)` 523 524#### `TEST_ASSERT_EACH_EQUAL_UINT16 (expected, actual, num_elements)` 525 526#### `TEST_ASSERT_EACH_EQUAL_UINT32 (expected, actual, num_elements)` 527 528#### `TEST_ASSERT_EACH_EQUAL_UINT64 (expected, actual, num_elements)` 529 530#### `TEST_ASSERT_EACH_EQUAL_HEX (expected, actual, num_elements)` 531 532#### `TEST_ASSERT_EACH_EQUAL_HEX8 (expected, actual, num_elements)` 533 534#### `TEST_ASSERT_EACH_EQUAL_HEX16 (expected, actual, num_elements)` 535 536#### `TEST_ASSERT_EACH_EQUAL_HEX32 (expected, actual, num_elements)` 537 538#### `TEST_ASSERT_EACH_EQUAL_HEX64 (expected, actual, num_elements)` 539 540#### `TEST_ASSERT_EACH_EQUAL_CHAR (expected, actual, num_elements)` 541 542#### `TEST_ASSERT_EACH_EQUAL_PTR (expected, actual, num_elements)` 543 544#### `TEST_ASSERT_EACH_EQUAL_STRING (expected, actual, num_elements)` 545 546#### `TEST_ASSERT_EACH_EQUAL_MEMORY (expected, actual, len, num_elements)` 547 548`len` is the memory in bytes to be compared at each array element. 549 550### Floating Point (If enabled) 551 552#### `TEST_ASSERT_FLOAT_WITHIN (delta, expected, actual)` 553 554Asserts that the `actual` value is within +/- `delta` of the `expected` value. 555The nature of floating point representation is such that exact evaluations of 556equality are not guaranteed. 557 558#### `TEST_ASSERT_FLOAT_NOT_WITHIN (delta, expected, actual)` 559 560Asserts that the `actual` value is NOT within +/- `delta` of the `expected` value. 561 562#### `TEST_ASSERT_EQUAL_FLOAT (expected, actual)` 563 564Asserts that the `actual` value is “close enough to be considered equal” to the 565`expected` value. If you are curious about the details, refer to the Advanced 566Asserting section for more details on this. Omitting a user-specified delta in a 567floating point assertion is both a shorthand convenience and a requirement of 568code generation conventions for CMock. 569 570#### `TEST_ASSERT_NOT_EQUAL_FLOAT (expected, actual)` 571 572Asserts that the `actual` value is NOT “close enough to be considered equal” to the 573`expected` value. 574 575#### `TEST_ASSERT_FLOAT_ARRAY_WITHIN (delta, expected, actual, num_elements)` 576 577See Array assertion section for details. Note that individual array element 578uses user-provided delta plus default comparison delta for checking 579and is based on `TEST_ASSERT_FLOAT_WITHIN` comparison. 580 581#### `TEST_ASSERT_EQUAL_FLOAT_ARRAY (expected, actual, num_elements)` 582 583See Array assertion section for details. Note that individual array element 584float comparisons are executed using `TEST_ASSERT_EQUAL_FLOAT`. That is, user 585specified delta comparison values requires a custom-implemented floating point 586array assertion. 587 588#### `TEST_ASSERT_LESS_THAN_FLOAT (threshold, actual)` 589 590Asserts that the `actual` parameter is less than `threshold` (exclusive). 591For example, if the threshold value is 1.0f, the assertion will fail if it is 592greater than 1.0f. 593 594#### `TEST_ASSERT_GREATER_THAN_FLOAT (threshold, actual)` 595 596Asserts that the `actual` parameter is greater than `threshold` (exclusive). 597For example, if the threshold value is 1.0f, the assertion will fail if it is 598less than 1.0f. 599 600#### `TEST_ASSERT_LESS_OR_EQUAL_FLOAT (threshold, actual)` 601 602Asserts that the `actual` parameter is less than or equal to `threshold`. 603The rules for equality are the same as for `TEST_ASSERT_EQUAL_FLOAT`. 604 605#### `TEST_ASSERT_GREATER_OR_EQUAL_FLOAT (threshold, actual)` 606 607Asserts that the `actual` parameter is greater than `threshold`. 608The rules for equality are the same as for `TEST_ASSERT_EQUAL_FLOAT`. 609 610#### `TEST_ASSERT_FLOAT_IS_INF (actual)` 611 612Asserts that `actual` parameter is equivalent to positive infinity floating 613point representation. 614 615#### `TEST_ASSERT_FLOAT_IS_NEG_INF (actual)` 616 617Asserts that `actual` parameter is equivalent to negative infinity floating 618point representation. 619 620#### `TEST_ASSERT_FLOAT_IS_NAN (actual)` 621 622Asserts that `actual` parameter is a Not A Number floating point representation. 623 624#### `TEST_ASSERT_FLOAT_IS_DETERMINATE (actual)` 625 626Asserts that `actual` parameter is a floating point representation usable for 627mathematical operations. That is, the `actual` parameter is neither positive 628infinity nor negative infinity nor Not A Number floating point representations. 629 630#### `TEST_ASSERT_FLOAT_IS_NOT_INF (actual)` 631 632Asserts that `actual` parameter is a value other than positive infinity floating 633point representation. 634 635#### `TEST_ASSERT_FLOAT_IS_NOT_NEG_INF (actual)` 636 637Asserts that `actual` parameter is a value other than negative infinity floating 638point representation. 639 640#### `TEST_ASSERT_FLOAT_IS_NOT_NAN (actual)` 641 642Asserts that `actual` parameter is a value other than Not A Number floating 643point representation. 644 645#### `TEST_ASSERT_FLOAT_IS_NOT_DETERMINATE (actual)` 646 647Asserts that `actual` parameter is not usable for mathematical operations. That 648is, the `actual` parameter is either positive infinity or negative infinity or 649Not A Number floating point representations. 650 651### Double (If enabled) 652 653#### `TEST_ASSERT_DOUBLE_WITHIN (delta, expected, actual)` 654 655Asserts that the `actual` value is within +/- `delta` of the `expected` value. 656The nature of floating point representation is such that exact evaluations of 657equality are not guaranteed. 658 659#### `TEST_ASSERT_DOUBLE_NOT_WITHIN (delta, expected, actual)` 660 661Asserts that the `actual` value is NOT within +/- `delta` of the `expected` value. 662 663#### `TEST_ASSERT_EQUAL_DOUBLE (expected, actual)` 664 665Asserts that the `actual` value is “close enough to be considered equal” to the 666`expected` value. If you are curious about the details, refer to the Advanced 667Asserting section for more details. Omitting a user-specified delta in a 668floating point assertion is both a shorthand convenience and a requirement of 669code generation conventions for CMock. 670 671#### `TEST_ASSERT_NOT_EQUAL_DOUBLE (expected, actual)` 672 673Asserts that the `actual` value is NOT “close enough to be considered equal” to the 674`expected` value. 675 676#### `TEST_ASSERT_DOUBLE_ARRAY_WITHIN (delta, expected, actual, num_elements)` 677 678See Array assertion section for details. Note that individual array element 679uses user-provided delta plus default comparison delta for checking 680and is based on `TEST_ASSERT_DOUBLE_WITHIN` comparison. 681 682#### `TEST_ASSERT_EQUAL_DOUBLE_ARRAY (expected, actual, num_elements)` 683 684See Array assertion section for details. Note that individual array element 685double comparisons are executed using `TEST_ASSERT_EQUAL_DOUBLE`. That is, user 686specified delta comparison values requires a custom implemented double array 687assertion. 688 689#### `TEST_ASSERT_LESS_THAN_DOUBLE (threshold, actual)` 690 691Asserts that the `actual` parameter is less than `threshold` (exclusive). 692For example, if the threshold value is 1.0, the assertion will fail if it is 693greater than 1.0. 694 695#### `TEST_ASSERT_LESS_OR_EQUAL_DOUBLE (threshold, actual)` 696 697Asserts that the `actual` parameter is less than or equal to `threshold`. 698The rules for equality are the same as for `TEST_ASSERT_EQUAL_DOUBLE`. 699 700#### `TEST_ASSERT_GREATER_THAN_DOUBLE (threshold, actual)` 701 702Asserts that the `actual` parameter is greater than `threshold` (exclusive). 703For example, if the threshold value is 1.0, the assertion will fail if it is 704less than 1.0. 705 706#### `TEST_ASSERT_GREATER_OR_EQUAL_DOUBLE (threshold, actual)` 707 708Asserts that the `actual` parameter is greater than or equal to `threshold`. 709The rules for equality are the same as for `TEST_ASSERT_EQUAL_DOUBLE`. 710 711#### `TEST_ASSERT_DOUBLE_IS_INF (actual)` 712 713Asserts that `actual` parameter is equivalent to positive infinity floating 714point representation. 715 716#### `TEST_ASSERT_DOUBLE_IS_NEG_INF (actual)` 717 718Asserts that `actual` parameter is equivalent to negative infinity floating point 719representation. 720 721#### `TEST_ASSERT_DOUBLE_IS_NAN (actual)` 722 723Asserts that `actual` parameter is a Not A Number floating point representation. 724 725#### `TEST_ASSERT_DOUBLE_IS_DETERMINATE (actual)` 726 727Asserts that `actual` parameter is a floating point representation usable for 728mathematical operations. That is, the `actual` parameter is neither positive 729infinity nor negative infinity nor Not A Number floating point representations. 730 731#### `TEST_ASSERT_DOUBLE_IS_NOT_INF (actual)` 732 733Asserts that `actual` parameter is a value other than positive infinity floating 734point representation. 735 736#### `TEST_ASSERT_DOUBLE_IS_NOT_NEG_INF (actual)` 737 738Asserts that `actual` parameter is a value other than negative infinity floating 739point representation. 740 741#### `TEST_ASSERT_DOUBLE_IS_NOT_NAN (actual)` 742 743Asserts that `actual` parameter is a value other than Not A Number floating 744point representation. 745 746#### `TEST_ASSERT_DOUBLE_IS_NOT_DETERMINATE (actual)` 747 748Asserts that `actual` parameter is not usable for mathematical operations. That 749is, the `actual` parameter is either positive infinity or negative infinity or 750Not A Number floating point representations. 751 752## Advanced Asserting: Details On Tricky Assertions 753 754This section helps you understand how to deal with some of the trickier 755assertion situations you may run into. It will give you a glimpse into some of 756the under-the-hood details of Unity’s assertion mechanisms. If you’re one of 757those people who likes to know what is going on in the background, read on. If 758not, feel free to ignore the rest of this document until you need it. 759 760### How do the EQUAL assertions work for FLOAT and DOUBLE? 761 762As you may know, directly checking for equality between a pair of floats or a 763pair of doubles is sloppy at best and an outright no-no at worst. Floating point 764values can often be represented in multiple ways, particularly after a series of 765operations on a value. Initializing a variable to the value of 2.0 is likely to 766result in a floating point representation of 2 x 20,but a series of 767mathematical operations might result in a representation of 8 x 2-2 768that also evaluates to a value of 2. At some point repeated operations cause 769equality checks to fail. 770 771So Unity doesn’t do direct floating point comparisons for equality. Instead, it 772checks if two floating point values are “really close.” If you leave Unity 773running with defaults, “really close” means “within a significant bit or two.” 774Under the hood, `TEST_ASSERT_EQUAL_FLOAT` is really `TEST_ASSERT_FLOAT_WITHIN` 775with the `delta` parameter calculated on the fly. For single precision, delta is 776the expected value multiplied by 0.00001, producing a very small proportional 777range around the expected value. 778 779If you are expecting a value of 20,000.0 the delta is calculated to be 0.2. So 780any value between 19,999.8 and 20,000.2 will satisfy the equality check. This 781works out to be roughly a single bit of range for a single-precision number, and 782that’s just about as tight a tolerance as you can reasonably get from a floating 783point value. 784 785So what happens when it’s zero? Zero - even more than other floating point 786values - can be represented many different ways. It doesn’t matter if you have 7870x20 or 0x263. It’s still zero, right? Luckily, if you subtract these 788values from each other, they will always produce a difference of zero, which 789will still fall between 0 plus or minus a delta of 0. So it still works! 790 791Double precision floating point numbers use a much smaller multiplier, again 792approximating a single bit of error. 793 794If you don’t like these ranges and you want to make your floating point equality 795assertions less strict, you can change these multipliers to whatever you like by 796defining UNITY_FLOAT_PRECISION and UNITY_DOUBLE_PRECISION. See Unity 797documentation for more. 798 799### How do we deal with targets with non-standard int sizes? 800 801It’s “fun” that C is a standard where something as fundamental as an integer 802varies by target. According to the C standard, an `int` is to be the target’s 803natural register size, and it should be at least 16-bits and a multiple of a 804byte. It also guarantees an order of sizes: 805 806```C 807char <= short <= int <= long <= long long 808``` 809 810Most often, `int` is 32-bits. In many cases in the embedded world, `int` is 81116-bits. There are rare microcontrollers out there that have 24-bit integers, 812and this remains perfectly standard C. 813 814To make things even more interesting, there are compilers and targets out there 815that have a hard choice to make. What if their natural register size is 10-bits 816or 12-bits? Clearly they can’t fulfill _both_ the requirement to be at least 81716-bits AND the requirement to match the natural register size. In these 818situations, they often choose the natural register size, leaving us with 819something like this: 820 821```C 822char (8 bit) <= short (12 bit) <= int (12 bit) <= long (16 bit) 823``` 824 825Um… yikes. It’s obviously breaking a rule or two… but they had to break SOME 826rules, so they made a choice. 827 828When the C99 standard rolled around, it introduced alternate standard-size types. 829It also introduced macros for pulling in MIN/MAX values for your integer types. 830It’s glorious! Unfortunately, many embedded compilers can’t be relied upon to 831use the C99 types (Sometimes because they have weird register sizes as described 832above. Sometimes because they don’t feel like it?). 833 834A goal of Unity from the beginning was to support every combination of 835microcontroller or microprocessor and C compiler. Over time, we’ve gotten really 836close to this. There are a few tricks that you should be aware of, though, if 837you’re going to do this effectively on some of these more idiosyncratic targets. 838 839First, when setting up Unity for a new target, you’re going to want to pay 840special attention to the macros for automatically detecting types 841(where available) or manually configuring them yourself. You can get information 842on both of these in Unity’s documentation. 843 844What about the times where you suddenly need to deal with something odd, like a 84524-bit `int`? The simplest solution is to use the next size up. If you have a 84624-bit `int`, configure Unity to use 32-bit integers. If you have a 12-bit 847`int`, configure Unity to use 16 bits. There are two ways this is going to 848affect you: 849 8501. When Unity displays errors for you, it’s going to pad the upper unused bits 851 with zeros. 8522. You’re going to have to be careful of assertions that perform signed 853 operations, particularly `TEST_ASSERT_INT_WITHIN`. Such assertions might wrap 854 your `int` in the wrong place, and you could experience false failures. You can 855 always back down to a simple `TEST_ASSERT` and do the operations yourself. 856 857*Find The Latest of This And More at [ThrowTheSwitch.org][]* 858 859[assert() macro]: http://en.wikipedia.org/wiki/Assert.h 860[ThrowTheSwitch.org]: https://throwtheswitch.org 861