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