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

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

*/