repository·master·Indexed 21 days ago
https://github.com/throwtheswitch/cmockA mock and stub generator for C unit testing that automates the creation of mock interfaces by parsing C header files. Part of the ThrowTheSwitch.org ecosystem, CMock integrates with Unity Test and can be managed via the Ceedling build manager. It provides features for argument validation, return value control, call order verification, and support for custom assertions, callbacks, and stubs.
CMock is a mock and stub generator and runtime designed for unit testing C code. It automatically parses C header files to create mock interfaces. It is designed to integrate seamlessly with Unity Test, another testing tool from ThrowTheSwitch.org.
For users who prefer not to manage unit testing builds manually, Ceedling is recommended as a test-centered build manager that integrates with CMock.
CMock is a tool that takes C header files and automatically generates a Mock interface for them. This allows you to replace real function implementations with mocked versions during unit testing.
With these mocks, you can:
CMock is built on top of Unity and uses Ruby (version 3.0.0 or higher) for its core logic.
The project follows a specific hierarchy for naming to ensure code is easy to maintain. When choosing names for files, functions, or variables, prioritize them in this order:
i, j, and k for simple loop counters or throw-away local variables.UNITY_EXCLUDE_BLAH or UNITY_USES_BLAH for configuration macros).release_invoker instead of a generic name).When standard Expect functions are insufficient, you can use callbacks or stubs to implement custom logic. CMock provides two primary ways to do this, which reset the function's call count to zero:
func_AddCallback: The mock performs normal argument and calling order checks (based on your Expect setup) before executing the callback.func_Stub: The mock skips all normal checks and jumps directly to your custom callback, effectively replacing the mock's default behavior.The callback signature depends on the original function's signature:
void func(void) $\rightarrow$ void func_[AddCallback,Stub](CMOCK_func_CALLBACK callback) where CMOCK_func_CALLBACK is void func(int NumCalls)void func(params) $\rightarrow$ void func_[AddCallback,Stub](CMOCK_func_CALLBACK callback) where CMOCK_func_CALLBACK is void func(params, int NumCalls)retval func(void) $\rightarrow$ void func_[AddCallback,Stub](CMOCK_func_CALLBACK callback) where CMOCK_func_CALLBACK is retval func(int NumCalls)retval func(params) $\rightarrow$ void func_[AddCallback,Stub](CMOCK_func_CALLBACK callback) where CMOCK_func_CALLBACK is retval func(params, int NumCalls)NumCalls represents the number of calls made since the current stub or callback was installed. You can also query the current call count at any time using func_CallCount().
// Example: Using a callback to return a specific value via a pointer
// Assuming: uint divide(uint n, uint d, uint *result);
uint result_1 = 42;
divide_ExpectAndReturn(5, 2, NULL, TRUE);
divide_IgnoreArg_result();
divide_ReturnThruPtr_result(&result_1);CMock is designed to mock C functions and C++ static member methods. It does not mock non-static (instance) members; for those, you should use a dedicated C++ mocking framework.
When mixing CMock with a C++ framework, you may encounter multiple definition errors because the C++ framework might link the real object. To resolve this, use the weak attribute in your real implementation for any functions that CMock mocks:
#if defined(TEST)
__attribute__((weak))
#endifTo avoid collisions with namespaces or classes, CMock generates function names by including the namespace and class hierarchy.
Example Mapping: If you have:
namespace MyNamespace {
class MyClass {
static int DoesSomething(int a, int b);
};
}CMock will generate:
void MyNamespace_MyClass_DoesSomething_ExpectAndReturn(int a, int b, int toReturn);
namespace MyNamespace {
class MyClass {
static int DoesSomething(int a, int b);
};
}
// Generates:
// void MyNamespace_MyClass_DoesSomething_ExpectAndReturn(int a, int b, int toReturn);CMock supports various plugins to extend its mocking capabilities:
void* and provides _ExpectWithArray / _ExpectWithArrayExtended for array-based argument verification.StopIgnore (added in 2.5.1) to control the ignoring of calls.As of CMock 2.7.0, array and pointer handling has been significantly improved:
char* (string) arguments as byte arrays using _ExpectWithArray, while still allowing them to be treated as strings via _Expect._ExpectWithArrayExtended is generated as a fallback to allow you to explicitly override the depth.void* Comparison:void* defaults to pointer comparison.void* defaults to byte-by-byte comparison.// Example of the improved array/pointer capabilities (conceptual)
// Using _ExpectWithArray for byte-wise comparison of a string
_ExpectWithArray(my_function, my_string_ptr, length);
// Using _Expect for standard string comparison
_Expect(my_function, my_string_ptr);To improve clarity and visual organization, use the following emojis in commit messages, Issues, and Feature Requests:
Actions
:seedling: (or :cactus:, :herb:, :evergreen_tree:, :palm_tree:, :deciduous_tree:, :blossom:): Growing new features:art:: Improving code format/structure:racehorse:: Improving performance:non-potable_water:: Plugging memory leaks:memo:: Writing documentation:bug: (or :beetle:, :ant:, :honeybee:): Fixing a bug:fire:: Removing code or files:green_heart:: Fixing the CI build:white_check_mark:: Adding tests:lock:: Dealing with security:arrow_up:: Upgrading dependencies:arrow_down:: Downgrading dependencies:shirt:: Removing linter warningsPlatforms
:penguin:: Fixing something on Linux:apple:: Fixing something on macOS:checkered_flag:: Fixing something on WindowsCMock can be installed using several methods depending on your build environment:
git clone --recursive https://github.com/throwtheswitch/cmock.gitConsistency with the existing codebase is required. When modifying files, follow the established style, formatting, and naming conventions (e.g., if private properties use an underscore prefix _, continue using that pattern; if methods use camelCase, do not switch to snake_case).
Linting is enforced for the following languages:
If you are using Unity's test runner generator scripts or Ceedling, a resetTest function is generated in your runner.
Calling resetTest() during a test will:
This is useful for testing a single function multiple times with different arguments within the same test case.