avengineers / hammocking

Automatic mocking tool for C

HammocKing

Automatic mocking tool for C

CI

Build

This project uses Pipenv. Run the following command to install it using your system's Python >=3.6 installation:

pip install pipenv

To create a virtual environment for development run:

pipenv install --dev

To delete the currently used virtual environment run:

pipenv --rm

To debug your Python code in VS Code you need to activate the virtual environment. To activate this project's virtualenv, run:

pipenv shell

After that you can select the virtual env in the list of Python installations.

Run all tests:

pipenv run pytest --verbose --capture=tee-sys

TODO: Somehow pytest fails when already installed in the system's python distribution. Uninstall it:

pip uninstall pytest

Concept

The basic idea of HammocKing is to use Python and libclang to process and parse sources of an item under test (IUT) for automatic creation of mockups.

Used libraries/sources/repos:

• libclang

How to create and publish a pypi package

$ # Change version in setup.py to e.g. 0.5.0
$ python setup.py sdist
$ twine upload --repository-url https://test.pypi.org/legacy/dist/hammock-0.5.0.tar.gz

hammocking's Issues

Hammock as SPL extension ([email protected])

As Avengineer I want to be able to use hammock in my daily TDD work.

Acceptance criteria:

• Hammock repo is public containing necessary information. 👍
• Hammock is available as PIP package (via pypi.org). 👍
• Hammock contains CMake glue for integration in any SPL.
  --> CMake glue is currently in spl-core 👍
• SPLDemo contains usage example incl. GTest and GMock. 👍
• SPLDemo does not contain any Unity and/or CMock stuff. 👍

No C linkage when symbol is found in C file directly

Problem: When a function is not found in a header but on C-file level, no #include is created which establishes the interface with C linkage.
The function is therefore having C++ linkage.

Solution: Modify the template to wrap the C function shims with explicit C linkage

Function-like mockup interface

As a SW developer I would like to have a nice and neat mockup interface to make my tests readable.

E.g., mimicc creates nice mockups:

• https://mimicc.dev/mimicc-resource/userguidehtml/#mock-api-reference
• https://github.com/avengineers/hammock/tree/feature/mimicc-playground/resources/mini_c (main.c and mock-main.h)
  • created with mimicc -c -o mock_main.o main.h -Wall --hout=mock-main.h -v

Acceptance criteria:

• Mockup expect() interface is available to check that function foo() is called at least once, e.g., HAM_FUNC(foo).expect() 👍
• Mockup expect() interface is available to check that function foo(var a, var b) is called at least once with expected parameters, e.g., HAM_FUNC(foo).expect(someValueForA, someValueForB) 👍
• Mockup returns() interface is available, e.g., HAM_FUNC(foo).returns(someReturnValueOfFoo) 👍

Issue is solved by creating gmock mockups. See https://google.github.io/googletest/reference/mocking.html

Hammock PoC

As an SWE I want to be able to write unit tests without caring for mocking of used external symbols.

Acceptance criteria:

• We know how to implement an auto mocker. 👍
• Prototype in with tests and CI actions for Linux and Windows is available. 👍

Compiler options handling

We need to be able to pass all options from compiler command line to libclang for proper preprocessing of sources to be scanned.

Acceptance criteria:

• Command line interface exists to pass compiler options to libclang.
• libclang finds the correct symbols according to possible preprocessor definitions, include paths and files. 👍

Variable output file names

Following requirement shall be satisfied by HamMocKing:

• Req_HammocKing_0001: There shall be an optional command line argument to define file names of the output files. Templating-Engine shall know about the filename(s). Usecase: gmock/mockup.cc.j2 contains an include-statement which needs to be adapted to the target filename of template gmock/mockup.h.j2.

Additional work shall be done within this issue:

• Add a new chapter "Design" to documentation (in a new file)
• Add a new chapter "Requirements" to documentation (in a new file)
• Start the list of requirements with above one.

We need a new release for it by the end of 2022CW36.4.THU because spldemo needs it via dependendy to spl-core .

Mocking mode: automatic creation of mockups

As SWE I don't care for missing symbols. When my IUT is defined (productive sources, test sources, ...) I want to be able to build an executable and run tests.

Acceptance criteria:

• Courage's concept of "partial linking" is used. 👍
• Get unresolved symbols of partially linked object with nm. 👍
  • Before implementing a command line interface for nm we checked for libclang's capability. 👍
• Command line interface for (partially linked) object(s) instead of missing symbols exists. 👍

Full Integration of Hammock in SPL and/or CMake

As Avengineer I want to have one nice and neat CMake integration (function, macro, whatsoever) to create mockups.

Acceptance criteria:

• hammock can find missing symbols and mock them in one command line call.
• hammock is integrated in SPL build chain.
• hammock is integrated in some example CMake project (mini_c or holgi_c in hammock repo for integration tests).

Syntax error when mocking struct return type

typedef struct {...} struct_type;

struct_type some_function();

the empty mockup of some_function returns a 0, which does not work:
return (struct_type)0;

Instead, it needs to be the empty struct:
return (struct_type){0};

libclang parses like a C compiler

I looks like libclang incorporates a "C" compiler when parsing the sources.
This is a problem since the generated mockup.cc file will be compiled as C++; headers may parse differently dependent on the mode.

For example, the bool type from <stdbool.h> is #defined to int when parsed by libclang, but is a native type _Bool in C99 and C++ mode.

[build] /build/some_test/mockup.cc:21:5: error: functions that differ only in their return type cannot be overloaded
[build] int func_x(uint8_t arg){
[build] ~~~ ^
[build] /project/include/some_include.h:65:6: note: previous declaration is here
[build] bool func_x(uint8_t arg);
[build] ~~~~ ^

We need to control the compiler that libclang incorporates to be the same C++ compiler that will compile the code.

Provide explicit disposal of mockup object

Motivation: Passing around the local mockup object might be tedious when it comes to test helpers:

void helper(class_mockup &mock, ...) {
  ON_CALL(mock, uninteresting_function).WillByDefault(do_something);
}

TEST(XYZ, test_something) {
   CREATE_MOCK(mock);
   helper(mock, other_args);
   EXPECT_CALL(mock, other_calls);
  ... 
}

What is even more severe, when some generic behavior shall be established in the test fixture, the object needs to be passed down to the test, which is then destroyed too early.

class XYZ : public testing::Test {
 protected:
   void SetUp() override { 
      CREATE_MOCK(m);
      mock = &m;
      ON_CALL(m, uninteresting_function).WillByDefault(do_something);
   }  /* Here, the object is already destroyed and no longer available in the test. */
   class_mockup* mock;
};

TEST_F(XYZ, test1)
{
   EXPECT_CALL(*mock, another_function).WillReturnOnce(etc.);
  ...
}

The target is to have the ability of both minimum-effort mocking like today, with CREATE_MOCK() in the test function (automatic cleanup at end of test) and a controlled SetUp / TearDown macro for the fixture.

Syntax error when mocking constants

A constant variable needs an initializer.

const some_type var;

needs to be mocked as:

const some_type var = (some_type)0;

(Also consider array and struct types)

pass Compiler flags to clang

When clang processes the sources, it will need compiler flags, such as include search pathes.
--> Extra args to hammocking are passed on to the compiler, so this is basically a matter of the integration example.

Mocking mode: mockups from headers

mimicc does it, CMock tries to do it, so maybe hammock should support it, too?

Syntax error when mocking array type parameter

Mocking a parameter like:
void some_function(char string[]);

Results in the following implementation, which is syntax error:

void some_function(char[] string)
{
...
}

Exclusion option for symbols that shall not be mocked

It may be requested that an interface is not mocked by hammock, but directly implemented by the test code.
Be it that mocking goes wrong for inabilities of hammock, or wish by the user.
This is not possible with the current workflow, that hammocking takes place before the test code is compiled.

As a quick-and-easy solution, hammock shall accept as a parameter a list of symbols that are not mocked.

Bootstrap documentation

Documentation shall exist with following constraints:

• Use restructured text with sphinx 👍
• Plantuml shall be integrated 👍
• Build shall generate html pages automatically 👍