134 lines
5.0 KiB
Plaintext
134 lines
5.0 KiB
Plaintext
/**
|
|
|
|
@mainpage
|
|
|
|
This is the online reference for developing with the cmocka library. It
|
|
documents the cmocka C API.
|
|
|
|
cmocka is an elegant unit testing framework for C with support for mock
|
|
objects. It only requires the standard C library, works on a lot of platforms
|
|
(including embedded) and with different compilers.
|
|
|
|
http://cmocka.org/
|
|
|
|
@section main-features Features
|
|
|
|
Tests written with cmocka are compiled into stand-alone executables and linked with the
|
|
CMock library, the standard C library and module being tested. Any symbols
|
|
external to the module being tested should be mocked - replaced with functions
|
|
that return values determined by the test - within the test application. Even
|
|
though significant differences may exist between the target execution
|
|
environment of a code module and the environment used to test the code the unit
|
|
testing is still valid since its goal is to test the logic of a code modules at
|
|
a functional level and not necessarily all of its interactions with the target
|
|
execution environment.
|
|
|
|
The CMocka library provides:
|
|
|
|
- Support for mock objects.
|
|
- Test fixtures.
|
|
- Only requires a C library
|
|
- Exception handling for signals (SIGSEGV, SIGILL, ...)
|
|
- No use of fork()
|
|
- Very well tested
|
|
- Testing of memory leaks, buffer overflows and underflows.
|
|
- A set of assert macros.
|
|
- Several supported output formats (stdout, TAP, xUnit XML, Subunit)
|
|
- License: Apache License 2.0
|
|
|
|
@section main-test A cmocka test
|
|
|
|
Test cases are functions with the signature void function(void **state). Test
|
|
applications initialize a table with test case function pointers using
|
|
unit_test() macros. This table is then passed to the run_tests() macro to
|
|
execute the tests. run_tests() sets up the appropriate exception / signal
|
|
handlers and other data structures prior to running each test function. When a
|
|
unit test is complete run_tests() performs various checks to determine whether
|
|
the test succeeded.
|
|
|
|
@code
|
|
#include <stdarg.h>
|
|
#include <stddef.h>
|
|
#include <setjmp.h>
|
|
#include <cmocka.h>
|
|
|
|
/* A test case that does nothing and succeeds. */
|
|
static void null_test_success(void **state) {
|
|
(void) state; /* unused */
|
|
}
|
|
|
|
int main(void) {
|
|
const struct CMUnitTest tests[] = {
|
|
cmocka_unit_test(null_test_success),
|
|
};
|
|
|
|
return cmocka_run_group_tests(tests, NULL, NULL);
|
|
}
|
|
@endcode
|
|
|
|
@section main-mock Mock objects
|
|
|
|
You may already have heard the term "Mock Object". It describes a special case
|
|
of an object that mimics a real instance of an interface in order to provide
|
|
enough of that interface for testing. While there are several unit testing
|
|
frameworks that already provide some easy to use interface for creating
|
|
different kinds of "fake" objects for testing, there may be some confusion in
|
|
terms of how these test objects are programmed and what the behavioral
|
|
differences are between them.
|
|
|
|
Mock objects include some logic and the test driver is able to modify the
|
|
behaviour and state. The object can call some functions or act on different
|
|
input (abort a test if it is wrong). The test driver injects what it expects
|
|
the mock object to return. CMocka provides and API to easily mock code.
|
|
|
|
<a href="https://lwn.net/Articles/558106/">Learn more ...</a>
|
|
|
|
@section main-embedded Embedded platforms
|
|
|
|
It is possible that some embedded platforms do not provide definitions for
|
|
required types or that the guards to protect them are not defined. To address
|
|
this issue you can create a header file name 'cmocka_platform.h' with the
|
|
required types and definitions. After that point cmake to the include directory
|
|
using:
|
|
|
|
<pre>
|
|
cmake -DCMOCKA_PLATFORM_INCLUDE=/home/compiler/my/include_directory ..
|
|
</pre>
|
|
|
|
@section main-threads Threading
|
|
|
|
cmocka is not fully thread safe and it is not the goal of it to be it. We have
|
|
several global variables to track test states. They are marked as thread local
|
|
but it is possible that you still run into issues. However if you use cmocka
|
|
for writing tests in an application which uses threads, you can set the
|
|
following envionment variable:
|
|
|
|
<pre>
|
|
CMOCKA_TEST_ABORT='1' ./my_threading_test
|
|
</pre>
|
|
|
|
With this environment variable set to '1', cmocka will call <tt>abort()</tt> if
|
|
a test fails.
|
|
|
|
@section main-output Output formats
|
|
|
|
By default, cmocka prints human-readable test output to stderr. It is
|
|
possible to configure several other output formats. The configuration is
|
|
done using the <tt>CMOCKA_MESSAGE_OUTPUT</tt> environment variable. The
|
|
supported values are:
|
|
- <tt>STDOUT</tt> for the default standard output printer
|
|
- <tt>SUBUNIT</tt> for subunit output
|
|
- <tt>TAP</tt> for Test Anything Protocol (TAP) output
|
|
- <tt>XML</tt> for xUnit XML format
|
|
The case doesn't matter.
|
|
|
|
The XML output goes to stderr by default. If the environment variable
|
|
<tt>CMOCKA_XML_FILE</tt> exists and the file specified by this variable
|
|
doesn't exist yet, then cmocka will put the output to this file. Note
|
|
that if you are have several groups you should set <tt>CMOCKA_XML_FILE</tt>
|
|
to <tt>CMOCKA_XML_FILE=cm_%g.xml</tt>. In this %g will be replaced by
|
|
the group_name of the test and a file will be created for each group,
|
|
othwerwise all groups will be printed into the same file.
|
|
|
|
*/
|