diff --git a/docs/ThrowTheSwitchCodingStandard.md b/docs/ThrowTheSwitchCodingStandard.md new file mode 100644 index 0000000000000000000000000000000000000000..a48a83240334ce980f05842643b70f1bc19eef29 --- /dev/null +++ b/docs/ThrowTheSwitchCodingStandard.md @@ -0,0 +1,170 @@ +# ThrowTheSwitch.org Coding Standard +Hi. Welcome to the coding standard for ThrowTheSwitch.org. For the most part, +we try to follow these standards to unify our contributors' code into a cohesive +unit (puns intended). You might find places where these standards aren't +followed. We're not perfect. Please be polite where +you notice these discrepancies and we'll try to be polite when we notice yours. +;) + +## Why Have A Coding Standard? +Being consistent makes code easier to understand. We've made an attempt to keep +our standard simple because we also believe that we can only expect someone to +follow something that is understandable. Please do your best. + +## Our Philosophy +Before we get into details on syntax, let's take a moment to talk about our +vision for these tools. We're C developers and embedded software developers. +These tools are great to test any C code, but catering to embedded software has +made us more tolerant of compiler quirks. There are a LOT of quirky compilers +out there. By quirky I mean "doesn't follow standards because they feel like +they have a license to do as they wish." + +Our philosophy is "support every compiler we can". Most often, this means that +we aim for writing C code that is standards compliant (often C89... that seems +to be a sweet spot that is almost always compatible). But it also means these +tools are tolerant of things that aren't common. Some that aren't even +compliant. There are configuration options to override the size of standard +types. There are configuration options to force Unity to not use certain +standard library functions. A lot of Unity is configurable and we have worked +hard to make it not TOO ugly in the process. + +Similarly, our tools that parse C do their best. They aren't full C parsers +(yet) and, even if they were, they would still have to accept non-standard +additions like gcc extensions or specifying `@0x1000` to force a variable to +compile to a particular location. It's just what we do, because we like +everything to Just Work™. + +Speaking of having things Just Work™, that's our second philosophy. By that, we +mean that we do our best to have EVERY configuration option have a logical +default. We believe that if you're working with a simple compiler and target, +you shouldn't need to configure very much... we try to make the tools guess as +much as they can, but give the user the power to override it when it's wrong. + +## Naming Things +Let's talk about naming things. Programming is all about naming things. We name +files, functions, variables, and so much more. While we're not always going to +find the best name for something, we actually put quite a bit of effort into +finding *What Something WANTS to be Called*™. + +When naming things, we more or less follow this hierarchy, the first being the +most important to us (but we do all four whenever possible): +1. Readable +2. Descriptive +3. Consistent +4. Memorable + +#### Readable +We want to read our code. This means we like names and flow that are more +naturally read. We try to avoid double negatives. We try to avoid cryptic +abbreviations (sticking to ones we feel are common). + +#### Descriptive +We like descriptive names for things, especially functions and variables. +Finding the right name for something is an important endeavor. You might notice +from poking around our code that this often results in names that are a little +longer than the average. Guilty. We're okay with a tiny bit more typing if it +means our code is easier to understand. + +There are two exceptions to this rule that we also stick to as religiously as +possible: + +First, while we realize hungarian notation (and similar systems for encoding +type information into variable names) is providing a more descriptive name, we +feel that (for the average developer) it takes away from readability and +therefore is to be avoided. + +Second, loop counters and other local throw-away variables often have a purpose +which is obvious. There's no need, therefore, to get carried away with complex +naming. We find i, j, and k are better loop counters than loopCounterVar or +whatnot. We only break this rule when we see that more description could improve +understanding of an algorithm. + +#### Consistent +We like consistency, but we're not really obsessed with it. We try to name our +configuration macros in a consistent fashion... you'll notice a repeated use of +UNITY_EXCLUDE_BLAH or UNITY_USES_BLAH macros. This helps users avoid having to +remember each macro's details. + +#### Memorable +Where ever it doesn't violate the above principles, we try to apply memorable +names. Sometimes this means using something that is simply descriptive, but +often we strive for descriptive AND unique... we like quirky names that stand +out in our memory and are easier to search for. Take a look through the file +names in Ceedling and you'll get a good idea of what we are talking about here. +Why use preprocess when you can use preprocessinator? Or what better describes a +module in charge of invoking tasks during releases than release_invoker? Don't +get carried away. The names are still descriptive and fulfill the above +requirements, but they don't feel stale. + +## C and C++ Details +We don't really want to add to the style battles out there. Tabs or spaces? +How many spaces? Where do the braces go? These are age-old questions that will +never be answered... or at least not answered in a way that will make everyone +happy. + +We've decided on our own style preferences. If you'd like to contribute to these +projects (and we hope that you do), then we ask if you do your best to follow +the same. It will only hurt a little. We promise. + +#### Whitespace +Our C-style is to use spaces and to use 4 of them per indent level. It's a nice +power-of-2 number that looks decent on a wide screen. We have no more reason +than that. We break that rule when we have lines that wrap (macros or function +arguments or whatnot). When that happens, we like to indent further to line +things up in nice tidy columns. + +```C + if (stuff_happened) + { + do_something(); + } +``` + +#### Case +- Files - all lower case with underscores. +- Variables - all lower case with underscores +- Macros - all caps with underscores. +- Typedefs - all caps with underscores. (also ends with _T). +- Functions - camel cased. Usually named ModuleName_FuncName +- Constants and Globals - camel cased. + +#### Braces +The left brace is on the next line after the declaration. The right brace is +directly below that. Everything in between in indented one level. If you're +catching an error and you have a one-line, go ahead and to it on the same line. + +```C + while (blah) + { + //Like so. Even if only one line, we use braces. + } +``` + +#### Comments +Do you know what we hate? Old-school C block comments. BUT, we're using them +anyway. As we mentioned, our goal is to support every compiler we can, +especially embedded compilers. There are STILL C compilers out there that only +support old-school block comments. So that is what we're using. We apologize. We +think they are ugly too. + +## Ruby Details +Is there really such thing as a Ruby coding standard? Ruby is such a free form +language, it seems almost sacrilegious to suggest that people should comply to +one method! We'll keep it really brief! + +#### Whitespace +Our Ruby style is to use spaces and to use 2 of them per indent level. It's a +nice power-of-2 number that really grooves with Ruby's compact style. We have no +more reason than that. We break that rule when we have lines that wrap. When +that happens, we like to indent further to line things up in nice tidy columns. + +#### Case +- Files - all lower case with underscores. +- Variables - all lower case with underscores +- Classes, Modules, etc - Camel cased. +- Functions - all lower case with underscores +- Constants - all upper case with underscores + +## Documentation +Egad. Really? We use markdown and we like pdf files because they can be made to +look nice while still being portable. Good enough? diff --git a/docs/UnityAssertionsReference.md b/docs/UnityAssertionsReference.md new file mode 100644 index 0000000000000000000000000000000000000000..bc2ce7d455be0f87389d43303ca52dfc7455701e --- /dev/null +++ b/docs/UnityAssertionsReference.md @@ -0,0 +1,486 @@ +# Unity Assertions Reference +## Background and Overview +### Super Condensed Version +- An assertion establishes truth (i.e. boolean True) for a single condition. +Upon boolean False, an assertion stops execution and reports the failure. +- Unity is mainly a rich collection of assertions and the support to gather up +and easily execute those assertions. +- The structure of Unity allows you to easily separate test assertions from +source code in, well, test code. +- Unity's assertions: +- Come in many, many flavors to handle different C types and assertion cases. +- Use context to provide detailed and helpful failure messages. +- Document types, expected values, and basic behavior in your source code for +free. + +### Unity Is Several Things But Mainly It's Assertions +One way to think of Unity is simply as a rich collection of assertions you can +use to establish whether your source code behaves the way you think it does. +Unity provides a framework to easily organize and execute those assertions in +test code separate from your source code. + +### What's an Assertion? +At their core, assertions are an establishment of truth—boolean truth. Was this +thing equal to that thing? Does that code doohickey have such-and-such property +or not? You get the idea. Assertions are executable code (to appreciate the big +picture on this read up on the difference between +[link:Dynamic Verification and Static Analysis]). A failing assertion stops +execution and reports an error through some appropriate I/O channel (e.g. +stdout, GUI, file, blinky light). + +Fundamentally, for dynamic verification all you need is a single assertion +mechanism. In fact, that's what the [assert() macro in C's standard library](http://en.wikipedia.org/en/wiki/Assert.h) +is for. So why not just use it? Well, we can do far better in the reporting +department. C's `assert()` is pretty dumb as-is and is particularly poor for +handling common data types like arrays, structs, etc. And, without some other +support, it's far too tempting to litter source code with C's `assert()`'s. It's +generally much cleaner, manageable, and more useful to separate test and source +code in the way Unity facilitates. + +### Unity's Assertions: Helpful Messages _and_ Free Source Code Documentation +Asserting a simple truth condition is valuable, but using the context of the +assertion is even more valuable. For instance, if you know you're comparing bit +flags and not just integers, then why not use that context to give explicit, +readable, bit-level feedback when an assertion fails? + +That's what Unity's collection of assertions do - capture context to give you +helpful, meaningful assertion failure messages. In fact, the assertions +themselves also serve as executable documentation about types and values in your +source code. So long as your tests remain current with your source and all those +tests pass, you have a detailed, up-to-date view of the intent and mechanisms in +your source code. And due to a wondrous mystery, well-tested code usually tends +to be well designed code. + +## Assertion Conventions and Configurations +### Naming and Parameter Conventions +The convention of assertion parameters generally follows this order: + + TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) + +The very simplest assertion possible uses only a single "actual" parameter (e.g. +a simple null check). + +"Actual" is the value being tested and unlike the other parameters in an +assertion construction is the only parameter present in all assertion variants. +"Modifiers" are masks, ranges, bit flag specifiers, floating point deltas. +"Expected" is your expected value (duh) to compare to an "actual" value; it's +marked as an optional parameter because some assertions only need a single +"actual" parameter (e.g. null check). +"Size/count" refers to string lengths, number of array elements, etc. + +Many of Unity's assertions are apparent duplications in that the same data type +is handled by several assertions. The differences among these are in how failure +messages are presented. For instance, a `_HEX` variant of an assertion prints +the expected and actual values of that assertion formatted as hexadecimal. + +#### TEST_ASSERT_X_MESSAGE Variants +_All_ assertions are complemented with a variant that includes a simple string +message as a final parameter. The string you specify is appended to an assertion +failure message in Unity output. + +For brevity, the assertion variants with a message parameter are not listed +below. Just tack on `_MESSAGE` as the final component to any assertion name in +the reference list below and add a string as the final parameter. + +_Example:_ + + TEST_ASSERT_X( {modifiers}, {expected}, actual, {size/count} ) + +becomes messageified like thus... + + TEST_ASSERT_X_MESSAGE( {modifiers}, {expected}, actual, {size/count}, message ) + +#### TEST_ASSERT_X_ARRAY Variants +Unity provides a collection of assertions for arrays containing a variety of +types. These are documented in the Array section below. These are almost on par +with the `_MESSAGE`variants of Unity's Asserts in that for pretty much any Unity +type assertion you can tack on `_ARRAY` and run assertions on an entire block of +memory. + + TEST_ASSERT_EQUAL_TYPEX_ARRAY( expected, actual, {size/count} ) + +"Expected" is an array itself. +"Size/count" is one or two parameters necessary to establish the number of array +elements and perhaps the length of elements within the array. + +Notes: +- The `_MESSAGE` variant convention still applies here to array assertions. The +`_MESSAGE` variants of the `_ARRAY` assertions have names ending with +`_ARRAY_MESSAGE`. +- Assertions for handling arrays of floating point values are grouped with float +and double assertions (see immediately following section). + +### Configuration +#### Floating Point Support Is Optional +Support for floating point types is configurable. That is, by defining the +appropriate preprocessor symbols, floats and doubles can be individually enabled +or disabled in Unity code. This is useful for embedded targets with no floating +point math support (i.e. Unity compiles free of errors for fixed point only +platforms). See Unity documentation for specifics. + +#### Maximum Data Type Width Is Configurable +Not all targets support 64 bit wide types or even 32 bit wide types. Define the +appropriate preprocessor symbols and Unity will omit all operations from +compilation that exceed the maximum width of your target. See Unity +documentation for specifics. + +## The Assertions in All Their Blessed Glory +### Basic Fail and Ignore + +##### `TEST_FAIL()` +This fella is most often used in special conditions where your test code is +performing logic beyond a simple assertion. That is, in practice, `TEST_FAIL()` +will always be found inside a conditional code block. + +_Examples:_ +- Executing a state machine multiple times that increments a counter your test +code then verifies as a final step. +- Triggering an exception and verifying it (as in Try / Catch / Throw - see the +[CException](https://github.com/ThrowTheSwitch/CException) project). + +##### `TEST_IGNORE()` +Marks a test case (i.e. function meant to contain test assertions) as ignored. +Usually this is employed as a breadcrumb to come back and implement a test case. +An ignored test case has effects if other assertions are in the enclosing test +case (see Unity documentation for more). + +### Boolean +##### `TEST_ASSERT (condition)` +##### `TEST_ASSERT_TRUE (condition)` +##### `TEST_ASSERT_FALSE (condition)` +##### `TEST_ASSERT_UNLESS (condition)` +A simple wording variation on `TEST_ASSERT_FALSE`.The semantics of +`TEST_ASSERT_UNLESS` aid readability in certain test constructions or +conditional statements. + +##### `TEST_ASSERT_NULL (pointer)` +##### `TEST_ASSERT_NOT_NULL (pointer)` + + +### Signed and Unsigned Integers (of all sizes) +Large integer sizes can be disabled for build targets that do not support them. +For example, if your target only supports up to 16 bit types, by defining the +appropriate symbols Unity can be configured to omit 32 and 64 bit operations +that would break compilation (see Unity documentation for more). Refer to +Advanced Asserting later in this document for advice on dealing with other word +sizes. + +##### `TEST_ASSERT_EQUAL_INT (expected, actual)` +##### `TEST_ASSERT_EQUAL_INT8 (expected, actual)` +##### `TEST_ASSERT_EQUAL_INT16 (expected, actual)` +##### `TEST_ASSERT_EQUAL_INT32 (expected, actual)` +##### `TEST_ASSERT_EQUAL_INT64 (expected, actual)` +##### `TEST_ASSERT_EQUAL (expected, actual)` +##### `TEST_ASSERT_NOT_EQUAL (expected, actual)` +##### `TEST_ASSERT_EQUAL_UINT (expected, actual)` +##### `TEST_ASSERT_EQUAL_UINT8 (expected, actual)` +##### `TEST_ASSERT_EQUAL_UINT16 (expected, actual)` +##### `TEST_ASSERT_EQUAL_UINT32 (expected, actual)` +##### `TEST_ASSERT_EQUAL_UINT64 (expected, actual)` + +### Unsigned Integers (of all sizes) in Hexadecimal +All `_HEX` assertions are identical in function to unsigned integer assertions +but produce failure messages with the `expected` and `actual` values formatted +in hexadecimal. Unity output is big endian. + +##### `TEST_ASSERT_EQUAL_HEX (expected, actual)` +##### `TEST_ASSERT_EQUAL_HEX8 (expected, actual)` +##### `TEST_ASSERT_EQUAL_HEX16 (expected, actual)` +##### `TEST_ASSERT_EQUAL_HEX32 (expected, actual)` +##### `TEST_ASSERT_EQUAL_HEX64 (expected, actual)` + +### Masked and Bit-level Assertions +Masked and bit-level assertions produce output formatted in hexadecimal. Unity +output is big endian. + +##### `TEST_ASSERT_BITS (mask, expected, actual)` +Only compares the masked (i.e. high) bits of `expected` and `actual` parameters. + +##### `TEST_ASSERT_BITS_HIGH (mask, actual)` +Asserts the masked bits of the `actual` parameter are high. + +##### `TEST_ASSERT_BITS_LOW (mask, actual)` +Asserts the masked bits of the `actual` parameter are low. + +##### `TEST_ASSERT_BIT_HIGH (bit, actual)` +Asserts the specified bit of the `actual` parameter is high. + +##### `TEST_ASSERT_BIT_LOW (bit, actual)` +Asserts the specified bit of the `actual` parameter is low. + +### Integer Ranges (of all sizes) +These assertions verify that the `expected` parameter is within +/- `delta` +(inclusive) of the `actual` parameter. For example, if the expected value is 10 +and the delta is 3 then the assertion will fail for any value outside the range +of 7 - 13. + +##### `TEST_ASSERT_INT_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_INT8_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_INT16_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_INT32_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_INT64_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_UINT_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_UINT8_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_UINT16_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_UINT32_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_UINT64_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_HEX_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_HEX8_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_HEX16_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_HEX32_WITHIN (delta, expected, actual)` +##### `TEST_ASSERT_HEX64_WITHIN (delta, expected, actual)` + +### Structs and Strings +##### `TEST_ASSERT_EQUAL_PTR (expected, actual)` +Asserts that the pointers point to the same memory location. + +##### `TEST_ASSERT_EQUAL_STRING (expected, actual)` +Asserts that the null terminated (`‘\0'`)strings are identical. If strings are +of different lengths or any portion of the strings before their terminators +differ, the assertion fails. Two NULL strings (i.e. zero length) are considered +equivalent. + +##### `TEST_ASSERT_EQUAL_MEMORY (expected, actual, len)` +Asserts that the contents of the memory specified by the `expected` and `actual` +pointers is identical. The size of the memory blocks in bytes is specified by +the `len` parameter. + +### Arrays +`expected` and `actual` parameters are both arrays. `num_elements` specifies the +number of elements in the arrays to compare. + +`_HEX` assertions produce failure messages with expected and actual array +contents formatted in hexadecimal. + +For array of strings comparison behavior, see comments for +`TEST_ASSERT_EQUAL_STRING` in the preceding section. + +Assertions fail upon the first element in the compared arrays found not to +match. Failure messages specify the array index of the failed comparison. + +##### `TEST_ASSERT_EQUAL_INT_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_INT8_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_INT16_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_INT32_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_INT64_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_UINT_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_UINT8_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_UINT16_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_UINT32_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_UINT64_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_HEX_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_HEX8_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_HEX16_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_HEX32_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_HEX64_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_PTR_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_STRING_ARRAY (expected, actual, num_elements)` +##### `TEST_ASSERT_EQUAL_MEMORY_ARRAY (expected, actual, len, num_elements)` +`len` is the memory in bytes to be compared at each array element. + +### Floating Point (If enabled) +##### `TEST_ASSERT_FLOAT_WITHIN (delta, expected, actual)` +Asserts that the `actual` value is within +/- `delta` of the `expected` value. +The nature of floating point representation is such that exact evaluations of +equality are not guaranteed. + +##### `TEST_ASSERT_EQUAL_FLOAT (expected, actual)` +Asserts that the ?actual?value is "close enough to be considered equal" to the +`expected` value. If you are curious about the details, refer to the Advanced +Asserting section for more details on this. Omitting a user-specified delta in a +floating point assertion is both a shorthand convenience and a requirement of +code generation conventions for CMock. + +##### `TEST_ASSERT_EQUAL_FLOAT_ARRAY (expected, actual, num_elements)` +See Array assertion section for details. Note that individual array element +float comparisons are executed using T?EST_ASSERT_EQUAL_FLOAT?.That is, user +specified delta comparison values requires a custom-implemented floating point +array assertion. + +##### `TEST_ASSERT_FLOAT_IS_INF (actual)` +Asserts that `actual` parameter is equivalent to positive infinity floating +point representation. + +##### `TEST_ASSERT_FLOAT_IS_NEG_INF (actual)` +Asserts that `actual` parameter is equivalent to negative infinity floating +point representation. + +##### `TEST_ASSERT_FLOAT_IS_NAN (actual)` +Asserts that `actual` parameter is a Not A Number floating point representation. + +##### `TEST_ASSERT_FLOAT_IS_DETERMINATE (actual)` +Asserts that ?actual?parameter is a floating point representation usable for +mathematical operations. That is, the `actual` parameter is neither positive +infinity nor negative infinity nor Not A Number floating point representations. + +##### `TEST_ASSERT_FLOAT_IS_NOT_INF (actual)` +Asserts that `actual` parameter is a value other than positive infinity floating +point representation. + +##### `TEST_ASSERT_FLOAT_IS_NOT_NEG_INF (actual)` +Asserts that `actual` parameter is a value other than negative infinity floating +point representation. + +##### `TEST_ASSERT_FLOAT_IS_NOT_NAN (actual)` +Asserts that `actual` parameter is a value other than Not A Number floating +point representation. + +##### `TEST_ASSERT_FLOAT_IS_NOT_DETERMINATE (actual)` +Asserts that `actual` parameter is not usable for mathematical operations. That +is, the `actual` parameter is either positive infinity or negative infinity or +Not A Number floating point representations. + +### Double (If enabled) +##### `TEST_ASSERT_DOUBLE_WITHIN (delta, expected, actual)` +Asserts that the `actual` value is within +/- `delta` of the `expected` value. +The nature of floating point representation is such that exact evaluations of +equality are not guaranteed. + +##### `TEST_ASSERT_EQUAL_DOUBLE (expected, actual)` +Asserts that the `actual` value is "close enough to be considered equal" to the +`expected` value. If you are curious about the details, refer to the Advanced +Asserting section for more details. Omitting a user-specified delta in a +floating point assertion is both a shorthand convenience and a requirement of +code generation conventions for CMock. + +##### `TEST_ASSERT_EQUAL_DOUBLE_ARRAY (expected, actual, num_elements)` +See Array assertion section for details. Note that individual array element +double comparisons are executed using `TEST_ASSERT_EQUAL_DOUBLE`.That is, user +specified delta comparison values requires a custom­implemented double array +assertion. + +##### `TEST_ASSERT_DOUBLE_IS_INF (actual)` +Asserts that `actual` parameter is equivalent to positive infinity floating +point representation. + +##### `TEST_ASSERT_DOUBLE_IS_NEG_INF (actual)` +Asserts that `actual` parameter is equivalent to negative infinity floating point +representation. + +##### `TEST_ASSERT_DOUBLE_IS_NAN (actual)` +Asserts that `actual` parameter is a Not A Number floating point representation. + +##### `TEST_ASSERT_DOUBLE_IS_DETERMINATE (actual)` +Asserts that `actual` parameter is a floating point representation usable for +mathematical operations. That is, the ?actual?parameter is neither positive +infinity nor negative infinity nor Not A Number floating point representations. + +##### `TEST_ASSERT_DOUBLE_IS_NOT_INF (actual)` +Asserts that `actual` parameter is a value other than positive infinity floating +point representation. + +##### `TEST_ASSERT_DOUBLE_IS_NOT_NEG_INF (actual)` +Asserts that `actual` parameter is a value other than negative infinity floating +point representation. + +##### `TEST_ASSERT_DOUBLE_IS_NOT_NAN (actual)` +Asserts that `actual` parameter is a value other than Not A Number floating +point representation. + +##### `TEST_ASSERT_DOUBLE_IS_NOT_DETERMINATE (actual)` +Asserts that `actual` parameter is not usable for mathematical operations. That +is, the `actual` parameter is either positive infinity or negative infinity or +Not A Number floating point representations. + +## Advanced Asserting: Details On Tricky Assertions +This section helps you understand how to deal with some of the trickier +assertion situations you may run into. It will give you a glimpse into some of +the under-the-hood details of Unity's assertion mechanisms. If you're one of +those people who likes to know what is going on in the background, read on. If +not, feel free to ignore the rest of this document until you need it. + +### How do the EQUAL assertions work for FLOAT and DOUBLE? +As you may know, directly checking for equality between a pair of floats or a +pair of doubles is sloppy at best and an outright no-no at worst. Floating point +values can often be represented in multiple ways, particularly after a series of +operations on a value. Initializing a variable to the value of 2.0 is likely to +result in a floating point representation of 2 x 20,but a series of +mathematical operations might result in a representation of 8 x 2-2 +that also evaluates to a value of 2. At some point repeated operations cause +equality checks to fail. + +So Unity doesn't do direct floating point comparisons for equality. Instead, it +checks if two floating point values are "really close." If you leave Unity +running with defaults, "really close" means "within a significant bit or two." +Under the hood, `TEST_ASSERT_EQUAL_FLOAT` is really `TEST_ASSERT_FLOAT_WITHIN` +with the `delta` parameter calculated on the fly. For single precision, delta is +the expected value multiplied by 0.00001, producing a very small proportional +range around the expected value. + +If you are expecting a value of 20,000.0 the delta is calculated to be 0.2. So +any value between 19,999.8 and 20,000.2 will satisfy the equality check. This +works out to be roughly a single bit of range for a single-precision number, and +that's just about as tight a tolerance as you can reasonably get from a floating +point value. + +So what happens when it's zero? Zero - even more than other floating point +values - can be represented many different ways. It doesn't matter if you have +0 x 20or 0 x 263.It's still zero, right? Luckily, if you +subtract these values from each other, they will always produce a difference of +zero, which will still fall between 0 plus or minus a delta of 0. So it still +works! + +Double precision floating point numbers use a much smaller multiplier, again +approximating a single bit of error. + +If you don't like these ranges and you want to make your floating point equality +assertions less strict, you can change these multipliers to whatever you like by +defining UNITY_FLOAT_PRECISION and UNITY_DOUBLE_PRECISION. See Unity +documentation for more. + +### How do we deal with targets with non-standard int sizes? +It's "fun" that C is a standard where something as fundamental as an integer +varies by target. According to the C standard, an `int` is to be the target's +natural register size, and it should be at least 16-bits and a multiple of a +byte. It also guarantees an order of sizes: + +```C +char <= short <= int <= long <= long long +``` + +Most often, `int` is 32-bits. In many cases in the embedded world, `int` is +16-bits. There are rare microcontrollers out there that have 24-bit integers, +and this remains perfectly standard C. + +To make things even more interesting, there are compilers and targets out there +that have a hard choice to make. What if their natural register size is 10-bits +or 12-bits? Clearly they can't fulfill _both_ the requirement to be at least +16-bits AND the requirement to match the natural register size. In these +situations, they often choose the natural register size, leaving us with +something like this: + +```C +char (8 bit) <= short (12 bit) <= int (12 bit) <= long (16 bit) +``` + +Um... yikes. It's obviously breaking a rule or two... but they had to break SOME +rules, so they made a choice. + +When the C99 standard rolled around, it introduced alternate standard-size types. +It also introduced macros for pulling in MIN/MAX values for your integer types. +It's glorious! Unfortunately, many embedded compilers can't be relied upon to +use the C99 types (Sometimes because they have weird register sizes as described +above. Sometimes because they don't feel like it?). + +A goal of Unity from the beginning was to support every combination of +microcontroller or microprocessor and C compiler. Over time, we've gotten really +close to this. There are a few tricks that you should be aware of, though, if +you're going to do this effectively on some of these more idiosyncratic targets. + +First, when setting up Unity for a new target, you're going to want to pay +special attention to the macros for automatically detecting types +(where available) or manually configuring them yourself. You can get information +on both of these in Unity's documentation. + +What about the times where you suddenly need to deal with something odd, like a +24-bit `int`? The simplest solution is to use the next size up. If you have a +24-bit `int`, configure Unity to use 32-bit integers. If you have a 12-bit +`int`, configure Unity to use 16 bits. There are two ways this is going to +affect you: + +1. When Unity displays errors for you, it's going to pad the upper unused bits +with zeros. +2. You're going to have to be careful of assertions that perform signed +operations, particularly `TEST_ASSERT_INT_WITHIN`.Such assertions might wrap +your `int` in the wrong place, and you could experience false failures. You can +always back down to a simple `TEST_ASSERT` and do the operations yourself. \ No newline at end of file diff --git a/docs/UnityConfigurationGuide.md b/docs/UnityConfigurationGuide.md new file mode 100644 index 0000000000000000000000000000000000000000..0a0c0ab96bd48bab61aea48e3c20a184e54e7f8b --- /dev/null +++ b/docs/UnityConfigurationGuide.md @@ -0,0 +1,340 @@ +# Unity Configuration Guide + +## C Standards, Compilers and Microcontrollers +The embedded software world contains its challenges. Compilers support different +revisions of the C Standard. They ignore requirements in places, sometimes to +make the language more usable in some special regard. Sometimes it's to simplify +their support. Sometimes it's due to specific quirks of the microcontroller they +are targeting. Simulators add another dimension to this menagerie. + +Unity is designed to run on almost anything that is targeted by a C compiler. It +would be awesome if this could be done with zero configuration. While there are +some targets that come close to this dream, it is sadly not universal. It is +likely that you are going to need at least a couple of the configuration options +described in this document. + +All of Unity's configuration options are `#defines`. Most of these are simple +definitions. A couple are macros with arguments. They live inside the +unity_internals.h header file. We don't necessarily recommend opening that file +unless you really need to. That file is proof that a cross-platform library is +challenging to build. From a more positive perspective, it is also proof that a +great deal of complexity can be centralized primarily to one place in order to +provide a more consistent and simple experience elsewhere. + +### Using These Options +It doesn't matter if you're using a target-specific compiler and a simulator or +a native compiler. In either case, you've got a couple choices for configuring +these options: + +1. Because these options are specified via C defines, you can pass most of these +options to your compiler through command line compiler flags. Even if you're +using an embedded target that forces you to use their overbearing IDE for all +configuration, there will be a place somewhere in your project to configure +defines for your compiler. +2. You can create a custom `unity_config.h` configuration file (present in your +toolchain's search paths). In this file, you will list definitions and macros +specific to your target. All you must do is define `UNITY_INCLUDE_CONFIG_H` and +Unity will rely on `unity_config.h` for any further definitions it may need. + +## The Options + +### Integer Types +If you've been a C developer for long, you probably already know that C's +concept of an integer varies from target to target. The C Standard has rules +about the `int` matching the register size of the target microprocessor. It has +rules about the `int` and how its size relates to other integer types. An `int` +on one target might be 16 bits while on another target it might be 64. There are +more specific types in compilers compliant with C99 or later, but that's +certainly not every compiler you are likely to encounter. Therefore, Unity has a +number of features for helping to adjust itself to match your required integer +sizes. It starts off by trying to do it automatically. + +##### `UNITY_EXCLUDE_STDINT_H` +The first thing that Unity does to guess your types is check `stdint.h`. +This file includes defines like `UINT_MAX` that Unity can make use of to +learn a lot about your system. It's possible you don't want it to do this +(um. why not?) or (more likely) it's possible that your system doesn't +support `stdint.h`. If that's the case, you're going to want to define this. +That way, Unity will know to skip the inclusion of this file and you won't +be left with a compiler error. + +_Example:_ + #define UNITY_EXCLUDE_STDINT_H + +##### `UNITY_EXCLUDE_LIMITS_H` +The second attempt to guess your types is to check `limits.h`. Some compilers +that don't support `stdint.h` could include `limits.h` instead. If you don't +want Unity to check this file either, define this to make it skip the inclusion. + +_Example:_ + #define UNITY_EXCLUDE_LIMITS_H + +##### `UNITY_EXCLUDE_SIZEOF` +The third and final attempt to guess your types is to use the `sizeof()` +operator. Even if the first two options don't work, this one covers most cases. +There _is_ a rare compiler or two out there that doesn't support sizeof() in the +preprocessing stage, though. For these, you have the ability to disable this +feature as well. + +_Example:_ + #define UNITY_EXCLUDE_SIZEOF + +If you've disabled all of the automatic options above, you're going to have to +do the configuration yourself. Don't worry. Even this isn't too bad... there are +just a handful of defines that you are going to specify if you don't like the +defaults. + +##### `UNITY_INT_WIDTH` +Define this to be the number of bits an `int` takes up on your system. The +default, if not autodetected, is 32 bits. + +_Example:_ + #define UNITY_INT_WIDTH 16 + +##### `UNITY_LONG_WIDTH` +Define this to be the number of bits a `long` takes up on your system. The +default, if not autodetected, is 32 bits. This is used to figure out what kind +of 64-bit support your system can handle. Does it need to specify a `long` or a +`long long` to get a 64-bit value. On 16-bit systems, this option is going to be +ignored. + +_Example:_ + #define UNITY_LONG_WIDTH 16 + +##### `UNITY_POINTER_WIDTH` +Define this to be the number of bits a pointer takes up on your system. The +default, if not autodetected, is 32-bits. If you're getting ugly compiler +warnings about casting from pointers, this is the one to look at. + +_Example:_ + #define UNITY_POINTER_WIDTH 64 + +##### `UNITY_INCLUDE_64` +Unity will automatically include 64-bit support if it auto-detects it, or if +your `int`, `long`, or pointer widths are greater than 32-bits. Define this to +enable 64-bit support if none of the other options already did it for you. There +can be a significant size and speed impact to enabling 64-bit support on small +targets, so don't define it if you don't need it. + +_Example:_ + #define UNITY_INCLUDE_64 + +### Floating Point Types +In the embedded world, it's not uncommon for targets to have no support for +floating point operations at all or to have support that is limited to only +single precision. We are able to guess integer sizes on the fly because integers +are always available in at least one size. Floating point, on the other hand, is +sometimes not available at all. Trying to include `float.h` on these platforms +would result in an error. This leaves manual configuration as the only option. + +##### `UNITY_INCLUDE_FLOAT` +##### `UNITY_EXCLUDE_FLOAT` +##### `UNITY_INCLUDE_DOUBLE` +##### `UNITY_EXCLUDE_DOUBLE` +By default, Unity guesses that you will want single precision floating point +support, but not double precision. It's easy to change either of these using the +include and exclude options here. You may include neither, either, or both, as +suits your needs. For features that are enabled, the following floating point +options also become available. + +_Example:_ + + //what manner of strange processor is this? + #define UNITY_EXCLUDE_FLOAT + #define UNITY_INCLUDE_DOUBLE + +##### `UNITY_FLOAT_VERBOSE` +##### `UNITY_DOUBLE_VERBOSE` +Unity aims for as small of a footprint as possible and avoids most standard +library calls (some embedded platforms don't have a standard library!). Because +of this, its routines for printing integer values are minimalist and hand-coded. +To keep Unity universal, though, we chose to _not_ develop our own floating +point print routines. Instead, the display of floating point values during a +failure are optional. By default, Unity will not print the actual results of +floating point assertion failure. So a failed assertion will produce a message +like `"Values Not Within Delta"`. If you would like verbose failure messages for +floating point assertions, use these options to give more explicit failure +messages (e.g. `"Expected 4.56 Was 4.68"`). Note that this feature requires the +use of `sprintf` so might not be desirable in all cases. + +_Example:_ + #define UNITY_DOUBLE_VERBOSE + +##### `UNITY_FLOAT_TYPE` +If enabled, Unity assumes you want your `FLOAT` asserts to compare standard C +floats. If your compiler supports a specialty floating point type, you can +always override this behavior by using this definition. + +_Example:_ + #define UNITY_FLOAT_TYPE float16_t + +##### `UNITY_DOUBLE_TYPE` +If enabled, Unity assumes you want your `DOUBLE` asserts to compare standard C +doubles. If you would like to change this, you can specify something else by +using this option. For example, defining `UNITY_DOUBLE_TYPE` to `long double` +could enable gargantuan floating point types on your 64-bit processor instead of +the standard `double`. + +_Example:_ + #define UNITY_DOUBLE_TYPE long double + +##### `UNITY_FLOAT_PRECISION` +##### `UNITY_DOUBLE_PRECISION` +If you look up `UNITY_ASSERT_EQUAL_FLOAT` and `UNITY_ASSERT_EQUAL_DOUBLE` as +documented in the big daddy Unity Assertion Guide, you will learn that they are +not really asserting that two values are equal but rather that two values are +"close enough" to equal. "Close enough" is controlled by these precision +configuration options. If you are working with 32-bit floats and/or 64-bit +doubles (the normal on most processors), you should have no need to change these +options. They are both set to give you approximately 1 significant bit in either +direction. The float precision is 0.00001 while the double is 10-12. +For further details on how this works, see the appendix of the Unity Assertion +Guide. + +_Example:_ + #define UNITY_FLOAT_PRECISION 0.001f + +### Toolset Customization +In addition to the options listed above, there are a number of other options +which will come in handy to customize Unity's behavior for your specific +toolchain. It is possible that you may not need to touch any of these... but +certain platforms, particularly those running in simulators, may need to jump +through extra hoops to operate properly. These macros will help in those +situations. + +##### `UNITY_OUTPUT_CHAR(a)` +##### `UNITY_OUTPUT_FLUSH()` +##### `UNITY_OUTPUT_START()` +##### `UNITY_OUTPUT_COMPLETE()` +By default, Unity prints its results to `stdout` as it runs. This works +perfectly fine in most situations where you are using a native compiler for +testing. It works on some simulators as well so long as they have `stdout` +routed back to the command line. There are times, however, where the simulator +will lack support for dumping results or you will want to route results +elsewhere for other reasons. In these cases, you should define the +`UNITY_OUTPUT_CHAR` macro. This macro accepts a single character at a time (as +an `int`, since this is the parameter type of the standard C `putchar` function +most commonly used). You may replace this with whatever function call you like. + +_Example:_ +Say you are forced to run your test suite on an embedded processor with no +`stdout` option. You decide to route your test result output to a custom serial +`RS232_putc()` function you wrote like thus: + + #define UNITY_OUTPUT_CHAR(a) RS232_putc(a) + #define UNITY_OUTPUT_START() RS232_config(115200,1,8,0) + #define UNITY_OUTPUT_FLUSH() RS232_flush() + #define UNITY_OUTPUT_COMPLETE() RS232_close() + +_Note:_ +`UNITY_OUTPUT_FLUSH()` can be set to the standard out flush function simply by +specifying `UNITY_USE_FLUSH_STDOUT`. No other defines are required. If you +specify a custom flush function instead with `UNITY_OUTPUT_FLUSH` directly, it +will declare an instance of your function by default. If you want to disable +this behavior, add `UNITY_OMIT_OUTPUT_FLUSH_HEADER_DECLARATION`. + +##### `UNITY_SUPPORT_WEAK` +For some targets, Unity can make the otherwise required `setUp()` and +`tearDown()` functions optional. This is a nice convenience for test writers +since `setUp` and `tearDown` don't often actually _do_ anything. If you're using +gcc or clang, this option is automatically defined for you. Other compilers can +also support this behavior, if they support a C feature called weak functions. A +weak function is a function that is compiled into your executable _unless_ a +non-weak version of the same function is defined elsewhere. If a non-weak +version is found, the weak version is ignored as if it never existed. If your +compiler supports this feature, you can let Unity know by defining +`UNITY_SUPPORT_WEAK` as the function attributes that would need to be applied to +identify a function as weak. If your compiler lacks support for weak functions, +you will always need to define `setUp` and `tearDown` functions (though they can +be and often will be just empty). The most common options for this feature are: + +_Example:_ + #define UNITY_SUPPORT_WEAK weak + #define UNITY_SUPPORT_WEAK __attribute__((weak)) + +##### `UNITY_PTR_ATTRIBUTE` +Some compilers require a custom attribute to be assigned to pointers, like +`near` or `far`. In these cases, you can give Unity a safe default for these by +defining this option with the attribute you would like. + +_Example:_ + #define UNITY_PTR_ATTRIBUTE __attribute__((far)) + #define UNITY_PTR_ATTRIBUTE near + +## Getting Into The Guts +There will be cases where the options above aren't quite going to get everything +perfect. They are likely sufficient for any situation where you are compiling +and executing your tests with a native toolchain (e.g. clang on Mac). These +options may even get you through the majority of cases encountered in working +with a target simulator run from your local command line. But especially if you +must run your test suite on your target hardware, your Unity configuration will +require special help. This special help will usually reside in one of two +places: the `main()` function or the `RUN_TEST` macro. Let's look at how these +work. + +##### `main()` +Each test module is compiled and run on its own, separate from the other test +files in your project. Each test file, therefore, has a `main` function. This +`main` function will need to contain whatever code is necessary to initialize +your system to a workable state. This is particularly true for situations where +you must set up a memory map or initialize a communication channel for the +output of your test results. + +A simple main function looks something like this: + + int main(void) { + UNITY_BEGIN(); + RUN_TEST(test_TheFirst); + RUN_TEST(test_TheSecond); + RUN_TEST(test_TheThird); + return UNITY_END(); + } + +You can see that our main function doesn't bother taking any arguments. For our +most barebones case, we'll never have arguments because we just run all the +tests each time. Instead, we start by calling `UNITY_BEGIN`. We run each test +(in whatever order we wish). Finally, we call `UNITY_END`, returning its return +value (which is the total number of failures). + +It should be easy to see that you can add code before any test cases are run or +after all the test cases have completed. This allows you to do any needed +system-wide setup or teardown that might be required for your special +circumstances. + +##### `RUN_TEST` +The `RUN_TEST` macro is called with each test case function. Its job is to +perform whatever setup and teardown is necessary for executing a single test +case function. This includes catching failures, calling the test module's +`setUp()` and `tearDown()` functions, and calling `UnityConcludeTest()`. If +using CMock or test coverage, there will be additional stubs in use here. A +simple minimalist RUN_TEST macro looks something like this: + + #define RUN_TEST(testfunc) \ + UNITY_NEW_TEST(#testfunc) \ + if (TEST_PROTECT()) { \ + setUp(); \ + testfunc(); \ + } \ + if (TEST_PROTECT() && (!TEST_IS_IGNORED)) \ + tearDown(); \ + UnityConcludeTest(); + +So that's quite a macro, huh? It gives you a glimpse of what kind of stuff Unity +has to deal with for every single test case. For each test case, we declare that +it is a new test. Then we run `setUp` and our test function. These are run +within a `TEST_PROTECT` block, the function of which is to handle failures that +occur during the test. Then, assuming our test is still running and hasn't been +ignored, we run `tearDown`. No matter what, our last step is to conclude this +test before moving on to the next. + +Let's say you need to add a call to `fsync` to force all of your output data to +flush to a file after each test. You could easily insert this after your +`UnityConcludeTest` call. Maybe you want to write an xml tag before and after +each result set. Again, you could do this by adding lines to this macro. Updates +to this macro are for the occasions when you need an action before or after +every single test case throughout your entire suite of tests. + +## Happy Porting +The defines and macros in this guide should help you port Unity to just about +any C target we can imagine. If you run into a snag or two, don't be afraid of +asking for help on the forums. We love a good challenge! \ No newline at end of file diff --git a/docs/UnityGettingStartedGuide.md b/docs/UnityGettingStartedGuide.md new file mode 100644 index 0000000000000000000000000000000000000000..a1183310b52d14533e66c2166c75f36cb98e020a --- /dev/null +++ b/docs/UnityGettingStartedGuide.md @@ -0,0 +1,171 @@ +# Unity - Getting Started + +## Welcome +Congratulations. You're now the proud owner of your very own pile of bits! What +are you going to do with all these ones and zeros? This document should be able +to help you decide just that. + +Unity is a unit test framework. The goal has been to keep it small and +functional. The core Unity test framework is three files: a single C file and a +couple header files. These team up to provide functions and macros to make +testing easier. + +Unity was designed to be cross platform. It works hard to stick with C standards +while still providing support for the many embedded C compilers that bend the +rules. Unity has been used with many compilers, including GCC, IAR, Clang, +Green Hills, Microchip, and MS Visual Studio. It's not much work to get it to +work with a new target. + +### Overview of the Documents + +#### Unity Assertions reference +This document will guide you through all the assertion options provided by +Unity. This is going to be your unit testing bread and butter. You'll spend more +time with assertions than any other part of Unity. + +#### Unity Assertions Cheat Sheet +This document contains an abridged summary of the assertions described in the +previous document. It's perfect for printing and referencing while you +familiarize yourself with Unity's options. + +#### Unity Configuration Guide +This document is the one to reference when you are going to use Unity with a new +target or compiler. It'll guide you through the configuration options and will +help you customize your testing experience to meet your needs. + +#### Unity Helper Scripts +This document describes the helper scripts that are available for simplifying +your testing workflow. It describes the collection of optional Ruby scripts +included in the auto directory of your Unity installation. Neither Ruby nor +these scripts are necessary for using Unity. They are provided as a convenience +for those who wish to use them. + +#### Unity License +What's an open source project without a license file? This brief document +describes the terms you're agreeing to when you use this software. Basically, we +want it to be useful to you in whatever context you want to use it, but please +don't blame us if you run into problems. + +### Overview of the Folders +If you have obtained Unity through Github or something similar, you might be +surprised by just how much stuff you suddenly have staring you in the face. +Don't worry, Unity itself is very small. The rest of it is just there to make +your life easier. You can ignore it or use it at your convenience. Here's an +overview of everything in the project. + +- `src` — This is the code you care about! This folder contains a C file and two +header files. These three files _are_ Unity. +- `docs` — You're reading this document, so it's possible you have found your way +into this folder already. This is where all the handy documentation can be +found. +- `examples` — This contains a few examples of using Unity. +- `extras` — These are optional add ons to Unity that are not part of the core +project. If you've reached us through James Grenning's book, you're going to +want to look here. +- `test` — This is how Unity and its scripts are all tested. If you're just using +Unity, you'll likely never need to go in here. If you are the lucky team member +who gets to port Unity to a new toolchain, this is a good place to verify +everything is configured properly. +- `auto` — Here you will find helpful Ruby scripts for simplifying your test +workflow. They are purely optional and are not required to make use of Unity. + +## How to Create A Test File +Test files are C files. Most often you will create a single test file for each C +module that you want to test. The test file should include unity.h and the +header for your C module to be tested. + +Next, a test file will include a `setUp()` and `tearDown()` function. The setUp +function can contain anything you would like to run before each test. The +tearDown function can contain anything you would like to run after each test. +Both functions accept no arguments and return nothing. You may leave either or +both of these blank if you have no need for them. If you're using a compiler +that is configured to make these functions optional, you may leave them off +completely. Not sure? Give it a try. If you compiler complains that it can't +find setUp or tearDown when it links, you'll know you need to at least include +an empty function for these. + +The majority of the file will be a series of test functions. Test functions +follow the convention of starting with the word "test" or "spec". You don't HAVE +to name them this way, but it makes it clear what functions are tests for other +developers. Test functions take no arguments and return nothing. All test +accounting is handled internally in Unity. + +Finally, at the bottom of your test file, you will write a `main()` function. +This function will call `UNITY_BEGIN()`, then `RUN_TEST` for each test, and +finally `UNITY_END()`.This is what will actually trigger each of those test +functions to run, so it is important that each function gets its own `RUN_TEST` +call. + +Remembering to add each test to the main function can get to be tedious. If you +enjoy using helper scripts in your build process, you might consider making use +of our handy generate_test_runner.rb script. This will create the main function +and all the calls for you, assuming that you have followed the suggested naming +conventions. In this case, there is no need for you to include the main function +in your test file at all. + +When you're done, your test file will look something like this: + +```C +#include "unity.h" +#include "file_to_test.h" + +void setUp(void) { + // set stuff up here +} + +void tearDown(void) { + // clean stuff up here +} + +void test_function_should_doBlahAndBlah(void) { + //test stuff +} + +void test_function_should_doAlsoDoBlah(void) { + //more test stuff +} + +int main(void) { + UNITY_BEGIN(); + RUN_TEST(test_function_should_doBlahAndBlah); + RUN_TEST(test_function_should_doAlsoDoBlah); + return UNITY_END(); +} +``` + +It's possible that you will require more customization than this, eventually. +For that sort of thing, you're going to want to look at the configuration guide. +This should be enough to get you going, though. + +## How to Build and Run A Test File +This is the single biggest challenge to picking up a new unit testing framework, +at least in a language like C or C++. These languages are REALLY good at getting +you "close to the metal" (why is the phrase metal? Wouldn't it be more accurate +to say "close to the silicon"?). While this feature is usually a good thing, it +can make testing more challenging. + +You have two really good options for toolchains. Depending on where you're +coming from, it might surprise you that neither of these options is running the +unit tests on your hardware. +There are many reasons for this, but here's a short version: +- On hardware, you have too many constraints (processing power, memory, etc), +- On hardware, you don't have complete control over all registers, +- On hardware, unit testing is more challenging, +- Unit testing isn't System testing. Keep them separate. + +Instead of running your tests on your actual hardware, most developers choose to +develop them as native applications (using gcc or MSVC for example) or as +applications running on a simulator. Either is a good option. Native apps have +the advantages of being faster and easier to set up. Simulator apps have the +advantage of working with the same compiler as your target application. The +options for configuring these are discussed in the configuration guide. + +To get either to work, you might need to make a few changes to the file +containing your register set (discussed later). + +In either case, a test is built by linking unity, the test file, and the C +file(s) being tested. These files create an executable which can be run as the +test set for that module. Then, this process is repeated for the next test file. +This flexibility of separating tests into individual executables allows us to +much more thoroughly unit test our system and it keeps all the test code out of +our final release! diff --git a/docs/UnityHelperScriptsGuide.md b/docs/UnityHelperScriptsGuide.md new file mode 100644 index 0000000000000000000000000000000000000000..0ea498c2dcbe63443790f45bb03492418bbd3aab --- /dev/null +++ b/docs/UnityHelperScriptsGuide.md @@ -0,0 +1,222 @@ +# Unity Helper Scripts +## With a Little Help From Our Friends +Sometimes what it takes to be a really efficient C programmer is a little non-C. +The Unity project includes a couple Ruby scripts for making your life just a tad +easier. They are completely optional. If you choose to use them, you'll need a +copy of Ruby, of course. Just install whatever the latest version is, and it is +likely to work. You can find Ruby at [ruby-lang.org](https://ruby-labg.org/). + +### `generate_test_runner.rb` +Are you tired of creating your own `main` function in your test file? Do you +keep forgetting to add a `RUN_TEST` call when you add a new test case to your +suite? Do you want to use CMock or other fancy add-ons but don't want to figure +out how to create your own `RUN_TEST` macro? + +Well then we have the perfect script for you! + +The `generate_test_runner` script processes a given test file and automatically +creates a separate test runner file that includes ?main?to execute the test +cases within the scanned test file. All you do then is add the generated runner +to your list of files to be compiled and linked, and presto you're done! + +This script searches your test file for void function signatures having a +function name beginning with "test" or "spec". It treats each of these +functions as a test case and builds up a test suite of them. For example, the +following includes three test cases: + +```C +void testVerifyThatUnityIsAwesomeAndWillMakeYourLifeEasier(void) +{ + ASSERT_TRUE(1); +} +void test_FunctionName_should_WorkProperlyAndReturn8(void) { + ASSERT_EQUAL_INT(8, FunctionName()); +} +void spec_Function_should_DoWhatItIsSupposedToDo(void) { + ASSERT_NOT_NULL(Function(5)); +} +``` + +You can run this script a couple of ways. The first is from the command line: + +```Shell +ruby generate_test_runner.rb TestFile.c NameOfRunner.c +``` + +Alternatively, if you include only the test file parameter, the script will copy +the name of the test file and automatically append "_Runner" to the name of the +generated file. The example immediately below will create TestFile_Runner.c. + +```Shell +ruby generate_test_runner.rb TestFile.c +``` + +You can also add a [YAML](http://www.yaml.org/) file to configure extra options. +Conveniently, this YAML file is of the same format as that used by Unity and +CMock. So if you are using YAML files already, you can simply pass the very same +file into the generator script. + +```Shell +ruby generate_test_runner.rb TestFile.c my_config.yml +``` + +The contents of the YAML file `my_config.yml` could look something like the +example below. If you're wondering what some of these options do, you're going +to love the next section of this document. + +```YAML +:unity: + :includes: + - stdio.h + - microdefs.h + :cexception: 1 + :suit_setup: "blah = malloc(1024);" + :suite_teardown: "free(blah);" +``` + +If you would like to force your generated test runner to include one or more +header files, you can just include those at the command line too. Just make sure +these are _after_ the YAML file, if you are using one: + +```Shell +ruby generate_test_runner.rb TestFile.c my_config.yml extras.h +``` + +Another option, particularly if you are already using Ruby to orchestrate your +builds - or more likely the Ruby-based build tool Rake - is requiring this +script directly. Anything that you would have specified in a YAML file can be +passed to the script as part of a hash. Let's push the exact same requirement +set as we did above but this time through Ruby code directly: + +```Ruby +require "generate_test_runner.rb" +options = { + :includes => ["stdio.h", "microdefs.h"], + :cexception => 1, + :suite_setup => "blah = malloc(1024);", + :suite_teardown => "free(blah);" +} +UnityTestRunnerGenerator.new.run(testfile, runner_name, options) +``` + +If you have multiple files to generate in a build script (such as a Rakefile), +you might want to instantiate a generator object with your options and call it +to generate each runner thereafter. Like thus: + +```Ruby +gen = UnityTestRunnerGenerator.new(options) +test_files.each do |f| + gen.run(f, File.basename(f,'.c')+"Runner.c" +end +``` + +#### Options accepted by generate_test_runner.rb: +The following options are available when executing `generate_test_runner`. You +may pass these as a Ruby hash directly or specify them in a YAML file, both of +which are described above. In the `examples` directory, Example 3's Rakefile +demonstrates using a Ruby hash. + +##### `:includes` +This option specifies an array of file names to be ?#include?'d at the top of +your runner C file. You might use it to reference custom types or anything else +universally needed in your generated runners. + +##### `:suite_setup` +Define this option with C code to be executed _before any_ test cases are run. + +##### `:suite_teardown` +Define this option with C code to be executed ?after all?test cases have +finished. + +##### `:enforce_strict_ordering` +This option should be defined if you have the strict order feature enabled in +CMock (see CMock documentation). This generates extra variables required for +everything to run smoothly. If you provide the same YAML to the generator as +used in CMock's configuration, you've already configured the generator properly. + +##### `:plugins` +This option specifies an array of plugins to be used (of course, the array can +contain only a single plugin). This is your opportunity to enable support for +CException support, which will add a check for unhandled exceptions in each +test, reporting a failure if one is detected. To enable this feature using Ruby: + +```Ruby +:plugins => [ :cexception ] +``` + +Or as a yaml file: + +```YAML +:plugins: + -:cexception +``` + +If you are using CMock, it is very likely that you are already passing an array +of plugins to CMock. You can just use the same array here. This script will just +ignore the plugins that don't require additional support. + +### `unity_test_summary.rb` +A Unity test file contains one or more test case functions. Each test case can +pass, fail, or be ignored. Each test file is run individually producing results +for its collection of test cases. A given project will almost certainly be +composed of multiple test files. Therefore, the suite of tests is comprised of +one or more test cases spread across one or more test files. This script +aggregates individual test file results to generate a summary of all executed +test cases. The output includes how many tests were run, how many were ignored, +and how many failed. In addition, the output includes a listing of which +specific tests were ignored and failed. A good example of the breadth and +details of these results can be found in the `examples` directory. Intentionally +ignored and failing tests in this project generate corresponding entries in the +summary report. + +If you're interested in other (prettier?) output formats, check into the +Ceedling build tool project (ceedling.sourceforge.net) that works with Unity and +CMock and supports xunit-style xml as well as other goodies. + +This script assumes the existence of files ending with the extensions +`.testpass` and `.testfail`.The contents of these files includes the test +results summary corresponding to each test file executed with the extension set +according to the presence or absence of failures for that test file. The script +searches a specified path for these files, opens each one it finds, parses the +results, and aggregates and prints a summary. Calling it from the command line +looks like this: + +```Shell +ruby unity_test_summary.rb build/test/ +``` + +You can optionally specify a root path as well. This is really helpful when you +are using relative paths in your tools' setup, but you want to pull the summary +into an IDE like Eclipse for clickable shortcuts. + +```Shell +ruby unity_test_summary.rb build/test/ ~/projects/myproject/ +``` + +Or, if you're more of a Windows sort of person: + +```Shell +ruby unity_test_summary.rb build\teat\ C:\projects\myproject\ +``` + +When configured correctly, you'll see a final summary, like so: + +```Shell +-------------------------- +UNITY IGNORED TEST SUMMARY +-------------------------- +blah.c:22:test_sandwiches_should_HaveBreadOnTwoSides:IGNORE + +------------------------- +UNITY FAILED TEST SUMMARY +------------------------- +blah.c:87:test_sandwiches_should_HaveCondiments:FAIL:Expected 1 was 0 +meh.c:38:test_soda_should_BeCalledPop:FAIL:Expected "pop" was "coke" + +-------------------------- +OVERALL UNITY TEST SUMMARY +-------------------------- +45 TOTAL TESTS 2 TOTAL FAILURES 1 IGNORED +``` + +How convenient is that?