CMock semantics reference

CMock is, per github.com/ThrowTheSwitch/CMock (opens in new window), "a mock and stub generator and runtime for unit testing C" that "automagically parses your C headers and creates useful and usable mock interfaces for unit testing". CMock only exists inside the Ceedling / Unity workflow this skill orchestrates - see SKILL.md (opens in new window) for the build tasks and project.yml wiring, and unity-test-framework-c for the assertion API.

This reference covers CMock's generated API surface and the cmock.yml plugin model: decoding which plugin produced which API when reading a mock-driven suite, choosing between strict expectations / ignored arguments / return-thru-pointer when authoring a new mock, and migrating a legacy fake-by-hand to a CMock-generated mock.

Mock / Stub / Spy / Fake in C

The English vocabulary is from Meszaros's xUnit Test Patterns (book, cite by ISBN 978-0131495050); CMock encodes all four shapes through one generated family.

What CMock generates from a header

Given parser.h:

int parse_message(const char *buf, size_t len, message_t *out);

CMock generates mock_parser.h and mock_parser.c. The generated API for parse_message is (per github.com/ThrowTheSwitch/CMock/blob/master/docs/CMock_Summary.md (opens in new window)):

// Strict expectations
void parse_message_Expect(const char *buf, size_t len, message_t *out);
void parse_message_ExpectAndReturn(const char *buf, size_t len, message_t *out, int retval);

// Argument-flexibility (requires :expect_any_args plugin)
void parse_message_ExpectAnyArgs(void);
void parse_message_ExpectAnyArgsAndReturn(int retval);

// Array depth (requires :array plugin)
void parse_message_ExpectWithArray(const char *buf, int buf_depth, size_t len, message_t *out, int out_depth);
void parse_message_ExpectWithArrayAndReturn(const char *buf, int buf_depth, size_t len, message_t *out, int out_depth, int retval);

// Per-argument ignore (requires :ignore_arg plugin)
void parse_message_IgnoreArg_buf(void);
void parse_message_IgnoreArg_len(void);
void parse_message_IgnoreArg_out(void);

// Whole-function ignore (requires :ignore or :ignore_stateless plugin)
void parse_message_Ignore(void);
void parse_message_IgnoreAndReturn(int retval);
void parse_message_StopIgnore(void);

// Pointer-return injection (requires :return_thru_ptr plugin)
void parse_message_ReturnThruPtr_out(message_t *val_to_return);
void parse_message_ReturnArrayThruPtr_out(message_t *val_to_return, int len);
void parse_message_ReturnMemThruPtr_out(message_t *val_to_return, size_t size);

// Callback / stub (requires :callback plugin)
void parse_message_AddCallback(CMOCK_parse_message_CALLBACK callback);
void parse_message_Stub(CMOCK_parse_message_CALLBACK callback);

// Exception throwing (requires :cexception plugin)
void parse_message_ExpectAndThrow(const char *buf, size_t len, message_t *out, CEXCEPTION_T value_to_throw);

All of the above family names are cited from the CMock Summary doc above. The generated function names follow the rigid pattern <original_function_name>_<CMockVerb>[_<paramName>].

cmock.yml :plugins list

Each generated API family is gated on a plugin in cmock.yml (typically inlined into Ceedling's project.yml under :cmock: :plugins: - per the same CMock summary doc):

A minimal cmock.yml for a typical embedded suite:

:cmock:
  :mock_prefix: Mock
  :mock_suffix: ""
  :plugins:
    - :ignore
    - :ignore_arg
    - :expect_any_args
    - :array
    - :callback
    - :return_thru_ptr

:cexception is added only if the project uses CException.

Mock-naming convention

Per the CMock summary doc, the mock module name is built from :mock_prefix + original module name + :mock_suffix. With the default :mock_prefix: Mock:

In a test (test_consumer.c), include the mock header:

#include "unity.h"
#include "Mockparser.h"      // CMock-generated
#include "consumer.h"        // under test

Ceedling automatically detects the Mock* include and generates the mock at test-build time.

Test lifecycle: setUp / tearDown / resetTest

CMock hooks into Unity's per-test lifecycle:

Forgetting to register a mock causes link errors, not test failures - the mock is the only definition of the symbol.

Argument-matching modes

CMock's default mode is strict by argument: passed arguments must memcmp-equal the expected. The user softens with:

For pointer arguments to structs, the default is deep-equal by size - CMock memcompares the pointed-to memory. For string pointers, treat as strcmp only if the deep-equal of the buffer matches the string length CMock chose at generation; in practice, use _IgnoreArg_<param> + a _AddCallback for string-matching.

Worked example

A consumer module that calls a parser; the test verifies the expected call shape:

// consumer.h - under test
int consume(const char *raw);

// consumer.c
#include "parser.h"
int consume(const char *raw) {
    message_t m;
    if (parse_message(raw, strlen(raw), &m) != 0) return -1;
    return m.kind;
}

// test_consumer.c
#include "unity.h"
#include "Mockparser.h"
#include "consumer.h"

void test_consume_returns_kind_on_success(void) {
    message_t out_fixture = { .kind = 7 };

    parse_message_ExpectAndReturn("PING", 4, NULL, 0);
    parse_message_IgnoreArg_out();
    parse_message_ReturnThruPtr_out(&out_fixture);

    TEST_ASSERT_EQUAL_INT(7, consume("PING"));
}

void test_consume_returns_negative_one_on_parse_error(void) {
    parse_message_ExpectAnyArgsAndReturn(-1);
    TEST_ASSERT_EQUAL_INT(-1, consume("BADINPUT"));
}

The first test: strict on buf + len, lenient on out, then write the fixture through the out-pointer. The second: count matters, args don't.

CMock anti-patterns

CMock limitations

• CMock parses C headers, not preprocessed source. Macros that hide function declarations are invisible - generators miss them.
• Function pointers in structs need explicit handling. CMock generates a per-symbol mock; a function-pointer field in a struct is not a symbol and isn't directly mockable. Define a typed wrapper.
• Vararg functions partially supported. Per the CMock summary doc, vararg mocking is limited; consider wrapping a vararg function before mocking.
• Generated code grows with module size. A 200-function header produces ~200×8 generated functions; build time matters. Split the header.
• Argument-deep-compare can be misleading on structs with pointer members. The pointed-to memory is not recursively compared - only the pointer value. Use _AddCallback for structures-with-pointers.
• Not thread-safe. CMock's expectation queue is per-process global state; concurrent tests in the same process collide. Ceedling runs tests serially by default - keep it that way.

Ceedling project.yml schema

Per CeedlingPacket.md, the canonical top-level sections. Copy-paste template:

:project:
  :build_root: build/
  :release_build: TRUE
  :use_mocks: TRUE
  :use_exceptions: TRUE
  :use_test_preprocessor: :all
  :test_file_prefix: test_

:paths:
  :test:
    - test/**
  :source:
    - src/**
  :include:
    - inc/**
  :support: []
  :libraries: []

:files:
  # .c, .h, .o extension mappings - usually default values

:defines:
  :test:
    - UNITY_INCLUDE_DOUBLE
  :release:
    - NDEBUG

:flags:
  :release:
    :compile:
      '*':
        - -O2
        - -Wall
    :link:
      '*':
        - -Wl,--gc-sections
  :test:
    :compile:
      '*':
        - -O0
        - -g
        - --coverage
    :link:
      '*':
        - --coverage

:tools:
  # Override compiler / linker / preprocessor executables here

:test_runner:
  :includes:
    - "Mock*.h"

:unity:
  :defines:
    - UNITY_INCLUDE_DOUBLE

:cmock:
  :when_no_prototypes: :warn
  :enforce_strict_ordering: TRUE
  :plugins:
    - :ignore
    - :ignore_arg
    - :expect_any_args
    - :array
    - :callback
    - :return_thru_ptr

:cexception:
  :defines:
    - CEXCEPTION_T='signed char'

:gcov:
  :reports:
    - HtmlDetailed
    - Cobertura
  :gcovr:
    :report_root: src/

:plugins:
  :enabled:
    - report_tests_pretty_stdout
    - report_tests_junit_xml
    - gcov
    - module_generator

Section notes

• :project holds the global on/off switches: :use_mocks, :use_exceptions, :test_file_prefix, :build_root.
• :paths supports glob patterns; '*' under :flags matches all files.
• :defines splits test-only vs release-only -D symbols (UNITY_INCLUDE_DOUBLE is a test-only define).
• :tools is where a cross-build overrides the compiler to arm-none-eabi-gcc.
• :unity sets Unity build-time defines, e.g. UNITY_INT_WIDTH=16 for 16-bit MCUs.
• :cmock plugin list - see cmock.md (opens in new window).
• :cexception type override; default is int, some MCUs prefer signed char.
• :gcov report formats: HtmlDetailed, Cobertura, SonarQube.

Plugins

Ceedling task reference

Per the CeedlingPacket task reference. The SKILL spine keeps ceedling test:all, ceedling gcov:all, and the compound CI invocation; the full surface follows.

Test tasks

ceedling test:all                          # Run every test_*.c
ceedling test:ringbuffer                   # Run only test_ringbuffer.c
ceedling test:pattern[ringbuffer]          # Regex match on test file basename
ceedling test:path[test/components]        # Tests under a path
ceedling test:ringbuffer --test-case=push  # Run only test cases matching 'push'

--test-case=<pattern> is the equivalent of GoogleTest's --gtest_filter.

Release build

ceedling release                # Build production binary
ceedling release:compile:foo.c  # Compile a single file

release is opt-in (:project: :release_build: TRUE in project.yml). Use it for the actual firmware build, not for tests.

Maintenance

ceedling clean        # Remove .o files
ceedling clobber      # Remove all generated files (build/, generated runners, mocks)
ceedling environment  # Print environment (CC, PATH, etc.)
ceedling dumpconfig   # Print the merged project.yml
ceedling help         # Task list
ceedling version      # Ceedling version

dumpconfig is the reliable way to debug mysterious flag behaviour - Ceedling merges several layers (defaults, project, plugin) and the final flags can surprise.

Compound tasks

Tasks chain on the command line:

ceedling clobber test:all release gcov:all
# Clean -> run tests -> build release -> produce coverage report

This is the canonical CI invocation.