cmocka Documentation

This is the online reference for developing with the CMocka library. It documents the CMocka C API.

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

CMocka is a fork of Google's cmockery.

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.

Mock objects

TODO Explain mock objects.

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.

#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);
}