adding new ceedling test project
This commit is contained in:
hathach
292
test/vendor/ceedling/docs/CException.md
vendored
Normal file
292
test/vendor/ceedling/docs/CException.md
vendored
Normal file
@@ -0,0 +1,292 @@
|
||||
|
||||
CException
|
||||
==========
|
||||
|
||||
CException is a basic exception framework for C, suitable for use in
|
||||
embedded applications. It provides an exception framework similar in
|
||||
use to C++, but with much less overhead.
|
||||
|
||||
|
||||
CException uses C standard library functions `setjmp` and `longjmp` to
|
||||
operate. As long as the target system has these two functions defined,
|
||||
this library should be useable with very little configuration. It
|
||||
even supports environments where multiple program flows are in use,
|
||||
such as real-time operating systems.
|
||||
|
||||
|
||||
There are about a gabillion exception frameworks using a similar
|
||||
setjmp/longjmp method out there... and there will probably be more
|
||||
in the future. Unfortunately, when we started our last embedded
|
||||
project, all those that existed either (a) did not support multiple
|
||||
tasks (therefore multiple stacks) or (b) were way more complex than
|
||||
we really wanted. CException was born.
|
||||
|
||||
|
||||
*Why use CException?*
|
||||
|
||||
|
||||
0. It's ANSI C, and it beats passing error codes around.
|
||||
1. You want something simple... CException throws a single id. You can
|
||||
define those ID's to be whatever you like. You might even choose which
|
||||
type that number is for your project. But that's as far as it goes.
|
||||
We weren't interested in passing objects or structs or strings...
|
||||
just simple error codes.
|
||||
2. Performance... CException can be configured for single tasking or
|
||||
multitasking. In single tasking, there is very little overhead past
|
||||
the setjmp/longjmp calls (which are already fast). In multitasking,
|
||||
your only additional overhead is the time it takes you to determine
|
||||
a unique task id 0 - num_tasks.
|
||||
|
||||
|
||||
For the latest version, go to [ThrowTheSwitch.org](http://throwtheswitch.org)
|
||||
|
||||
|
||||
CONTENTS OF THIS DOCUMENT
|
||||
=========================
|
||||
|
||||
* Usage
|
||||
* Limitations
|
||||
*API
|
||||
* Configuration
|
||||
* Testing
|
||||
* License
|
||||
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Code that is to be protected are wrapped in `Try { } Catch { }` blocks.
|
||||
The code directly following the Try call is "protected", meaning that
|
||||
if any Throws occur, program control is directly transferred to the
|
||||
start of the Catch block.
|
||||
|
||||
|
||||
A numerical exception ID is included with Throw, and is made accessible
|
||||
from the Catch block.
|
||||
|
||||
|
||||
Throws can occur from within function calls (nested as deeply as you
|
||||
like) or directly from within the function itself.
|
||||
|
||||
|
||||
|
||||
Limitations
|
||||
-----------
|
||||
|
||||
|
||||
This library was made to be as fast as possible, and provide basic
|
||||
exception handling. It is not a full-blown exception library. Because
|
||||
of this, there are a few limitations that should be observed in order
|
||||
to successfully utilize this library:
|
||||
|
||||
1. Do not directly "return" from within a `Try` block, nor `goto`
|
||||
into or out of a `Try` block.
|
||||
|
||||
*Why?*
|
||||
|
||||
The `Try` macro allocates some local memory and alters a global
|
||||
pointer. These are cleaned up at the top of the `Catch` macro.
|
||||
Gotos and returns would bypass some of these steps, resulting in
|
||||
memory leaks or unpredictable behavior.
|
||||
|
||||
|
||||
2. If (a) you change local (stack) variables within your `Try` block,
|
||||
AND (b) wish to make use of the updated values after an exception
|
||||
is thrown, those variables should be made `volatile`. Note that this
|
||||
is ONLY for locals and ONLY when you need access to them after a
|
||||
`Throw`.
|
||||
|
||||
*Why?*
|
||||
|
||||
Compilers optimize. There is no way to guarantee that the actual
|
||||
memory location was updated and not just a register unless the
|
||||
variable is marked volatile.
|
||||
|
||||
|
||||
3. Memory which is `malloc`'d or `new`'d is not automatically released
|
||||
when an error is thrown. This will sometimes be desirable, and
|
||||
othertimes may not. It will be the responsibility of the `Catch`
|
||||
block to perform this kind of cleanup.
|
||||
|
||||
*Why?*
|
||||
|
||||
There's just no easy way to track `malloc`'d memory, etc., without
|
||||
replacing or wrapping malloc calls or something like that. This
|
||||
is a light framework, so these options were not desirable.
|
||||
|
||||
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
###Try
|
||||
|
||||
`Try` is a macro which starts a protected block. It MUST be followed by
|
||||
a pair of braces or a single protected line (similar to an 'if'),
|
||||
enclosing the data that is to be protected. It **must** be followed by a
|
||||
`Catch` block (don't worry, you'll get compiler errors to let you know if
|
||||
you mess any of that up).
|
||||
|
||||
|
||||
###Catch(e)
|
||||
|
||||
`Catch` is a macro which ends the `Try` block and starts the error handling
|
||||
block. The `Catch` block is called if and only if an exception was thrown
|
||||
while within the `Try` block. This error was thrown by a `Throw` call
|
||||
somewhere within `Try` (or within a function called within `Try`, or a function
|
||||
called by a function called within `Try`, etc).
|
||||
|
||||
The single parameter `e` is filled with the error code which was thrown.
|
||||
This can be used for reporting, conditional cleanup, etc. (or you can just
|
||||
ignore it if you really want... people ignore return codes all the time,
|
||||
right?). `e` should be of type `EXCEPTION_T`
|
||||
|
||||
|
||||
###Throw(e)
|
||||
|
||||
This is the method of throwing an error. A `Throw` should only occur from within a
|
||||
protected (`Try` ... `Catch`) block, though it may easily be nested many function
|
||||
calls deep without an impact on performance or functionality. `Throw` takes
|
||||
a single argument, which is an exception id which will be passed to `Catch`
|
||||
as the reason for the error.
|
||||
|
||||
If you wish to rethrow an error, this can be done by calling `Throw(e)` with
|
||||
the error code you just caught. It **is** valid to throw from a catch block.
|
||||
|
||||
|
||||
###ExitTry()
|
||||
|
||||
On rare occasion, you might want to immediately exit your current `Try` block
|
||||
but **not** treat this as an error. Don't run the `Catch`. Just start executing
|
||||
from after the `Catch` as if nothing had happened... That's what `ExitTry` is
|
||||
for.
|
||||
|
||||
|
||||
CONFIGURATION
|
||||
-------------
|
||||
|
||||
CException is a mostly portable library. It has one universal
|
||||
dependency, and some macros which are required if working in a
|
||||
multi-tasking environment.
|
||||
|
||||
1. The standard C library setjmp must be available. Since this is part
|
||||
of the standard library, chances are good that you'll be fine.
|
||||
|
||||
2. If working in a multitasking environment, methods for obtaining an
|
||||
index into an array of frames and to get the overall number of
|
||||
id's are required. If the OS supports a method to retrieve Task
|
||||
ID's, and those Tasks are number 0, 1, 2... you are in an ideal
|
||||
situation. Otherwise, a more creative mapping function may be
|
||||
required. Note that this function is likely to be called twice
|
||||
for each protected block and once during a throw. This is the
|
||||
only overhead in the system.
|
||||
|
||||
|
||||
Exception.h
|
||||
-----------
|
||||
|
||||
By convention, most projects include `Exception.h` which defines any
|
||||
further requirements, then calls `CException.h` to do the gruntwork. All
|
||||
of these are optional. You could directly include `CException.h` if
|
||||
you wanted and just use the defaults provided.
|
||||
|
||||
* `EXCEPTION_T`
|
||||
* Set this to the type you want your exception id's to be. Defaults to 'unsigned int'.
|
||||
|
||||
* `EXCEPTION_NONE`
|
||||
* Set this to a number which will never be an exception id in your system. Defaults to `0x5a5a5a5a`.
|
||||
|
||||
* `EXCEPTION_GET_ID`
|
||||
* If in a multi-tasking environment, this should be
|
||||
set to be a call to the function described in #2 above.
|
||||
Defaults to just return `0` all the time (good for
|
||||
single tasking environments)
|
||||
|
||||
* `EXCEPTION_NUM_ID`
|
||||
* If in a multi-tasking environment, this should be set
|
||||
to the number of ID's required (usually the number of
|
||||
tasks in the system). Defaults to `1` (for single
|
||||
tasking environments).
|
||||
|
||||
* `CEXCEPTION_NO_CATCH_HANDLER(id)`
|
||||
* This macro can be optionally specified.
|
||||
It allows you to specify code to be called when a Throw
|
||||
is made outside of `Try` ... `Catch` protection. Consider
|
||||
this the emergency fallback plan for when something has
|
||||
gone terribly wrong.
|
||||
|
||||
|
||||
You may also want to include any header files which will commonly be
|
||||
needed by the rest of your application where it uses exception handling
|
||||
here. For example, OS header files or exception codes would be useful.
|
||||
|
||||
|
||||
Finally, there are some hook macros which you can implement to inject
|
||||
your own target-specific code in particular places. It is a rare instance
|
||||
where you will need these, but they are here if you need them:
|
||||
|
||||
|
||||
* `CEXCEPTION_HOOK_START_TRY`
|
||||
* called immediately before the Try block
|
||||
|
||||
* `CEXCEPTION_HOOK_HAPPY_TRY`
|
||||
* called immediately after the Try block if no exception was thrown
|
||||
|
||||
* `CEXCEPTION_HOOK_AFTER_TRY`
|
||||
* called immediately after the Try block OR before an exception is caught
|
||||
|
||||
* `CEXCEPTION_HOOK_START_CATCH`
|
||||
* called immediately before the catch
|
||||
|
||||
|
||||
|
||||
TESTING
|
||||
-------
|
||||
|
||||
|
||||
If you want to validate that CException works with your tools or that
|
||||
it works with your custom configuration, you may want to run the test
|
||||
suite.
|
||||
|
||||
|
||||
The test suite included makes use of the `Unity` Test Framework. It will
|
||||
require a native C compiler. The example makefile uses MinGW's gcc.
|
||||
Modify the makefile to include the proper paths to tools, then run `make`
|
||||
to compile and run the test application.
|
||||
|
||||
* `C_COMPILER`
|
||||
* The C compiler to use to perform the tests
|
||||
|
||||
* `C_LIBS`
|
||||
* The path to the C libraries (including setjmp)
|
||||
|
||||
* `UNITY_DIR`
|
||||
* The path to the Unity framework (required to run tests)
|
||||
(get it at [ThrowTheSwitch.org](http://throwtheswitch.org))
|
||||
|
||||
|
||||
|
||||
LICENSE
|
||||
-------
|
||||
|
||||
This software is licensed under the MIT License
|
||||
|
||||
Copyright (c) 2007-2017 Mark VanderVoord
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in
|
||||
all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
||||
THE SOFTWARE.
|
||||
603
test/vendor/ceedling/docs/CMock_Summary.md
vendored
Normal file
603
test/vendor/ceedling/docs/CMock_Summary.md
vendored
Normal file
@@ -0,0 +1,603 @@
|
||||
CMock: A Summary
|
||||
================
|
||||
|
||||
*[ThrowTheSwitch.org](http://throwtheswitch.org)*
|
||||
|
||||
*This documentation is released under a Creative Commons 3.0 Attribution Share-Alike License*
|
||||
|
||||
|
||||
What Exactly Are We Talking About Here?
|
||||
---------------------------------------
|
||||
|
||||
CMock is a nice little tool which takes your header files and creates
|
||||
a Mock interface for it so that you can more easily unit test modules
|
||||
that touch other modules. For each function prototype in your
|
||||
header, like this one:
|
||||
|
||||
int DoesSomething(int a, int b);
|
||||
|
||||
|
||||
...you get an automatically generated DoesSomething function
|
||||
that you can link to instead of your real DoesSomething function.
|
||||
By using this Mocked version, you can then verify that it receives
|
||||
the data you want, and make it return whatever data you desire,
|
||||
make it throw errors when you want, and more... Create these for
|
||||
everything your latest real module touches, and you're suddenly
|
||||
in a position of power: You can control and verify every detail
|
||||
of your latest creation.
|
||||
|
||||
To make that easier, CMock also gives you a bunch of functions
|
||||
like the ones below, so you can tell that generated DoesSomething
|
||||
function how to behave for each test:
|
||||
|
||||
void DoesSomething_ExpectAndReturn(int a, int b, int toReturn);
|
||||
void DoesSomething_ExpectAndThrow(int a, int b, EXCEPTION_T error);
|
||||
void DoesSomething_StubWithCallback(CMOCK_DoesSomething_CALLBACK YourCallback);
|
||||
void DoesSomething_IgnoreAndReturn(int toReturn);
|
||||
|
||||
|
||||
You can pile a bunch of these back to back, and it remembers what
|
||||
you wanted to pass when, like so:
|
||||
|
||||
test_CallsDoesSomething_ShouldDoJustThat(void)
|
||||
{
|
||||
DoesSomething_ExpectAndReturn(1,2,3);
|
||||
DoesSomething_ExpectAndReturn(4,5,6);
|
||||
DoesSomething_ExpectAndThrow(7,8, STATUS_ERROR_OOPS);
|
||||
|
||||
CallsDoesSomething( );
|
||||
}
|
||||
|
||||
|
||||
This test will call CallsDoesSomething, which is the function
|
||||
we are testing. We are expecting that function to call DoesSomething
|
||||
three times. The first time, we check to make sure it's called
|
||||
as DoesSomething(1, 2) and we'll magically return a 3. The second
|
||||
time we check for DoesSomething(4, 5) and we'll return a 6. The
|
||||
third time we verify DoesSomething(7, 8) and we'll throw an error
|
||||
instead of returning anything. If CallsDoesSomething gets
|
||||
any of this wrong, it fails the test. It will fail if you didn't
|
||||
call DoesSomething enough, or too much, or with the wrong arguments,
|
||||
or in the wrong order.
|
||||
|
||||
CMock is based on Unity, which it uses for all internal testing.
|
||||
It uses Ruby to do all the main work (versions 2.0.0 and above).
|
||||
|
||||
|
||||
Installing
|
||||
==========
|
||||
|
||||
The first thing you need to do to install CMock is to get yourself
|
||||
a copy of Ruby. If you're on linux or osx, you probably already
|
||||
have it. You can prove it by typing the following:
|
||||
|
||||
ruby --version
|
||||
|
||||
|
||||
If it replied in a way that implies ignorance, then you're going to
|
||||
need to install it. You can go to [ruby-lang](https://ruby-lang.org)
|
||||
to get the latest version. You're also going to need to do that if it
|
||||
replied with a version that is older than 2.0.0. Go ahead. We'll wait.
|
||||
|
||||
Once you have Ruby, you have three options:
|
||||
|
||||
* Clone the latest [CMock repo on github](https://github.com/ThrowTheSwitch/CMock/)
|
||||
* Download the latest [CMock zip from github](https://github.com/ThrowTheSwitch/CMock/)
|
||||
* Install Ceedling (which has it built in!) through your commandline using `gem install ceedling`.
|
||||
|
||||
|
||||
Generated Mock Module Summary
|
||||
=============================
|
||||
|
||||
In addition to the mocks themselves, CMock will generate the
|
||||
following functions for use in your tests. The expect functions
|
||||
are always generated. The other functions are only generated
|
||||
if those plugins are enabled:
|
||||
|
||||
|
||||
Expect:
|
||||
-------
|
||||
|
||||
Your basic staple Expects which will be used for most of your day
|
||||
to day CMock work. By calling this, you are telling CMock that you
|
||||
expect that function to be called during your test. It also specifies
|
||||
which arguments you expect it to be called with, and what return
|
||||
value you want returned when that happens. You can call this function
|
||||
multiple times back to back in order to queue up multiple calls.
|
||||
|
||||
* `void func(void)` => `void func_Expect(void)`
|
||||
* `void func(params)` => `void func_Expect(expected_params)`
|
||||
* `retval func(void)` => `void func_ExpectAndReturn(retval_to_return)`
|
||||
* `retval func(params)` => `void func_ExpectAndReturn(expected_params, retval_to_return)`
|
||||
|
||||
|
||||
ExpectAnyArgs:
|
||||
--------------
|
||||
|
||||
This behaves just like the Expects calls, except that it doesn't really
|
||||
care what the arguments are that the mock gets called with. It still counts
|
||||
the number of times the mock is called and it still handles return values
|
||||
if there are some.
|
||||
|
||||
* `void func(void)` => `void func_ExpectAnyArgs(void)`
|
||||
* `void func(params)` => `void func_ExpectAnyArgs(void)`
|
||||
* `retval func(void)` => `void func_ExpectAnyArgsAndReturn(retval_to_return)`
|
||||
* `retval func(params)` => `void func_ExpectAnyArgsAndReturn(retval_to_return)`
|
||||
|
||||
|
||||
Array:
|
||||
------
|
||||
|
||||
An ExpectWithArray is another variant of Expect. Like expect, it cares about
|
||||
the number of times a mock is called, the arguments it is called with, and the
|
||||
values it is to return. This variant has another feature, though. For anything
|
||||
that resembles a pointer or array, it breaks the argument into TWO arguments.
|
||||
The first is the original pointer. The second specify the number of elements
|
||||
it is to verify of that array. If you specify 1, it'll check one object. If 2,
|
||||
it'll assume your pointer is pointing at the first of two elements in an array.
|
||||
If you specify zero elements, it will check just the pointer if
|
||||
`:smart` mode is configured or fail if `:compare_data` is set.
|
||||
|
||||
* `void func(void)` => (nothing. In fact, an additional function is only generated if the params list contains pointers)
|
||||
* `void func(ptr * param, other)` => `void func_ExpectWithArray(ptr* param, int param_depth, other)`
|
||||
* `retval func(void)` => (nothing. In fact, an additional function is only generated if the params list contains pointers)
|
||||
* `retval func(other, ptr* param)` => `void func_ExpectWithArrayAndReturn(other, ptr* param, int param_depth, retval_to_return)`
|
||||
|
||||
|
||||
Ignore:
|
||||
-------
|
||||
|
||||
Maybe you don't care about the number of times a particular function is called or
|
||||
the actual arguments it is called with. In that case, you want to use Ignore. Ignore
|
||||
only needs to be called once per test. It will then ignore any further calls to that
|
||||
particular mock. The IgnoreAndReturn works similarly, except that it has the added
|
||||
benefit of knowing what to return when that call happens. If the mock is called more
|
||||
times than IgnoreAndReturn was called, it will keep returning the last value without
|
||||
complaint. If it's called less times, it will also ignore that. You SAID you didn't
|
||||
care how many times it was called, right?
|
||||
|
||||
* `void func(void)` => `void func_Ignore(void)`
|
||||
* `void func(params)` => `void func_Ignore(void)`
|
||||
* `retval func(void)` => `void func_IgnoreAndReturn(retval_to_return)`
|
||||
* `retval func(params)` => `void func_IgnoreAndReturn(retval_to_return)`
|
||||
|
||||
|
||||
Ignore Arg:
|
||||
------------
|
||||
|
||||
Maybe you overall want to use Expect and its similar variations, but you don't care
|
||||
what is passed to a particular argument. This is particularly useful when that argument
|
||||
is a pointer to a value that is supposed to be filled in by the function. You don't want
|
||||
to use ExpectAnyArgs, because you still care about the other arguments. Instead, before
|
||||
any of your Expect calls are made, you can call this function. It tells CMock to ignore
|
||||
a particular argument for the rest of this test, for this mock function.
|
||||
|
||||
* `void func(params)` => `void func_IgnoreArg_paramName(void)`
|
||||
|
||||
|
||||
ReturnThruPtr:
|
||||
--------------
|
||||
|
||||
Another option which operates on a particular argument of a function is the ReturnThruPtr
|
||||
plugin. For every argument that resembles a pointer or reference, CMock generates an
|
||||
instance of this function. Just as the AndReturn functions support injecting one or more
|
||||
return values into a queue, this function lets you specify one or more return values which
|
||||
are queued up and copied into the space being pointed at each time the mock is called.
|
||||
|
||||
* `void func(param1)` => `void func_ReturnThruPtr_paramName(val_to_return)`
|
||||
* => `void func_ReturnArrayThruPtr_paramName(cal_to_return, len)`
|
||||
* => `void func_ReturnMemThruPtr_paramName(val_to_return, size)`
|
||||
|
||||
|
||||
Callback:
|
||||
---------
|
||||
|
||||
If all those other options don't work, and you really need to do something custom, you
|
||||
still have a choice. As soon as you stub a callback in a test, it will call the callback
|
||||
whenever the mock is encountered and return the retval returned from the callback (if any)
|
||||
instead of performing the usual expect checks. It can be configured to check the arguments
|
||||
first (like expects) or just jump directly to the callback.
|
||||
|
||||
* `void func(void)` => `void func_StubWithCallback(CMOCK_func_CALLBACK callback)`
|
||||
where `CMOCK_func_CALLBACK` looks like: `void func(int NumCalls)`
|
||||
* `void func(params)` => `void func_StubWithCallback(CMOCK_func_CALLBACK callback)`
|
||||
where `CMOCK_func_CALLBACK` looks like: `void func(params, int NumCalls)`
|
||||
* `retval func(void)` => `void func_StubWithCallback(CMOCK_func_CALLBACK callback)`
|
||||
where `CMOCK_func_CALLBACK` looks like: `retval func(int NumCalls)`
|
||||
* `retval func(params)` => `void func_StubWithCallback(CMOCK_func_CALLBACK callback)`
|
||||
where `CMOCK_func_CALLBACK` looks like: `retval func(params, int NumCalls)`
|
||||
|
||||
|
||||
Cexception:
|
||||
-----------
|
||||
|
||||
Finally, if you are using Cexception for error handling, you can use this to throw errors
|
||||
from inside mocks. Like Expects, it remembers which call was supposed to throw the error,
|
||||
and it still checks parameters first.
|
||||
|
||||
* `void func(void)` => `void func_ExpectAndThrow(value_to_throw)`
|
||||
* `void func(params)` => `void func_ExpectAndThrow(expected_params, value_to_throw)`
|
||||
* `retval func(void)` => `void func_ExpectAndThrow(value_to_throw)`
|
||||
* `retval func(params)` => `void func_ExpectAndThrow(expected_params, value_to_throw)`
|
||||
|
||||
|
||||
|
||||
Running CMock
|
||||
=============
|
||||
|
||||
CMock is a Ruby script and class. You can therefore use it directly
|
||||
from the command line, or include it in your own scripts or rakefiles.
|
||||
|
||||
|
||||
Mocking from the Command Line
|
||||
-----------------------------
|
||||
|
||||
After unpacking CMock, you will find cmock.rb in the 'lib' directory.
|
||||
This is the file that you want to run. It takes a list of header files
|
||||
to be mocked, as well as an optional yaml file for a more detailed
|
||||
configuration (see config options below).
|
||||
|
||||
For example, this will create three mocks using the configuration
|
||||
specified in MyConfig.yml:
|
||||
|
||||
ruby cmock.rb -oMyConfig.yml super.h duper.h awesome.h
|
||||
|
||||
And this will create two mocks using the default configuration:
|
||||
|
||||
ruby cmock.rb ../mocking/stuff/is/fun.h ../try/it/yourself.h
|
||||
|
||||
|
||||
Mocking From Scripts or Rake
|
||||
----------------------------
|
||||
|
||||
CMock can be used directly from your own scripts or from a rakefile.
|
||||
Start by including cmock.rb, then create an instance of CMock.
|
||||
When you create your instance, you may initialize it in one of
|
||||
three ways.
|
||||
|
||||
You may specify nothing, allowing it to run with default settings:
|
||||
|
||||
require 'cmock.rb'
|
||||
cmock = CMock.new
|
||||
|
||||
You may specify a YAML file containing the configuration options
|
||||
you desire:
|
||||
|
||||
cmock = CMock.new('../MyConfig.yml')
|
||||
|
||||
You may specify the options explicitly:
|
||||
|
||||
cmock = Cmock.new(:plugins => [:cexception, :ignore], :mock_path => 'my/mocks/')
|
||||
|
||||
|
||||
Config Options:
|
||||
---------------
|
||||
|
||||
The following configuration options can be specified in the
|
||||
yaml file or directly when instantiating.
|
||||
|
||||
Passed as Ruby, they look like this:
|
||||
|
||||
{ :attributes => [“__funky”, “__intrinsic”], :when_ptr => :compare }
|
||||
|
||||
Defined in the yaml file, they look more like this:
|
||||
|
||||
:cmock:
|
||||
:attributes:
|
||||
- __funky
|
||||
- __intrinsic
|
||||
:when_ptr: :compare
|
||||
|
||||
In all cases, you can just include the things that you want to override
|
||||
from the defaults. We've tried to specify what the defaults are below.
|
||||
|
||||
* `:attributes`:
|
||||
These are attributes that CMock should ignore for you for testing
|
||||
purposes. Custom compiler extensions and externs are handy things to
|
||||
put here. If your compiler is choking on some extended syntax, this
|
||||
is often a good place to look.
|
||||
|
||||
* defaults: ['__ramfunc', '__irq', '__fiq', 'register', 'extern']
|
||||
* **note:** this option will reinsert these attributes onto the mock's calls.
|
||||
If that isn't what you are looking for, check out :strippables.
|
||||
|
||||
* `:c_calling_conventions`:
|
||||
Similarly, CMock may need to understand which C calling conventions
|
||||
might show up in your codebase. If it encounters something it doesn't
|
||||
recognize, it's not going to mock it. We have the most common covered,
|
||||
but there are many compilers out there, and therefore many other options.
|
||||
|
||||
* defaults: ['__stdcall', '__cdecl', '__fastcall']
|
||||
* **note:** this option will reinsert these attributes onto the mock's calls.
|
||||
If that isn't what you are looking for, check out :strippables.
|
||||
|
||||
* `:callback_after_arg_check`:
|
||||
Tell `:callback` plugin to do the normal argument checking **before** it
|
||||
calls the callback function by setting this to true. When false, the
|
||||
callback function is called **instead** of the argument verification.
|
||||
|
||||
* default: false
|
||||
|
||||
* `:callback_include_count`:
|
||||
Tell `:callback` plugin to include an extra parameter to specify the
|
||||
number of times the callback has been called. If set to false, the
|
||||
callback has the same interface as the mocked function. This can be
|
||||
handy when you're wanting to use callback as a stub.
|
||||
|
||||
* default: true
|
||||
|
||||
* `:cexception_include`:
|
||||
Tell `:cexception` plugin where to find CException.h... You only need to
|
||||
define this if it's not in your build path already... which it usually
|
||||
will be for the purpose of your builds.
|
||||
|
||||
* default: *nil*
|
||||
|
||||
* `:enforce_strict_ordering`:
|
||||
CMock always enforces the order that you call a particular function,
|
||||
so if you expect GrabNabber(int size) to be called three times, it
|
||||
will verify that the sizes are in the order you specified. You might
|
||||
*also* want to make sure that all different functions are called in a
|
||||
particular order. If so, set this to true.
|
||||
|
||||
* default: false
|
||||
|
||||
* `:framework`:
|
||||
Currently the only option is `:unity.` Eventually if we support other
|
||||
unity test frameworks (or if you write one for us), they'll get added
|
||||
here.
|
||||
|
||||
: default: :unity
|
||||
|
||||
* `:includes`:
|
||||
An array of additional include files which should be added to the
|
||||
mocks. Useful for global types and definitions used in your project.
|
||||
There are more specific versions if you care WHERE in the mock files
|
||||
the includes get placed. You can define any or all of these options.
|
||||
|
||||
* `:includes`
|
||||
* `:includes_h_pre_orig_header`
|
||||
* `:includes_h_post_orig_header`
|
||||
* `:includes_c_pre_header`
|
||||
* `:includes_c_post_header`
|
||||
* default: nil #for all 5 options
|
||||
|
||||
* `:memcmp_if_unknown`:
|
||||
C developers create a lot of types, either through typedef or preprocessor
|
||||
macros. CMock isn't going to automatically know what you were thinking all
|
||||
the time (though it tries its best). If it comes across a type it doesn't
|
||||
recognize, you have a choice on how you want it to handle it. It can either
|
||||
perform a raw memory comparison and report any differences, or it can fail
|
||||
with a meaningful message. Either way, this feature will only happen after
|
||||
all other mechanisms have failed (The thing encountered isn't a standard
|
||||
type. It isn't in the :treat_as list. It isn't in a custom unity_helper).
|
||||
|
||||
* default: true
|
||||
|
||||
* `:mock_path`:
|
||||
The directory where you would like the mock files generated to be
|
||||
placed.
|
||||
|
||||
* default: mocks
|
||||
|
||||
* `:mock_prefix`:
|
||||
The prefix to prepend to your mock files. For example, if it's “Mock”, a file
|
||||
“USART.h” will get a mock called “MockUSART.c”. This CAN be used with a suffix
|
||||
at the same time.
|
||||
|
||||
* default: Mock
|
||||
|
||||
* `:mock_suffix`:
|
||||
The suffix to append to your mock files. For example, it it's "_Mock", a file
|
||||
"USART.h" will get a mock called "USART_Mock.h". This CAN be used with a prefix
|
||||
at the same time.
|
||||
|
||||
* default: ""
|
||||
|
||||
* `:plugins`:
|
||||
An array of which plugins to enable. ':expect' is always active. Also
|
||||
available currently:
|
||||
|
||||
* `:ignore`
|
||||
* `:ignore_arg`
|
||||
* `:expect_any_args`
|
||||
* `:array`
|
||||
* `:cexception`
|
||||
* `:callback`
|
||||
* `:return_thru_ptr`
|
||||
|
||||
* `:strippables`:
|
||||
An array containing a list of items to remove from the header
|
||||
before deciding what should be mocked. This can be something simple
|
||||
like a compiler extension CMock wouldn't recognize, or could be a
|
||||
regex to reject certain function name patterns. This is a great way to
|
||||
get rid of compiler extensions when your test compiler doesn't support
|
||||
them. For example, use `:strippables: ['(?:functionName\s*\(+.*?\)+)']`
|
||||
to prevent a function `functionName` from being mocked. By default, it
|
||||
is ignoring all gcc attribute extensions.
|
||||
|
||||
* default: ['(?:__attribute__\s*\(+.*?\)+)']
|
||||
|
||||
* `:subdir`:
|
||||
This is a relative subdirectory for your mocks. Set this to e.g. "sys" in
|
||||
order to create a mock for `sys/types.h` in `(:mock_path)/sys/`.
|
||||
|
||||
* default: ""
|
||||
|
||||
* `:treat_as`:
|
||||
The `:treat_as` list is a shortcut for when you have created typedefs
|
||||
of standard types. Why create a custom unity helper for UINT16 when
|
||||
the unity function TEST_ASSERT_EQUAL_HEX16 will work just perfectly?
|
||||
Just add 'UINT16' => 'HEX16' to your list (actually, don't. We already
|
||||
did that one for you). Maybe you have a type that is a pointer to an
|
||||
array of unsigned characters? No problem, just add 'UINT8_T*' =>
|
||||
'HEX8*'
|
||||
|
||||
* NOTE: unlike the other options, your specifications MERGE with the
|
||||
default list. Therefore, if you want to override something, you must
|
||||
reassign it to something else (or to *nil* if you don't want it)
|
||||
|
||||
* default:
|
||||
* 'int': 'INT'
|
||||
* 'char': 'INT8'
|
||||
* 'short': 'INT16'
|
||||
* 'long': 'INT'
|
||||
* 'int8': 'INT8'
|
||||
* 'int16': 'INT16'
|
||||
* 'int32': 'INT'
|
||||
* 'int8_t': 'INT8'
|
||||
* 'int16_t': 'INT16'
|
||||
* 'int32_t': 'INT'
|
||||
* 'INT8_T': 'INT8'
|
||||
* 'INT16_T': 'INT16'
|
||||
* 'INT32_T': 'INT'
|
||||
* 'bool': 'INT'
|
||||
* 'bool_t': 'INT'
|
||||
* 'BOOL': 'INT'
|
||||
* 'BOOL_T': 'INT'
|
||||
* 'unsigned int': 'HEX32'
|
||||
* 'unsigned long': 'HEX32'
|
||||
* 'uint32': 'HEX32'
|
||||
* 'uint32_t': 'HEX32'
|
||||
* 'UINT32': 'HEX32'
|
||||
* 'UINT32_T': 'HEX32'
|
||||
* 'void*': 'HEX8_ARRAY'
|
||||
* 'unsigned short': 'HEX16'
|
||||
* 'uint16': 'HEX16'
|
||||
* 'uint16_t': 'HEX16'
|
||||
* 'UINT16': 'HEX16'
|
||||
* 'UINT16_T': 'HEX16'
|
||||
* 'unsigned char': 'HEX8'
|
||||
* 'uint8': 'HEX8'
|
||||
* 'uint8_t': 'HEX8'
|
||||
* 'UINT8': 'HEX8'
|
||||
* 'UINT8_T': 'HEX8'
|
||||
* 'char*': 'STRING'
|
||||
* 'pCHAR': 'STRING'
|
||||
* 'cstring': 'STRING'
|
||||
* 'CSTRING': 'STRING'
|
||||
* 'float': 'FLOAT'
|
||||
* 'double': 'FLOAT'
|
||||
|
||||
* `:treat_as_void`:
|
||||
We've seen "fun" legacy systems typedef 'void' with a custom type,
|
||||
like MY_VOID. Add any instances of those to this list to help CMock
|
||||
understand how to deal with your code.
|
||||
|
||||
* default: []
|
||||
|
||||
* `:treat_externs`:
|
||||
This specifies how you want CMock to handle functions that have been
|
||||
marked as extern in the header file. Should it mock them?
|
||||
|
||||
* `:include` will mock externed functions
|
||||
* `:exclude` will ignore externed functions (default).
|
||||
|
||||
* `:unity_helper_path`:
|
||||
If you have created a header with your own extensions to unity to
|
||||
handle your own types, you can set this argument to that path. CMock
|
||||
will then automagically pull in your helpers and use them. The only
|
||||
trick is that you make sure you follow the naming convention:
|
||||
`UNITY_TEST_ASSERT_EQUAL_YourType`. If it finds macros of the right
|
||||
shape that match that pattern, it'll use them.
|
||||
|
||||
* default: []
|
||||
|
||||
* `:verbosity`:
|
||||
How loud should CMock be?
|
||||
|
||||
* 0 for errors only
|
||||
* 1 for errors and warnings
|
||||
* 2 for normal (default)
|
||||
* 3 for verbose
|
||||
|
||||
* `:weak`:
|
||||
When set this to some value, the generated mocks are defined as weak
|
||||
symbols using the configured format. This allows them to be overridden
|
||||
in particular tests.
|
||||
|
||||
* Set to '__attribute ((weak))' for weak mocks when using GCC.
|
||||
* Set to any non-empty string for weak mocks when using IAR.
|
||||
* default: ""
|
||||
|
||||
* `:when_no_prototypes`:
|
||||
When you give CMock a header file and ask it to create a mock out of
|
||||
it, it usually contains function prototypes (otherwise what was the
|
||||
point?). You can control what happens when this isn't true. You can
|
||||
set this to `:warn,` `:ignore,` or `:error`
|
||||
|
||||
* default: :warn
|
||||
|
||||
* `:when_ptr`:
|
||||
You can customize how CMock deals with pointers (c strings result in
|
||||
string comparisons... we're talking about **other** pointers here). Your
|
||||
options are `:compare_ptr` to just verify the pointers are the same,
|
||||
`:compare_data` or `:smart` to verify that the data is the same.
|
||||
`:compare_data` and `:smart` behaviors will change slightly based on
|
||||
if you have the array plugin enabled. By default, they compare a
|
||||
single element of what is being pointed to. So if you have a pointer
|
||||
to a struct called ORGAN_T, it will compare one ORGAN_T (whatever that
|
||||
is).
|
||||
|
||||
* default: :smart
|
||||
|
||||
* `:fail_on_unexpected_calls`:
|
||||
By default, CMock will fail a test if a mock is called without _Expect and _Ignore
|
||||
called first. While this forces test writers to be more explicit in their expectations,
|
||||
it can clutter tests with _Expect or _Ignore calls for functions which are not the focus
|
||||
of the test. While this is a good indicator that this module should be refactored, some
|
||||
users are not fans of the additional noise.
|
||||
|
||||
Therefore, :fail_on_unexpected_calls can be set to false to force all mocks to start with
|
||||
the assumption that they are operating as _Ignore unless otherwise specified.
|
||||
|
||||
* default: true
|
||||
* **note:**
|
||||
If this option is disabled, the mocked functions will return
|
||||
a default value (0) when called (and only if they have to return something of course).
|
||||
|
||||
|
||||
Compiled Options:
|
||||
-----------------
|
||||
|
||||
A number of #defines also exist for customizing the cmock experience.
|
||||
Feel free to pass these into your compiler or whatever is most
|
||||
convenient. CMock will otherwise do its best to guess what you want
|
||||
based on other settings, particularly Unity's settings.
|
||||
|
||||
* `CMOCK_MEM_STATIC` or `CMOCK_MEM_DYNAMIC`
|
||||
Define one of these to determine if you want to dynamically add
|
||||
memory during tests as required from the heap. If static, you
|
||||
can control the total footprint of Cmock. If dynamic, you will
|
||||
need to make sure you make some heap space available for Cmock.
|
||||
|
||||
* `CMOCK_MEM_SIZE`
|
||||
In static mode this is the total amount of memory you are allocating
|
||||
to Cmock. In Dynamic mode this is the size of each chunk allocated
|
||||
at once (larger numbers grab more memory but require less mallocs).
|
||||
|
||||
* `CMOCK_MEM_ALIGN`
|
||||
The way to align your data to. Not everything is as flexible as
|
||||
a PC, as most embedded designers know. This defaults to 2, meaning
|
||||
align to the closest 2^2 -> 4 bytes (32 bits). You can turn off alignment
|
||||
by setting 0, force alignment to the closest uint16 with 1 or even
|
||||
to the closest uint64 with 3.
|
||||
|
||||
* `CMOCK_MEM_PTR_AS_INT`
|
||||
This is used internally to hold pointers... it needs to be big
|
||||
enough. On most processors a pointer is the same as an unsigned
|
||||
long... but maybe that's not true for yours?
|
||||
|
||||
* `CMOCK_MEM_INDEX_TYPE`
|
||||
This needs to be something big enough to point anywhere in Cmock's
|
||||
memory space... usually it's an unsigned int.
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
You can look in the [examples directory](/examples/) for a couple of examples on how
|
||||
you might tool CMock into your build process. You may also want to consider
|
||||
using [Ceedling](https://throwtheswitch.org/ceedling). Please note that
|
||||
these examples are meant to show how the build process works. They have
|
||||
failing tests ON PURPOSE to show what that would look like. Don't be alarmed. ;)
|
||||
|
||||
2060
test/vendor/ceedling/docs/CeedlingPacket.md
vendored
Normal file
2060
test/vendor/ceedling/docs/CeedlingPacket.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
206
test/vendor/ceedling/docs/ThrowTheSwitchCodingStandard.md
vendored
Normal file
206
test/vendor/ceedling/docs/ThrowTheSwitchCodingStandard.md
vendored
Normal file
@@ -0,0 +1,206 @@
|
||||
# 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 tried 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 a bit of effort into
|
||||
finding *What Something WANTS to be Called*™.
|
||||
|
||||
When naming things, we follow this hierarchy, the first being the
|
||||
most important to us (but we do all four when 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 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 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 mark down and we like pdf files because they can be made to
|
||||
look nice while still being portable. Good enough?
|
||||
|
||||
|
||||
*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)*
|
||||
BIN
test/vendor/ceedling/docs/UnityAssertionsCheatSheetSuitableforPrintingandPossiblyFraming.pdf
vendored
Normal file
BIN
test/vendor/ceedling/docs/UnityAssertionsCheatSheetSuitableforPrintingandPossiblyFraming.pdf
vendored
Normal file
Binary file not shown.
779
test/vendor/ceedling/docs/UnityAssertionsReference.md
vendored
Normal file
779
test/vendor/ceedling/docs/UnityAssertionsReference.md
vendored
Normal file
@@ -0,0 +1,779 @@
|
||||
# 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 clear 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 )
|
||||
|
||||
Notes:
|
||||
- The `_MESSAGE` variants intentionally do not support `printf` style formatting
|
||||
since many embedded projects don't support or avoid `printf` for various reasons.
|
||||
It is possible to use `sprintf` before the assertion to assemble a complex fail
|
||||
message, if necessary.
|
||||
- If you want to output a counter value within an assertion fail message (e.g. from
|
||||
a loop) , building up an array of results and then using one of the `_ARRAY`
|
||||
assertions (see below) might be a handy alternative to `sprintf`.
|
||||
|
||||
|
||||
#### 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).
|
||||
|
||||
|
||||
### TEST_ASSERT_EACH_EQUAL_X Variants
|
||||
|
||||
Unity provides a collection of assertions for arrays containing a variety of
|
||||
types which can be compared to a single value as well. These are documented in
|
||||
the Each Equal 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 inject _EACH_EQUAL and run assertions on an entire block of memory.
|
||||
|
||||
TEST_ASSERT_EACH_EQUAL_TYPEX( expected, actual, {size/count} )
|
||||
|
||||
"Expected" is a single value to compare to.
|
||||
"Actual" is an array where each element will be compared to the expected value.
|
||||
"Size/count" is one of 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 Each Equal assertions.
|
||||
- Assertions for handling Each Equal 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 Less Than / Greater Than
|
||||
|
||||
These assertions verify that the `actual` parameter is less than or greater
|
||||
than `threshold` (exclusive). For example, if the threshold value is 0 for the
|
||||
greater than assertion will fail if it is 0 or less.
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_INT (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_INT8 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_INT16 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_INT32 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_UINT (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_UINT8 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_UINT16 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_UINT32 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_HEX8 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_HEX16 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_GREATER_THAN_HEX32 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_INT (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_INT8 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_INT16 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_INT32 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_UINT (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_UINT8 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_UINT16 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_UINT32 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_HEX8 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_HEX16 (threshold, actual)`
|
||||
|
||||
##### `TEST_ASSERT_LESS_THAN_HEX32 (threshold, actual)`
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
### Each Equal (Arrays to Single Value)
|
||||
|
||||
`expected` are single values and `actual` are 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.
|
||||
|
||||
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_EACH_EQUAL_INT (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_INT8 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_INT16 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_INT32 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_INT64 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_UINT (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_UINT8 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_UINT16 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_UINT32 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_UINT64 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_HEX (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_HEX8 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_HEX16 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_HEX32 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_HEX64 (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_PTR (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_STRING (expected, actual, num_elements)`
|
||||
|
||||
#### `TEST_ASSERT_EACH_EQUAL_MEMORY (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 20 or 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.
|
||||
|
||||
|
||||
*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)*
|
||||
433
test/vendor/ceedling/docs/UnityConfigurationGuide.md
vendored
Normal file
433
test/vendor/ceedling/docs/UnityConfigurationGuide.md
vendored
Normal file
@@ -0,0 +1,433 @@
|
||||
# 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 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 use 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
|
||||
|
||||
|
||||
If you've disabled both 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_SUPPORT_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_SUPPORT_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_EXCLUDE_FLOAT_PRINT`
|
||||
|
||||
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.
|
||||
Therefore, the display of floating point values during a failure are optional.
|
||||
By default, Unity will print the actual results of floating point assertion
|
||||
failure (e.g. ”Expected 4.56 Was 4.68”). To not include this extra support, you
|
||||
can use this define to instead respond to a failed assertion with 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.
|
||||
|
||||
_Example:_
|
||||
#define UNITY_EXCLUDE_FLOAT_PRINT
|
||||
|
||||
|
||||
##### `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 run 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:
|
||||
#include "RS232_header.h"
|
||||
...
|
||||
#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.
|
||||
|
||||
|
||||
##### `UNITY_WEAK_ATTRIBUTE`
|
||||
|
||||
##### `UNITY_WEAK_PRAGMA`
|
||||
|
||||
##### `UNITY_NO_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_WEAK_ATTRIBUTE or UNITY_WEAK_PRAGMA 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). You can also force Unity to NOT use weak functions by defining
|
||||
UNITY_NO_WEAK. The most common options for this feature are:
|
||||
|
||||
_Example:_
|
||||
#define UNITY_WEAK_ATTRIBUTE weak
|
||||
#define UNITY_WEAK_ATTRIBUTE __attribute__((weak))
|
||||
#define UNITY_WEAK_PRAGMA
|
||||
#define UNITY_NO_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
|
||||
|
||||
|
||||
##### `UNITY_PRINT_EOL`
|
||||
|
||||
By default, Unity outputs \n at the end of each line of output. This is easy
|
||||
to parse by the scripts, by Ceedling, etc, but it might not be ideal for YOUR
|
||||
system. Feel free to override this and to make it whatever you wish.
|
||||
|
||||
_Example:_
|
||||
#define UNITY_PRINT_EOL { UNITY_OUTPUT_CHAR('\r'); UNITY_OUTPUT_CHAR('\n') }
|
||||
|
||||
|
||||
|
||||
##### `UNITY_EXCLUDE_DETAILS`
|
||||
|
||||
This is an option for if you absolutely must squeeze every byte of memory out of
|
||||
your system. Unity stores a set of internal scratchpads which are used to pass
|
||||
extra detail information around. It's used by systems like CMock in order to
|
||||
report which function or argument flagged an error. If you're not using CMock and
|
||||
you're not using these details for other things, then you can exclude them.
|
||||
|
||||
_Example:_
|
||||
#define UNITY_EXCLUDE_DETAILS
|
||||
|
||||
|
||||
|
||||
##### `UNITY_EXCLUDE_SETJMP`
|
||||
|
||||
If your embedded system doesn't support the standard library setjmp, you can
|
||||
exclude Unity's reliance on this by using this define. This dropped dependence
|
||||
comes at a price, though. You will be unable to use custom helper functions for
|
||||
your tests, and you will be unable to use tools like CMock. Very likely, if your
|
||||
compiler doesn't support setjmp, you wouldn't have had the memory space for those
|
||||
things anyway, though... so this option exists for those situations.
|
||||
|
||||
_Example:_
|
||||
#define UNITY_EXCLUDE_SETJMP
|
||||
|
||||
##### `UNITY_OUTPUT_COLOR`
|
||||
|
||||
If you want to add color using ANSI escape codes you can use this define.
|
||||
t
|
||||
_Example:_
|
||||
#define UNITY_OUTPUT_COLOR
|
||||
|
||||
|
||||
|
||||
## 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!
|
||||
|
||||
|
||||
*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)*
|
||||
192
test/vendor/ceedling/docs/UnityGettingStartedGuide.md
vendored
Normal file
192
test/vendor/ceedling/docs/UnityGettingStartedGuide.md
vendored
Normal file
@@ -0,0 +1,192 @@
|
||||
# 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. Also, the automated scripts that come with Unity or Ceedling will default
|
||||
to looking for test functions to be prefixed this way. 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 need 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!
|
||||
|
||||
|
||||
*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)*
|
||||
260
test/vendor/ceedling/docs/UnityHelperScriptsGuide.md
vendored
Normal file
260
test/vendor/ceedling/docs/UnityHelperScriptsGuide.md
vendored
Normal file
@@ -0,0 +1,260 @@
|
||||
# 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 of 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 afterwards. 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.
|
||||
|
||||
Alternatively, if your C compiler supports weak symbols, you can leave this
|
||||
option unset and instead provide a `void suiteSetUp(void)` function in your test
|
||||
suite. The linker will look for this symbol and fall back to a Unity-provided
|
||||
stub if it is not found.
|
||||
|
||||
|
||||
##### `:suite_teardown`
|
||||
|
||||
Define this option with C code to be executed _after all_ test cases have
|
||||
finished. An integer variable `num_failures` is available for diagnostics.
|
||||
The code should end with a `return` statement; the value returned will become
|
||||
the exit code of `main`. You can normally just return `num_failures`.
|
||||
|
||||
Alternatively, if your C compiler supports weak symbols, you can leave this
|
||||
option unset and instead provide a `int suiteTearDown(int num_failures)`
|
||||
function in your test suite. The linker will look for this symbol and fall
|
||||
back to a Unity-provided stub if it is not found.
|
||||
|
||||
|
||||
##### `: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.
|
||||
|
||||
##### `:mock_prefix` and `:mock_suffix`
|
||||
|
||||
Unity automatically generates calls to Init, Verify and Destroy for every file
|
||||
included in the main test file that starts with the given mock prefix and ends
|
||||
with the given mock suffix, file extension not included. By default, Unity
|
||||
assumes a `Mock` prefix and no suffix.
|
||||
|
||||
##### `: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?
|
||||
|
||||
|
||||
*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)*
|
||||
Reference in New Issue
Block a user