doc/mainpage.dox

/**

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


CMocka is a fork of Google's cmockery.

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

@section main-mock Mock objects

TODO Explain mock objects.

@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

*/