| /** |
| |
| @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. |
| |
| |
| */ |