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