Support test-specific header injection for generated mock files

[JannisRln]

Feature request

First of all, thank you for Ceedling/CMock. It is a great framework and very useful for embedded C testing. I really appreciate the work that has gone into making unit testing in C more practical.

I would like Ceedling/CMock to support injecting additional header files from a specific test file into generated mock files, without applying those includes globally to every generated mock.

Current behavior / limitation

CMock already provides include-related configuration options such as:

#:includes: []                   # You can add additional includes here, or specify the location with the options below
:includes_h_pre_orig_header: ['bds_canopen_obj_api_for_mock.h']
#:includes_h_post_orig_header: []
#:includes_c_pre_header:  []
#:includes_c_post_header:  []

These options are useful, but they appear to apply broadly across generated mocks/tests. In my case, adding a header this way injects it into each test/mock generation context.

This can lead to unwanted includes, unnecessary dependencies, and possible conflicts in tests that do not need those headers.

Problem

Some tests require mock-specific or test-specific headers, for example to provide:

• additional type definitions
• macros
• test-only configuration
• platform-specific declarations
• compatibility wrappers for a specific mocked interface

However, these headers should only be included for the mock used by a particular test file, not globally for all generated mocks.

Manually editing generated mock files is not practical because those files are regenerated by Ceedling/CMock.

Proposed solution

Add a way for a test file to declare extra includes for a specific generated mock.

For example, using an annotation-style directive:

// In test_driver.c

#include "unity.h"
#include "mock_driver.h"

// Desired feature:
// inject only into mock_driver.c / mock_driver.h for this test
// @mock_include "test_driver_types.h"

Or with a more explicit mock target:

// @mock_include mock_driver "test_driver_types.h"

As an alternative, this could use a macro-like syntax similar to the already supported TEST_INCLUDE_PATH(...) mechanism for test include paths:

// In test_driver.c

#include "unity.h"
#include "mock_driver.h"

// Desired feature:
// inject only into mock_driver.c / mock_driver.h for this test
TEST_MOCK_INCLUDE("mock_driver.h", "test_driver_types.h")

or, if the mock name should be used instead of the mock header:

TEST_MOCK_INCLUDE(mock_driver, "test_driver_types.h")

A more location-specific variant could also mirror the existing CMock include placement options:

TEST_MOCK_INCLUDE_H_PRE_ORIG_HEADER(mock_driver, "test_driver_types.h")
TEST_MOCK_INCLUDE_H_POST_ORIG_HEADER(mock_driver, "test_driver_types.h")
TEST_MOCK_INCLUDE_C_PRE_HEADER(mock_driver, "test_driver_config.h")
TEST_MOCK_INCLUDE_C_POST_HEADER(mock_driver, "test_driver_config.h")

This would cause CMock to inject the header only into the generated mock file associated with that test/mock combination, instead of injecting it into every mock.

Desired behavior
Existing global CMock include options continue to work as they do today.
Additional includes can be scoped to a specific test file and mock.
Includes are not injected into unrelated generated mocks.
Generated files do not need to be manually edited.
The feature supports the same include locations already available globally:

:includes_h_pre_orig_header
:includes_h_post_orig_header
:includes_c_pre_header
:includes_c_post_header

Benefit

This would make it easier to test embedded C projects where some mocks need test-specific helper headers, without polluting every generated mock with unnecessary includes or causing include conflicts in unrelated tests.

Thanks again for maintaining Ceedling/CMock. It is a valuable framework, and this feature would make it even more flexible for complex embedded test setups.

[mkarlesky]

@JannisRln Thank you for submitting this. Can you explain more on why the chain of source includes is not enough? CMock generates a mock from a given header file and includes that source header file in the mock header file. That linkage should give access to all symbols that the mock needs. What kind of extra symbols do you need in your mock beyond this?

[JannisRln]

@mkarlesky I’ll provide an example on Monday.

We use a vendor-provided CANopen stack where I need to inject additional headers via CMock project settings (the YAML file). However, when I apply those settings, the headers are injected into all generated mocks, including modules that are unrelated to CANopen test.

Maybe I have overseen a simple solution. I check this Monday. Currently it is holiday in Germany.

Edit:
I mean the vendor uses Marcos in the header file that causes the problem.

[JannisRln]

@mkarlesky

The CANopen stack appears to have incomplete, non-self-contained headers. Some headers use types that are defined in other headers, but they do not include those dependency headers themselves.

I know this is bad design in the vendor stack, but I currently need to live with it.

In normal application code, I can work around this by including the type-definition header first, followed by the function/API header.

However, this becomes a problem when generating mocks. If I mock a function header directly, the generated mock_*.c file does not automatically include the missing type-definition header.

I worked around this by using CMock's :includes_h_pre_orig_header: option:

:includes_h_pre_orig_header:
  - 'bds_canopen_obj_api_for_mock.h'

This injects the required header into the generated mock file before the original header is included.

I think this approach solves the problem for bad or incomplete vendor APIs like this. However, if I use this option globally, Ceedling/CMock injects this header into all generated mocks. That also feels like a code smell.

In a small project, I can live with this. But if the project needs to support more than one CANopen stack, this can cause problems because a vendor-specific compatibility header may be included in mocks where it does not belong.

Maybe this could be solved with compiler flags, but ideally I do not want to inject this compatibility header into every mock file in the first place. What I would need is a way to inject a specific extra include only for a specific mocked header.

Example problem

Assume the vendor stack provides a type header like this:

/* canopen_types.h */
typedef struct
{
    int node_id;
} CanOpenNode;

And an API header like this:

/* canopen_api.h */

/* Problem:
 * This header uses CanOpenNode but does not include canopen_types.h.
 */
void canopen_init(CanOpenNode *node);

This only works if the application includes the headers in the correct order:

#include "canopen_types.h"
#include "canopen_api.h"

But it fails if canopen_api.h is included by itself, for example by a mock generator:

/* mock_canopen_api.h */

/* Missing required include:
 * #include "canopen_types.h"
 */
#include "canopen_api.h"

/* Error:
 * unknown type name 'CanOpenNode'
 */

Normally, the better design would be to make canopen_api.h self-contained:

/* canopen_api.h */
#ifndef CANOPEN_API_H
#define CANOPEN_API_H

#include "canopen_types.h"

void canopen_init(CanOpenNode *node);

#endif

But since this is a vendor stack, I cannot easily fix the original header. Therefore, I need a CMock/Ceedling-level workaround that lets me add this missing include only for the affected mock, instead of adding it globally to every generated mock.