Loading...
Searching...
No Matches
cmocka

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

📚 Looking for the API documentation?
See the API Reference for detailed documentation of all functions, macros, and data structures.

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/

# 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, JUnit XML, Subunit)
- 📜 License: Apache License 2.0

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

#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);
}
cmocka_unit_test
#define cmocka_unit_test(f)
Definition cmocka.h:5928
cmocka_run_group_tests
int cmocka_run_group_tests(const struct CMUnitTest group_tests[], CMFixtureFunction group_setup, CMFixtureFunction group_teardown)
Run tests specified by an array of CMUnitTest structures.
CMUnitTest
Definition cmocka.h:6481

# 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 an API to easily mock code.

Check out the examples here.

# Disabling Deprecation Warnings

Note
  Deprecated features will remain available for a long time and are not scheduled for removal. The deprecation warnings are intended to help you identify older APIs and guide migration to newer alternatives at your own pace.

cmocka marks deprecated functions and features with compiler warnings to help you migrate to newer APIs. If you need to suppress these warnings (e.g., during a migration period or when building legacy code), you can define the following macro before including cmocka.h:

#define CMOCKA_DISABLE_DEPRECTATION_WARNINGS
#include <cmocka.h>

Alternatively, you can pass it as a compiler option:

        gcc -DCMOCKA_DISABLE_DEPRECTATION_WARNINGS -o my_test my_test.c -lcmocka

This will disable both the deprecated function attribute warnings and the compile-time deprecation messages.

# 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:

        cmake -DCMOCKA_PLATFORM_INCLUDE=/home/compiler/my/include_directory ..

## Standard includes

CMocka requires the include of the following list of standard headers or their equivalent.

#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <setjmp.h>

The header file 'cmocka.h' includes those headers already and in case your platform does not provide those header files, you must #define CMOCKA_NO_STANDARD_INCLUDES in order to prevent the include of those files.

An example of how your code which uses CMocka could look like is given below.

#include "path/to/cmocka_platform.h"
#define CMOCKA_NO_STANDARD_INCLUDES
#include <cmocka.h>
/* ... your test code goes here ... */

# 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:

        CMOCKA_TEST_ABORT='1' ./my_threading_test

With this environment variable set to '1', cmocka will call abort() if a test fails.

# 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 CMOCKA_MESSAGE_OUTPUT environment variable. The supported values are:

- STDOUT for the default standard output printer
- SUBUNIT for subunit output
- TAP for Test Anything Protocol (TAP) output
- XML for JUnit XML format The case doesn't matter.

The XML output goes to stderr by default. If the environment variable CMOCKA_XML_FILE exists and the file specified by this variable doesn't exist yet, then cmocka will put the output to this file. Note that if you are have several groups you should set CMOCKA_XML_FILE to CMOCKA_XML_FILE=cm_%g.xml. In this g will be replaced by the group_name of the test and a file will be created for each group, othwerwise all groups will be printed into the same file.

Error messages from test failures are controlled by the CMOCKA_ERROR_OUTPUT environment variable. The supported values are:

- STDOUT for standard output (default)
- STDERR for standard error The case doesn't matter. This allows you to redirect error messages separately from test results when needed.