| /** |
| |
| @mainpage |
| |
| This is the online reference for developing with the CMocka library. It |
| documents the CMocka C API. |
| |
| @section main-motivation Motivation |
| |
| There are a variety of C unit testing frameworks available supporting different |
| platforms and compilers. Some development requires a lot of different compilers |
| and older versions which makes it difficult to use unit testing frameworks. |
| |
| The idea of CMocka is that a test application only requires the standard C |
| library and CMocka itself to minimize the conflicts with standard C library |
| headers especially on a lot of different platforms. |
| |
| Currently CMocka is tested on Linux, FreeBSD, Solaris and Windows. See the |
| <a href="http://mock.cryptomilk.org/index.php?project=cmocka">Testing Dashboard</a>. |
| |
| @section main-features Features |
| |
| CMocka tests 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: |
| |
| - An easy to use framework to write unit tests. |
| - Support for mock objects. |
| - Fixtures to implement a setup and teardown function. |
| - A set of assert macros. |
| |
| @section main-test A CMocka test |
| |
| CMocka unit test cases are functions with the signature void function(void **state). |
| CMocka 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 UnitTest tests[] = { |
| unit_test(null_test_success), |
| }; |
| |
| return run_tests(tests); |
| } |
| @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. |
| |
| Read the article <a href="https://lwn.net/Articles/558106/">Unit testing with mock objects in C</a> |
| to learn more. |
| |
| */ |