1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
/**
@mainpage
This is the online reference for developing with the cmocka library. It
documents the cmocka C API.
<div style="background-color: #fff8e6; border-left: 4px solid #feb41c; padding: 15px; margin: 20px 0;">
<strong>📚 Looking for the API documentation?</strong><br/>
See the <a href="topics.html"><b>API Reference</b></a> for detailed documentation of all functions, macros, and data structures.
</div>
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/
@section main-features 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
@section main-test 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.
@code
#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);
}
@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 an API to easily mock code.
Check out the examples <a href="https://git.cryptomilk.org/projects/cmocka.git/tree/example/mock">here</a>.
@section main-deprecation 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:
@code
#define CMOCKA_DISABLE_DEPRECTATION_WARNINGS
#include <cmocka.h>
@endcode
Alternatively, you can pass it as a compiler option:
<pre>
gcc -DCMOCKA_DISABLE_DEPRECTATION_WARNINGS -o my_test my_test.c -lcmocka
</pre>
This will disable both the deprecated function attribute warnings and the
compile-time deprecation messages.
@section main-embedded 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:
<pre>
cmake -DCMOCKA_PLATFORM_INCLUDE=/home/compiler/my/include_directory ..
</pre>
@subsection sub-includes Standard includes
CMocka requires the include of the following list of standard headers or
their equivalent.
@code
#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <setjmp.h>
@endcode
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.
@code
#include "path/to/cmocka_platform.h"
#define CMOCKA_NO_STANDARD_INCLUDES
#include <cmocka.h>
/* ... your test code goes here ... */
@endcode
@section main-threads 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:
<pre>
CMOCKA_TEST_ABORT='1' ./my_threading_test
</pre>
With this environment variable set to '1', cmocka will call <tt>abort()</tt> if
a test fails.
@section main-output 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 <tt>CMOCKA_MESSAGE_OUTPUT</tt> environment variable. The
supported values are:
- <tt>STDOUT</tt> for the default standard output printer
- <tt>SUBUNIT</tt> for subunit output
- <tt>TAP</tt> for Test Anything Protocol (TAP) output
- <tt>XML</tt> for JUnit XML format
The case doesn't matter.
The XML output goes to stderr by default. If the environment variable
<tt>CMOCKA_XML_FILE</tt> 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 <tt>CMOCKA_XML_FILE</tt>
to <tt>CMOCKA_XML_FILE=cm_%%g.xml</tt>. 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
<tt>CMOCKA_ERROR_OUTPUT</tt> environment variable. The supported values are:
- <tt>STDOUT</tt> for standard output (default)
- <tt>STDERR</tt> for standard error
The case doesn't matter. This allows you to redirect error messages
separately from test results when needed.
*/
|
