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 TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) 71 72The very simplest assertion possible uses only a single "actual" parameter (e.g. 73a simple null check). 74 75"Actual" is the value being tested and unlike the other parameters in an 76assertion construction is the only parameter present in all assertion variants. 77"Modifiers" are masks, ranges, bit flag specifiers, floating point deltas. 78"Expected" is your expected value (duh) to compare to an "actual" value; it's 79marked as an optional parameter because some assertions only need a single 80"actual" parameter (e.g. null check). 81"Size/count" refers to string lengths, number of array elements, etc. 82 83Many of Unity's assertions are apparent duplications in that the same data type 84is handled by several assertions. The differences among these are in how failure 85messages are presented. For instance, a `_HEX` variant of an assertion prints 86the expected and actual values of that assertion formatted as hexadecimal. 87 88 89#### TEST_ASSERT_X_MESSAGE Variants 90 91_All_ assertions are complemented with a variant that includes a simple string 92message as a final parameter. The string you specify is appended to an assertion 93failure message in Unity output. 94 95For brevity, the assertion variants with a message parameter are not listed 96below. Just tack on `_MESSAGE` as the final component to any assertion name in 97the reference list below and add a string as the final parameter. 98 99_Example:_ 100 101 TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) 102 103becomes messageified like thus... 104 105 TEST_ASSERT_X_MESSAGE( {modifiers}, {expected}, actual, {size/count}, message ) 106 107 108#### TEST_ASSERT_X_ARRAY Variants 109 110Unity provides a collection of assertions for arrays containing a variety of 111types. These are documented in the Array section below. These are almost on par 112with the `_MESSAGE`variants of Unity's Asserts in that for pretty much any Unity 113type assertion you can tack on `_ARRAY` and run assertions on an entire block of 114memory. 115 116 TEST_ASSERT_EQUAL_TYPEX_ARRAY( expected, actual, {size/count} ) 117 118"Expected" is an array itself. 119"Size/count" is one or two parameters necessary to establish the number of array 120elements and perhaps the length of elements within the array. 121 122Notes: 123- The `_MESSAGE` variant convention still applies here to array assertions. The 124`_MESSAGE` variants of the `_ARRAY` assertions have names ending with 125`_ARRAY_MESSAGE`. 126- Assertions for handling arrays of floating point values are grouped with float 127and double assertions (see immediately following section). 128 129 130### TEST_ASSERT_EACH_EQUAL_X Variants 131 132Unity provides a collection of assertions for arrays containing a variety of 133types which can be compared to a single value as well. These are documented in 134the Each Equal section below. these are almost on par with the `_MESSAGE` 135variants of Unity's Asserts in that for pretty much any Unity type assertion you 136can inject _EACH_EQUAL and run assertions on an entire block of memory. 137 138 TEST_ASSERT_EACH_EQUAL_TYPEX( expected, actual, {size/count} ) 139 140"Expected" is a single value to compare to. 141"Actual" is an array where each element will be compared to the expected value. 142"Size/count" is one of two parameters necessary to establish the number of array 143elements and perhaps the length of elements within the array. 144 145Notes: 146- The `_MESSAGE` variant convention still applies here to Each Equal assertions. 147- Assertions for handling Each Equal of floating point values are grouped with 148float and double assertions (see immediately following section). 149 150 151### Configuration 152 153#### Floating Point Support Is Optional 154 155Support for floating point types is configurable. That is, by defining the 156appropriate preprocessor symbols, floats and doubles can be individually enabled 157or disabled in Unity code. This is useful for embedded targets with no floating 158point math support (i.e. Unity compiles free of errors for fixed point only 159platforms). See Unity documentation for specifics. 160 161 162#### Maximum Data Type Width Is Configurable 163 164Not all targets support 64 bit wide types or even 32 bit wide types. Define the 165appropriate preprocessor symbols and Unity will omit all operations from 166compilation that exceed the maximum width of your target. See Unity 167documentation for specifics. 168 169 170## The Assertions in All Their Blessed Glory 171 172### Basic Fail and Ignore 173 174##### `TEST_FAIL()` 175 176This fella is most often used in special conditions where your test code is 177performing logic beyond a simple assertion. That is, in practice, `TEST_FAIL()` 178will always be found inside a conditional code block. 179 180_Examples:_ 181- Executing a state machine multiple times that increments a counter your test 182code then verifies as a final step. 183- Triggering an exception and verifying it (as in Try / Catch / Throw - see the 184[CException](https://github.com/ThrowTheSwitch/CException) project). 185 186##### `TEST_IGNORE()` 187 188Marks a test case (i.e. function meant to contain test assertions) as ignored. 189Usually this is employed as a breadcrumb to come back and implement a test case. 190An ignored test case has effects if other assertions are in the enclosing test 191case (see Unity documentation for more). 192 193### Boolean 194 195##### `TEST_ASSERT (condition)` 196 197##### `TEST_ASSERT_TRUE (condition)` 198 199##### `TEST_ASSERT_FALSE (condition)` 200 201##### `TEST_ASSERT_UNLESS (condition)` 202 203A simple wording variation on `TEST_ASSERT_FALSE`.The semantics of 204`TEST_ASSERT_UNLESS` aid readability in certain test constructions or 205conditional statements. 206 207##### `TEST_ASSERT_NULL (pointer)` 208 209##### `TEST_ASSERT_NOT_NULL (pointer)` 210 211 212### Signed and Unsigned Integers (of all sizes) 213 214Large integer sizes can be disabled for build targets that do not support them. 215For example, if your target only supports up to 16 bit types, by defining the 216appropriate symbols Unity can be configured to omit 32 and 64 bit operations 217that would break compilation (see Unity documentation for more). Refer to 218Advanced Asserting later in this document for advice on dealing with other word 219sizes. 220 221##### `TEST_ASSERT_EQUAL_INT (expected, actual)` 222 223##### `TEST_ASSERT_EQUAL_INT8 (expected, actual)` 224 225##### `TEST_ASSERT_EQUAL_INT16 (expected, actual)` 226 227##### `TEST_ASSERT_EQUAL_INT32 (expected, actual)` 228 229##### `TEST_ASSERT_EQUAL_INT64 (expected, actual)` 230 231##### `TEST_ASSERT_EQUAL (expected, actual)` 232 233##### `TEST_ASSERT_NOT_EQUAL (expected, actual)` 234 235##### `TEST_ASSERT_EQUAL_UINT (expected, actual)` 236 237##### `TEST_ASSERT_EQUAL_UINT8 (expected, actual)` 238 239##### `TEST_ASSERT_EQUAL_UINT16 (expected, actual)` 240 241##### `TEST_ASSERT_EQUAL_UINT32 (expected, actual)` 242 243##### `TEST_ASSERT_EQUAL_UINT64 (expected, actual)` 244 245 246### Unsigned Integers (of all sizes) in Hexadecimal 247 248All `_HEX` assertions are identical in function to unsigned integer assertions 249but produce failure messages with the `expected` and `actual` values formatted 250in hexadecimal. Unity output is big endian. 251 252##### `TEST_ASSERT_EQUAL_HEX (expected, actual)` 253 254##### `TEST_ASSERT_EQUAL_HEX8 (expected, actual)` 255 256##### `TEST_ASSERT_EQUAL_HEX16 (expected, actual)` 257 258##### `TEST_ASSERT_EQUAL_HEX32 (expected, actual)` 259 260##### `TEST_ASSERT_EQUAL_HEX64 (expected, actual)` 261 262 263### Masked and Bit-level Assertions 264 265Masked and bit-level assertions produce output formatted in hexadecimal. Unity 266output is big endian. 267 268 269##### `TEST_ASSERT_BITS (mask, expected, actual)` 270 271Only compares the masked (i.e. high) bits of `expected` and `actual` parameters. 272 273 274##### `TEST_ASSERT_BITS_HIGH (mask, actual)` 275 276Asserts the masked bits of the `actual` parameter are high. 277 278 279##### `TEST_ASSERT_BITS_LOW (mask, actual)` 280 281Asserts the masked bits of the `actual` parameter are low. 282 283 284##### `TEST_ASSERT_BIT_HIGH (bit, actual)` 285 286Asserts the specified bit of the `actual` parameter is high. 287 288 289##### `TEST_ASSERT_BIT_LOW (bit, actual)` 290 291Asserts the specified bit of the `actual` parameter is low. 292 293### Integer Less Than / Greater Than 294 295These assertions verify that the `actual` parameter is less than or greater 296than `threshold` (exclusive). For example, if the threshold value is 0 for the 297greater than assertion will fail if it is 0 or less. 298 299##### `TEST_ASSERT_GREATER_THAN (threshold, actual)` 300 301##### `TEST_ASSERT_GREATER_THAN_INT (threshold, actual)` 302 303##### `TEST_ASSERT_GREATER_THAN_INT8 (threshold, actual)` 304 305##### `TEST_ASSERT_GREATER_THAN_INT16 (threshold, actual)` 306 307##### `TEST_ASSERT_GREATER_THAN_INT32 (threshold, actual)` 308 309##### `TEST_ASSERT_GREATER_THAN_UINT (threshold, actual)` 310 311##### `TEST_ASSERT_GREATER_THAN_UINT8 (threshold, actual)` 312 313##### `TEST_ASSERT_GREATER_THAN_UINT16 (threshold, actual)` 314 315##### `TEST_ASSERT_GREATER_THAN_UINT32 (threshold, actual)` 316 317##### `TEST_ASSERT_GREATER_THAN_HEX8 (threshold, actual)` 318 319##### `TEST_ASSERT_GREATER_THAN_HEX16 (threshold, actual)` 320 321##### `TEST_ASSERT_GREATER_THAN_HEX32 (threshold, actual)` 322 323##### `TEST_ASSERT_LESS_THAN (threshold, actual)` 324 325##### `TEST_ASSERT_LESS_THAN_INT (threshold, actual)` 326 327##### `TEST_ASSERT_LESS_THAN_INT8 (threshold, actual)` 328 329##### `TEST_ASSERT_LESS_THAN_INT16 (threshold, actual)` 330 331##### `TEST_ASSERT_LESS_THAN_INT32 (threshold, actual)` 332 333##### `TEST_ASSERT_LESS_THAN_UINT (threshold, actual)` 334 335##### `TEST_ASSERT_LESS_THAN_UINT8 (threshold, actual)` 336 337##### `TEST_ASSERT_LESS_THAN_UINT16 (threshold, actual)` 338 339##### `TEST_ASSERT_LESS_THAN_UINT32 (threshold, actual)` 340 341##### `TEST_ASSERT_LESS_THAN_HEX8 (threshold, actual)` 342 343##### `TEST_ASSERT_LESS_THAN_HEX16 (threshold, actual)` 344 345##### `TEST_ASSERT_LESS_THAN_HEX32 (threshold, actual)` 346 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 386### Structs and Strings 387 388##### `TEST_ASSERT_EQUAL_PTR (expected, actual)` 389 390Asserts that the pointers point to the same memory location. 391 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 401##### `TEST_ASSERT_EQUAL_MEMORY (expected, actual, len)` 402 403Asserts that the contents of the memory specified by the `expected` and `actual` 404pointers is identical. The size of the memory blocks in bytes is specified by 405the `len` parameter. 406 407 408### Arrays 409 410`expected` and `actual` parameters are both arrays. `num_elements` specifies the 411number of elements in the arrays to compare. 412 413`_HEX` assertions produce failure messages with expected and actual array 414contents formatted in hexadecimal. 415 416For array of strings comparison behavior, see comments for 417`TEST_ASSERT_EQUAL_STRING` in the preceding section. 418 419Assertions fail upon the first element in the compared arrays found not to 420match. Failure messages specify the array index of the failed comparison. 421 422##### `TEST_ASSERT_EQUAL_INT_ARRAY (expected, actual, num_elements)` 423 424##### `TEST_ASSERT_EQUAL_INT8_ARRAY (expected, actual, num_elements)` 425 426##### `TEST_ASSERT_EQUAL_INT16_ARRAY (expected, actual, num_elements)` 427 428##### `TEST_ASSERT_EQUAL_INT32_ARRAY (expected, actual, num_elements)` 429 430##### `TEST_ASSERT_EQUAL_INT64_ARRAY (expected, actual, num_elements)` 431 432##### `TEST_ASSERT_EQUAL_UINT_ARRAY (expected, actual, num_elements)` 433 434##### `TEST_ASSERT_EQUAL_UINT8_ARRAY (expected, actual, num_elements)` 435 436##### `TEST_ASSERT_EQUAL_UINT16_ARRAY (expected, actual, num_elements)` 437 438##### `TEST_ASSERT_EQUAL_UINT32_ARRAY (expected, actual, num_elements)` 439 440##### `TEST_ASSERT_EQUAL_UINT64_ARRAY (expected, actual, num_elements)` 441 442##### `TEST_ASSERT_EQUAL_HEX_ARRAY (expected, actual, num_elements)` 443 444##### `TEST_ASSERT_EQUAL_HEX8_ARRAY (expected, actual, num_elements)` 445 446##### `TEST_ASSERT_EQUAL_HEX16_ARRAY (expected, actual, num_elements)` 447 448##### `TEST_ASSERT_EQUAL_HEX32_ARRAY (expected, actual, num_elements)` 449 450##### `TEST_ASSERT_EQUAL_HEX64_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 461### Each Equal (Arrays to Single Value) 462 463`expected` are single values and `actual` are arrays. `num_elements` specifies 464the number of elements in the arrays to compare. 465 466`_HEX` assertions produce failure messages with expected and actual array 467contents formatted in hexadecimal. 468 469Assertions fail upon the first element in the compared arrays found not to 470match. Failure messages specify the array index of the failed comparison. 471 472#### `TEST_ASSERT_EACH_EQUAL_INT (expected, actual, num_elements)` 473 474#### `TEST_ASSERT_EACH_EQUAL_INT8 (expected, actual, num_elements)` 475 476#### `TEST_ASSERT_EACH_EQUAL_INT16 (expected, actual, num_elements)` 477 478#### `TEST_ASSERT_EACH_EQUAL_INT32 (expected, actual, num_elements)` 479 480#### `TEST_ASSERT_EACH_EQUAL_INT64 (expected, actual, num_elements)` 481 482#### `TEST_ASSERT_EACH_EQUAL_UINT (expected, actual, num_elements)` 483 484#### `TEST_ASSERT_EACH_EQUAL_UINT8 (expected, actual, num_elements)` 485 486#### `TEST_ASSERT_EACH_EQUAL_UINT16 (expected, actual, num_elements)` 487 488#### `TEST_ASSERT_EACH_EQUAL_UINT32 (expected, actual, num_elements)` 489 490#### `TEST_ASSERT_EACH_EQUAL_UINT64 (expected, actual, num_elements)` 491 492#### `TEST_ASSERT_EACH_EQUAL_HEX (expected, actual, num_elements)` 493 494#### `TEST_ASSERT_EACH_EQUAL_HEX8 (expected, actual, num_elements)` 495 496#### `TEST_ASSERT_EACH_EQUAL_HEX16 (expected, actual, num_elements)` 497 498#### `TEST_ASSERT_EACH_EQUAL_HEX32 (expected, actual, num_elements)` 499 500#### `TEST_ASSERT_EACH_EQUAL_HEX64 (expected, actual, num_elements)` 501 502#### `TEST_ASSERT_EACH_EQUAL_PTR (expected, actual, num_elements)` 503 504#### `TEST_ASSERT_EACH_EQUAL_STRING (expected, actual, num_elements)` 505 506#### `TEST_ASSERT_EACH_EQUAL_MEMORY (expected, actual, len, num_elements)` 507 508`len` is the memory in bytes to be compared at each array element. 509 510 511### Floating Point (If enabled) 512 513##### `TEST_ASSERT_FLOAT_WITHIN (delta, expected, actual)` 514 515Asserts that the `actual` value is within +/- `delta` of the `expected` value. 516The nature of floating point representation is such that exact evaluations of 517equality are not guaranteed. 518 519 520##### `TEST_ASSERT_EQUAL_FLOAT (expected, actual)` 521 522Asserts that the ?actual?value is "close enough to be considered equal" to the 523`expected` value. If you are curious about the details, refer to the Advanced 524Asserting section for more details on this. Omitting a user-specified delta in a 525floating point assertion is both a shorthand convenience and a requirement of 526code generation conventions for CMock. 527 528 529##### `TEST_ASSERT_EQUAL_FLOAT_ARRAY (expected, actual, num_elements)` 530 531See Array assertion section for details. Note that individual array element 532float comparisons are executed using T?EST_ASSERT_EQUAL_FLOAT?.That is, user 533specified delta comparison values requires a custom-implemented floating point 534array assertion. 535 536 537##### `TEST_ASSERT_FLOAT_IS_INF (actual)` 538 539Asserts that `actual` parameter is equivalent to positive infinity floating 540point representation. 541 542 543##### `TEST_ASSERT_FLOAT_IS_NEG_INF (actual)` 544 545Asserts that `actual` parameter is equivalent to negative infinity floating 546point representation. 547 548 549##### `TEST_ASSERT_FLOAT_IS_NAN (actual)` 550 551Asserts that `actual` parameter is a Not A Number floating point representation. 552 553 554##### `TEST_ASSERT_FLOAT_IS_DETERMINATE (actual)` 555 556Asserts that ?actual?parameter is a floating point representation usable for 557mathematical operations. That is, the `actual` parameter is neither positive 558infinity nor negative infinity nor Not A Number floating point representations. 559 560 561##### `TEST_ASSERT_FLOAT_IS_NOT_INF (actual)` 562 563Asserts that `actual` parameter is a value other than positive infinity floating 564point representation. 565 566 567##### `TEST_ASSERT_FLOAT_IS_NOT_NEG_INF (actual)` 568 569Asserts that `actual` parameter is a value other than negative infinity floating 570point representation. 571 572 573##### `TEST_ASSERT_FLOAT_IS_NOT_NAN (actual)` 574 575Asserts that `actual` parameter is a value other than Not A Number floating 576point representation. 577 578 579##### `TEST_ASSERT_FLOAT_IS_NOT_DETERMINATE (actual)` 580 581Asserts that `actual` parameter is not usable for mathematical operations. That 582is, the `actual` parameter is either positive infinity or negative infinity or 583Not A Number floating point representations. 584 585 586### Double (If enabled) 587 588##### `TEST_ASSERT_DOUBLE_WITHIN (delta, expected, actual)` 589 590Asserts that the `actual` value is within +/- `delta` of the `expected` value. 591The nature of floating point representation is such that exact evaluations of 592equality are not guaranteed. 593 594 595##### `TEST_ASSERT_EQUAL_DOUBLE (expected, actual)` 596 597Asserts that the `actual` value is "close enough to be considered equal" to the 598`expected` value. If you are curious about the details, refer to the Advanced 599Asserting section for more details. Omitting a user-specified delta in a 600floating point assertion is both a shorthand convenience and a requirement of 601code generation conventions for CMock. 602 603 604##### `TEST_ASSERT_EQUAL_DOUBLE_ARRAY (expected, actual, num_elements)` 605 606See Array assertion section for details. Note that individual array element 607double comparisons are executed using `TEST_ASSERT_EQUAL_DOUBLE`.That is, user 608specified delta comparison values requires a custom implemented double array 609assertion. 610 611 612##### `TEST_ASSERT_DOUBLE_IS_INF (actual)` 613 614Asserts that `actual` parameter is equivalent to positive infinity floating 615point representation. 616 617 618##### `TEST_ASSERT_DOUBLE_IS_NEG_INF (actual)` 619 620Asserts that `actual` parameter is equivalent to negative infinity floating point 621representation. 622 623 624##### `TEST_ASSERT_DOUBLE_IS_NAN (actual)` 625 626Asserts that `actual` parameter is a Not A Number floating point representation. 627 628 629##### `TEST_ASSERT_DOUBLE_IS_DETERMINATE (actual)` 630 631Asserts that `actual` parameter is a floating point representation usable for 632mathematical operations. That is, the ?actual?parameter is neither positive 633infinity nor negative infinity nor Not A Number floating point representations. 634 635 636##### `TEST_ASSERT_DOUBLE_IS_NOT_INF (actual)` 637 638Asserts that `actual` parameter is a value other than positive infinity floating 639point representation. 640 641 642##### `TEST_ASSERT_DOUBLE_IS_NOT_NEG_INF (actual)` 643 644Asserts that `actual` parameter is a value other than negative infinity floating 645point representation. 646 647 648##### `TEST_ASSERT_DOUBLE_IS_NOT_NAN (actual)` 649 650Asserts that `actual` parameter is a value other than Not A Number floating 651point representation. 652 653 654##### `TEST_ASSERT_DOUBLE_IS_NOT_DETERMINATE (actual)` 655 656Asserts that `actual` parameter is not usable for mathematical operations. That 657is, the `actual` parameter is either positive infinity or negative infinity or 658Not A Number floating point representations. 659 660 661## Advanced Asserting: Details On Tricky Assertions 662 663This section helps you understand how to deal with some of the trickier 664assertion situations you may run into. It will give you a glimpse into some of 665the under-the-hood details of Unity's assertion mechanisms. If you're one of 666those people who likes to know what is going on in the background, read on. If 667not, feel free to ignore the rest of this document until you need it. 668 669 670### How do the EQUAL assertions work for FLOAT and DOUBLE? 671 672As you may know, directly checking for equality between a pair of floats or a 673pair of doubles is sloppy at best and an outright no-no at worst. Floating point 674values can often be represented in multiple ways, particularly after a series of 675operations on a value. Initializing a variable to the value of 2.0 is likely to 676result in a floating point representation of 2 x 20,but a series of 677mathematical operations might result in a representation of 8 x 2-2 678that also evaluates to a value of 2. At some point repeated operations cause 679equality checks to fail. 680 681So Unity doesn't do direct floating point comparisons for equality. Instead, it 682checks if two floating point values are "really close." If you leave Unity 683running with defaults, "really close" means "within a significant bit or two." 684Under the hood, `TEST_ASSERT_EQUAL_FLOAT` is really `TEST_ASSERT_FLOAT_WITHIN` 685with the `delta` parameter calculated on the fly. For single precision, delta is 686the expected value multiplied by 0.00001, producing a very small proportional 687range around the expected value. 688 689If you are expecting a value of 20,000.0 the delta is calculated to be 0.2. So 690any value between 19,999.8 and 20,000.2 will satisfy the equality check. This 691works out to be roughly a single bit of range for a single-precision number, and 692that's just about as tight a tolerance as you can reasonably get from a floating 693point value. 694 695So what happens when it's zero? Zero - even more than other floating point 696values - can be represented many different ways. It doesn't matter if you have 6970 x 20or 0 x 263.It's still zero, right? Luckily, if you 698subtract these values from each other, they will always produce a difference of 699zero, which will still fall between 0 plus or minus a delta of 0. So it still 700works! 701 702Double precision floating point numbers use a much smaller multiplier, again 703approximating a single bit of error. 704 705If you don't like these ranges and you want to make your floating point equality 706assertions less strict, you can change these multipliers to whatever you like by 707defining UNITY_FLOAT_PRECISION and UNITY_DOUBLE_PRECISION. See Unity 708documentation for more. 709 710 711### How do we deal with targets with non-standard int sizes? 712 713It's "fun" that C is a standard where something as fundamental as an integer 714varies by target. According to the C standard, an `int` is to be the target's 715natural register size, and it should be at least 16-bits and a multiple of a 716byte. It also guarantees an order of sizes: 717 718```C 719char <= short <= int <= long <= long long 720``` 721 722Most often, `int` is 32-bits. In many cases in the embedded world, `int` is 72316-bits. There are rare microcontrollers out there that have 24-bit integers, 724and this remains perfectly standard C. 725 726To make things even more interesting, there are compilers and targets out there 727that have a hard choice to make. What if their natural register size is 10-bits 728or 12-bits? Clearly they can't fulfill _both_ the requirement to be at least 72916-bits AND the requirement to match the natural register size. In these 730situations, they often choose the natural register size, leaving us with 731something like this: 732 733```C 734char (8 bit) <= short (12 bit) <= int (12 bit) <= long (16 bit) 735``` 736 737Um... yikes. It's obviously breaking a rule or two... but they had to break SOME 738rules, so they made a choice. 739 740When the C99 standard rolled around, it introduced alternate standard-size types. 741It also introduced macros for pulling in MIN/MAX values for your integer types. 742It's glorious! Unfortunately, many embedded compilers can't be relied upon to 743use the C99 types (Sometimes because they have weird register sizes as described 744above. Sometimes because they don't feel like it?). 745 746A goal of Unity from the beginning was to support every combination of 747microcontroller or microprocessor and C compiler. Over time, we've gotten really 748close to this. There are a few tricks that you should be aware of, though, if 749you're going to do this effectively on some of these more idiosyncratic targets. 750 751First, when setting up Unity for a new target, you're going to want to pay 752special attention to the macros for automatically detecting types 753(where available) or manually configuring them yourself. You can get information 754on both of these in Unity's documentation. 755 756What about the times where you suddenly need to deal with something odd, like a 75724-bit `int`? The simplest solution is to use the next size up. If you have a 75824-bit `int`, configure Unity to use 32-bit integers. If you have a 12-bit 759`int`, configure Unity to use 16 bits. There are two ways this is going to 760affect you: 761 7621. When Unity displays errors for you, it's going to pad the upper unused bits 763with zeros. 7642. You're going to have to be careful of assertions that perform signed 765operations, particularly `TEST_ASSERT_INT_WITHIN`.Such assertions might wrap 766your `int` in the wrong place, and you could experience false failures. You can 767always back down to a simple `TEST_ASSERT` and do the operations yourself. 768 769 770*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)* 771