|buildstatus|_
|coverage|_
|codecov|_
🦁 Nala
=======
A delightful test framework for `C` projects.
Based on `Narwhal`_ and `Narmock`_.
Features
========
- Automatic test discovery
- Use the same generic assertions everywhere
- Assertion failures reported as diffs
- Powerful mocking
- Easy-to-use output capturing utilities
- Traceback(s) on failure
- Works well with errors reported by sanitizers
- Test isolation with ``fork()``
- Only run tests matching given pattern
- Automatic build and run on file change
- Optional parallel test execution to save time
- Amalgamated source and header files ready to drop in your project
- JSON test report
Installation
============
It's recommended to install `Nala` with ``pip``. Only Python 3 is
supported.
.. code-block:: bash
$ pip install nala
Alternatively, if mocking is not needed, you can download the
`amalgamated`_ header and source files:
- `nala.h`_
- `nala.c`_
Drop the two files in your project, make sure ``nala.c`` is compiled
and linked just like the other source files of your test program and
you should be good to go.
Getting started
===============
|tryit|_
Use ``nala init foo`` to create a folder ``foo`` with two test files,
``test_assertions.c`` and ``test_time.c``. The first uses all
assertions and captures output, and the second mocks the time
function.
.. code-block:: bash
$ nala init foo
Run 'make -C foo' to build and run all tests!
The assertions tests looks like this:
.. code-block:: c
#include "nala.h"
TEST(assertions)
{
int i;
int array[] = { 1, 5, 2 };
ASSERT_EQ(NULL, NULL);
ASSERT_NE(1, 2);
ASSERT_LT(1.0, 2.0);
ASSERT_LE(1, 1);
ASSERT_GT(2L, 1L);
ASSERT_GE(1, 1);
ASSERT_TRUE(true);
ASSERT_FALSE(false);
ASSERT_SUBSTRING("12345", "34");
ASSERT_NOT_SUBSTRING("12345", "4567");
ASSERT_MEMORY_EQ("abcd", "abcd", 5);
ASSERT_FILE_EQ("test_assertions.c", "test_assertions.c");
ASSERT_ARRAY_EQ(array, array, sizeof(array));
ASSERT_FUNCTION_POINTER_EQ(assertions, assertions);
ASSERT_FUNCTION_POINTER_NE(assertions, NULL);
ASSERT(1 == 1);
CAPTURE_OUTPUT(output, errput) {
printf("output!\n");
fprintf(stderr, "errput!\n");
}
ASSERT_EQ(output, "output!\n");
ASSERT_EQ(errput, "errput!\n");
for (i = 0; i < 3; i++) {
WITH_MESSAGE("i: %d", i) {
ASSERT_EQ(array[i], array[i]);
}
}
}
And the time tests:
.. code-block:: c
#include <time.h>
#include "nala.h"
TEST(mock_time)
{
time_mock_once(42);
ASSERT_EQ(time(NULL), 42);
}
Build and run all tests with ``make -s -C foo``.
.. image:: https://github.com/eerimoq/nala/raw/master/docs/build-and-run.png
Build all tests but only run those whose name contains ``time``. This
is done by giving ``ARGS=time``.
.. image:: https://github.com/eerimoq/nala/raw/master/docs/build-and-run-one-test.png
Run ``make -s -C foo auto`` to build and run all tests automatically
when any source file in your project is modified. With the command
running, make the time test fail by returning ``41`` instead of ``42``
from the time mock.
.. code-block:: c
#include <time.h>
#include "nala.h"
TEST(mock_time)
{
time_mock_once(41);
ASSERT_EQ(time(NULL), 42);
}
Notice how the test is built and run automatically.
.. image:: https://github.com/eerimoq/nala/raw/master/docs/build-and-run-assert-eq-fail.png
Create a code coverage report and open it with Firefox.
.. code-block::
$ make -s -C foo coverage
Code coverage report: /home/erik/workspace/nala/foo/build/coverage/index.html
$ firefox /home/erik/workspace/nala/foo/build/coverage/index.html
API
===
Below is a list of all macros and functions in the API. They are all
defined/declared in `include/nala.h`_.
Assertions
----------
.. code-block:: c
ASSERT_EQ(actual, expected); // Assert that given characters, numbers, pointers or
// strings are equal.
ASSERT_NE(actual, expected); // Assert that given characters, numbers, pointers or
// strings are not equal.
ASSERT_LT(actual, expected); // Assert that actual is less than expected.
ASSERT_LE(actual, expected); // Assert that actual is less than or equal to expected.
ASSERT_GT(actual, expected); // Assert that actual is greater than expected.
ASSERT_GE(actual, expected); // Assert that actual is greater than or equal to
// expected.
ASSERT_TRUE(actual); // Assert that given value is true.
ASSERT_FALSE(actual); // Assert that given value is false.
ASSERT_SUBSTRING(haystack, needle); // Assert that given haystack string contains given
// needle string.
ASSERT_NOT_SUBSTRING(haystack, needle); // Assert that given haystack string does not contain
// given needle string.
ASSERT_MEMORY_EQ(actual, expected, size); // Assert that given memory regions are equal.
ASSERT_FILE_EQ(actual, expected); // Assert that given files are equal.
ASSERT_ARRAY_EQ(actual, expected, size); // Assert that given arrays are equal.
ASSERT_FUNCTION_POINTER_EQ(actual, expected); // Assert that given function pointers are equal.
ASSERT_FUNCTION_POINTER_NE(actual, expected); // Assert that given function pointers are not equal.
ASSERT(cond); // Assert that given condition is true.
Other macros
------------
.. code-block:: c
FAIL(message); // Fail current test with given message.
CAPTURE_OUTPUT(stdout_name, stderr_name); // A capture output block.
WITH_MESSAGE(format, ...); // Additional message on error block. May be nested.
Functions
---------
.. code-block:: c
void *nala_alloc(size_t size); // Allocate a memory buffer of given size that is
// automatically freed after the test. Always returns
// a valid pointer.
void nala_auto_free(void *buf_p); // Automatically free given buffer after the test.
// free() is called to free the buffer.
void nala_exit(int status); // Performs post-test checks and cleanup, and then
// exits with status 0. The status parameter is
// ignored.
Mocking
=======
Generating mocks
----------------
The ``nala generate_mocks`` command finds mocked functions in your
test code and generates ``nala_mocks.h``, ``nala_mocks.c`` and
``nala_mocks.ldflags``. The first two files declare and define mocks,
while the last file contains linker flags.
Use ``--rename-parameters-file`` to rename function parameters, often
useful when mocking standard library functions. If not given, Nala
renames `a few function parameters`_ by default. Also, any
``__``-prefix is removed from all parameters.
Use ``--no-rename-parameters`` not to rename any function
parameters. Overrides ``--rename-parameters-file``.
Use ``--no-implementation`` when the implementation of functions
matching given Unix shell-style wildcards pattern are not available in
the binary (and therefore should not be called by the generated code,
as the linker would give a relocation error). This option may be given
multipe times. An alternative to using this option is to manually
implement the missing functions. Here is an example implementation of
``foo()`` that makes the test fail if called.
.. code-block:: c
int foo()
{
FAIL("No real implementation available!\n");
return (0);
}
Use ``--no-real-variadic-functions`` not to add any real variadic
functions. Nala adds `a few variadic functions`_ by default, given
that they are mocked.
Here is an example of how to generate mocks:
.. code-block:: bash
$ nala cat *.c | gcc -DNALA_GENERATE_MOCKS -x c -E - | nala generate_mocks
``nala cat *.c`` should only concatenate test source files, not any
other source files in your project.
Nala requires test source code to be expanded by the preprocessor. You
can directly pipe the output of ``gcc -DNALA_GENERATE_MOCKS -x c -E
-`` to the command-line utility.
Mocking object-internal function calls
--------------------------------------
The GNU linker ``ld`` wrap feature (``--wrap=<symbol>``) does not wrap
object-internal function calls. As Nala implements mocking by wrapping
functions, object-internal function calls can't be mocked just using
the linker. To mock these, after compilation, run ``nala
wrap_internal_symbols ...`` for each object file, and then pass them
to the linker.
Also, local (``static``) functions can't be mocked, only global
functions can!
.. code-block:: Makefile
%.o: %.c
$(CC) -o $@ $<
nala wrap_internal_symbols nala_mocks.ldflags $@
Mock API
--------
A function mock will call the real implementation by default. Use the
functions below to control mock object behaviour.
Variadic functions will *not* call the real implementation by
default. Give ``--implementation`` to ``nala generate_mocks`` to
generate calls to the real function (taking a ``va_list`` instead of
``...``).
There are plenty of mock-examples in the `examples folder`_. All
inline examples below can also be found in the `mock_api_examples`_
example.
For all functions
^^^^^^^^^^^^^^^^^
``<params>`` is all char-pointer (string) and primitive type
parameters of the mocked function.
Same behaviour for every call.
.. code-block:: c
void FUNC_mock(<params>, <res>); // check parameters and return
void FUNC_mock_ignore_in(<res>); // ignore parameters and return
void FUNC_mock_none(); // no calls allowed
void FUNC_mock_implementation(*); // replace implementation
void FUNC_mock_real(); // real implementation
An example:
.. code-block:: c
/* int foo(int value); */
TEST(foo_every_call)
{
foo_mock(1, 2);
/* All calls to foo() expects its parameter to be 1 and returns 2. */
ASSERT_EQ(foo(1), 2);
ASSERT_EQ(foo(1), 2);
}
Per call control.
.. code-block:: c
int FUNC_mock_once(<params>, <res>); // check parameters and return once (per call)
// returns a mock instance handle
int FUNC_mock_ignore_in_once(<res>); // ignore parameters and return once (per call)
// returns a mock instance handle
void FUNC_mock_real_once(); // real implementation once (per call)
An example:
.. code-block:: c
/* int foo(int value); */
TEST(foo_per_call)
{
foo_mock_once(1, 2);
foo_mock_once(4, 5);
/* First call to foo() expects its parameter to be 1 and returns 2. */
ASSERT_EQ(foo(1), 2);
/* Second call to foo() expects its parameter to be 4 and returns 5. */
ASSERT_EQ(foo(4), 5);
/* Third call will fail and the test will end. */
foo(10);
}
Changes the behaviour of currect mock object (most recent ``*_mock()``
or ``*_mock_once()`` call). Works for both per call and every call
functions above.
.. code-block:: c
void FUNC_mock_set_errno(int); // errno on return, 0 by default
void FUNC_mock_set_callback(*); // additional checks and/or actions
// called just before returning from the mock
An example:
.. code-block:: c
/* int foo(int value); */
TEST(foo_set_errno)
{
foo_mock_once(1, 2);
foo_mock_set_errno(EINVAL);
ASSERT_EQ(foo(1), 2);
ASSERT_EQ(errno, EINVAL);
}
Get per call input parameters.
.. code-block:: c
*FUNC_mock_get_params_in(int); // get input parameters for given mock instance
// handle
An example:
.. code-block:: c
/* typedef void (*callback_t)(void); */
/* void bar(callback_t callback); */
static void fie(void)
{
printf("fie() called!\n");
}
TEST(bar_get_params_call_callback)
{
int handle;
handle = bar_mock_once();
bar(fie);
/* Call the callback (calls fie()). */
bar_mock_get_params_in(handle)->callback();
}
For pointer and array function parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Changes the behaviour of currect mock (most recent ``*_mock()`` or
``*_mock_once()`` call). Works for both per call and every call
functions above.
.. code-block:: c
void FUNC_mock_set_PARAM_in(*, size_t); // check on input
void FUNC_mock_set_PARAM_in_assert(*); // custom assert function on input
void FUNC_mock_set_PARAM_in_pointer(*); // check pointer (the address) on input
void FUNC_mock_set_PARAM_out(*, size_t); // value on return
void FUNC_mock_set_PARAM_out_copy(*); // custom output copy function
An example:
.. code-block:: c
/* struct foo_t { char *string_p }; */
/* void fum(int *value_p, struct foo_t *foo_p); */
static void assert_foo_string(struct foo_t *actual_p,
struct foo_t *expected_p,
size_t size)
{
ASSERT_EQ(size, sizeof(*expected_p));
ASSERT_EQ(actual_p->string_p, expected_p->string_p);
}
TEST(fum_in_out)
{
int value;
struct foo_t foo;
fum_mock_once();
/* Expect *value_p to be 1 when fum() is called, and assign 2 to
it before returning. */
value = 1;
fum_mock_set_value_p_in(&value, sizeof(value));
value = 2;
fum_mock_set_value_p_out(&value, sizeof(value));
/* Use a custom parameter assert function to check that
foo_p->string_p is "Hello!" when fum() is called. */
foo.string_p = "Hello!";
fum_mock_set_foo_p_in(&foo, sizeof(foo));
fum_mock_set_foo_p_in_assert(assert_foo_string);
value = 1;
foo.string_p = "Hello!";
fum(&value, &foo);
ASSERT_EQ(value, 2);
}
For function parameters part of <params>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Changes the behaviour of currect mock object (most recent ``*_mock()``
or ``*_mock_once()`` call). Works for both per call and every call
functions above.
.. code-block:: c
void FUNC_mock_ignore_PARAM_in(); // ignore on input
An example:
.. code-block:: c
/* void foo(int value); */
TEST(foo_ignore_value)
{
foo_mock_once(1, 2);
foo_mock_ignore_value_in();
ASSERT_EQ(foo(9), 2);
}
For variadic functions
^^^^^^^^^^^^^^^^^^^^^^
Variadic function mocks are slightly different from the above. Their
parameter list is extended with a format string (``format``) and an
ellipsis (``...``), as shown below.
.. code-block:: c
void FUNC_mock(<params>, <res>, format, ...);
void FUNC_mock_once(<params>, <res>, format, ...);
void FUNC_mock_ignore_in(<res>, format);
void FUNC_mock_ignore_in_once(<res>, format);
The format string supports the following specifiers.
.. code-block::
%d - signed integer
%u - unsigned integer
%ld - signed long integer
%lu - unsigned long integer
%p - pointer address
%s - string
The ``%p`` specifier takes no value when calling the mock function,
just like pointers are not part of the mock function parameters
list. Instead, set pointers after the mock call.
.. code-block:: c
foo_mock(3, "%d%p%s", 5, "the-string");
foo_mock_set_va_arg_in_pointer_at(1, NULL);
The variadic parameters are controlled by index instead of name.
.. code-block:: c
void FUNC_mock_ignore_va_arg_in_at(uint); // ignore on input
void FUNC_mock_set_va_arg_in_at(uint, *, size_t); // check on input
void FUNC_mock_set_va_arg_in_assert_at(uint, *); // custom assert function on input
void FUNC_mock_set_va_arg_in_pointer_at(uint, *); // check pointer (the address) on input
void FUNC_mock_set_va_arg_out_at(uint, *, size_t); // value on return
void FUNC_mock_set_va_arg_out_copy_at(uint, *); // custom output copy function
Limitations
-----------
- Structs and unions passed by value are ignored.
- ``va_list`` parameters are ignored.
- ``malloc()`` and ``free()`` can't be mocked if forking and using
gcov. They probably can if wrapping ``__gcov_fork()`` in an
suspend/resume-block.
- ``static`` functions can't be mocked.
- Only primitive data type members are asserted when comparing
structs. Pointer and union members are not asserted, and probably
never will be.
Debugging tips
==============
Nala executes each test in its own process. This means that following
the execution of a test with a debugger can be a bit tricky because
debuggers like `GDB`_ can only follow a single process at a time.
If you're using `GDB`, set a breakpoint at ``<test>_before_fork`` and
then run the program until it stops at the breakpoint. Before
continuing the program execution, tell `GDB` to follow the forked test
process by setting ``follow-fork-mode`` to ``child``.
Below are all commands to debug the ``assertions`` test in the example
above.
.. code-block::
$ gdb foo/build/app
(gdb) b assertions_before_fork
(gdb) r
(gdb) set follow-fork-mode child
(gdb) c
The ``gdb`` make target starts `GDB` and runs all commmands listed
above. Set the ``TEST`` make variable to the test to debug. Both
``TEST=test_assertions::assertions`` and ``TEST=assertions`` are
accepted. The test name may be partialy given, as long as it only
matches one test.
.. code-block::
$ make -s -C foo gdb TEST=assertions
The test program takes optional arguments as below, which also can be
helpful when debugging, especially ``--print-all-calls``.
.. code-block::
$ foo/build/app --help
usage: foo/build/app [-h] [-v] [-c] [-a] [-r] [-f] [-j] [<test-pattern>]
Run tests.
positional arguments:
test-pattern Only run tests matching given pattern. '^' matches
the beginning and '$' matches the end of the test
name.
optional arguments:
-h, --help Show this help message and exit.
-v, --version Print version information.
-c, --continue-on-failure Continue on test failure.
-a, --print-all-calls Print all calls to ease debugging.
-r, --report-json-file JSON test report file (default: report.json).
-f, --print-test-file-func Print file:function for exactly one test.
-j, --jobs Run given number of tests in parallel
(default: 1).
Compiler flags
==============
Pass ``-no-pie -g -O0 -fsanitize=address`` to the compiler for better
error reporting.
Read more about sanitizers here: https://en.wikipedia.org/wiki/AddressSanitizer
Other unit test frameworks
==========================
Other C unit test frameworks with similar feature set as Nala.
- `CMock`_ + `Unity`_
- `cmocka`_
Ideas
=====
New set of generated parameter functions where ``_in()`` functions are
renamed to ``_in_buffer()``. New ``_in()`` functions are added,
without the size parameter. Also remove the size parameter from the
assert function, as it is seldom used.
.. code-block:: c
void FUNC_mock_set_PARAM_in(*); // check on input
void FUNC_mock_set_PARAM_in_buffer(*, size_t); // check on input
void FUNC_mock_set_PARAM_in_assert(*); // custom assert function on input
void FUNC_mock_set_PARAM_in_pointer(*); // check pointer (the address) on input
void FUNC_mock_set_PARAM_out(*); // value on return
void FUNC_mock_set_PARAM_out_buffer(*, size_t); // value on return
void FUNC_mock_set_PARAM_out_copy(*); // custom output copy function
An example:
.. code-block:: c
/* struct foo_t { char *string_p }; */
/* void fum(int *value_p, struct foo_t *foo_p); */
static void assert_foo_string(struct foo_t *actual_p, struct foo_t *expected_p)
{
/* Is size is needed (which is seldom is). */
ASSERT_EQ(nala_mock_get_param_in_size(), sizeof(*expected_p));
ASSERT_EQ(actual_p->string_p, expected_p->string_p);
}
TEST(fum_in_out)
{
int value;
struct foo_t foo;
fum_mock_once();
/* Expect *value_p to be 1 when fum() is called, and assign 2 to
it before returning. */
value = 1;
fum_mock_set_value_p_in(&value);
value = 2;
fum_mock_set_value_p_out(&value);
/* Use a custom parameter assert function to check that
foo_p->string_p is "Hello!" when fum() is called. */
foo.string_p = "Hello!";
fum_mock_set_foo_p_in(&foo);
fum_mock_set_foo_p_in_assert(assert_foo_string);
value = 1;
foo.string_p = "Hello!";
fum(&value, &foo);
ASSERT_EQ(value, 2);
}
.. |buildstatus| image:: https://travis-ci.org/eerimoq/nala.svg?branch=master
.. _buildstatus: https://travis-ci.org/eerimoq/nala
.. |coverage| image:: https://coveralls.io/repos/github/eerimoq/nala/badge.svg?branch=master
.. _coverage: https://coveralls.io/github/eerimoq/nala
.. |codecov| image:: https://codecov.io/gh/eerimoq/nala/branch/master/graph/badge.svg
.. _codecov: https://codecov.io/gh/eerimoq/nala
.. _Narwhal: https://github.com/vberlier/narwhal
.. _Narmock: https://github.com/vberlier/narmock
.. |tryit| image:: https://img.shields.io/badge/try-online-f34b7d.svg
.. _tryit: https://repl.it/@eerimoq/nala
.. _amalgamated: https://sqlite.org/amalgamation.html
.. _nala.h: https://raw.githubusercontent.com/eerimoq/nala/master/nala/dist/nala.h
.. _nala.c: https://raw.githubusercontent.com/eerimoq/nala/master/nala/dist/nala.c
.. _a few function parameters: https://github.com/eerimoq/nala/blob/master/nala/rename_parameters.txt
.. _a few variadic functions: https://github.com/eerimoq/nala/blob/master/nala/real_variadic_functions.c
.. _include/nala.h: https://github.com/eerimoq/nala/blob/master/include/nala.h
.. _GDB: https://www.gnu.org/software/gdb/
.. _CMock: https://github.com/ThrowTheSwitch/CMock
.. _Unity: https://github.com/ThrowTheSwitch/Unity
.. _cmocka: https://cmocka.org/
.. _examples folder: https://github.com/eerimoq/nala/tree/master/examples
.. _mock_api_examples: https://github.com/eerimoq/nala/tree/master/examples/mock_api_examples
Raw data
{
"_id": null,
"home_page": "https://github.com/eerimoq/nala",
"name": "nala",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "c,test,mock",
"author": "Erik Moqvist and Valentin Berlier",
"author_email": "erik.moqvist@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3a/18/fa5841c98d05c94a5e9c8ee394c7acb90bbf4276e24ec45e281eb5c9d335/nala-0.180.0.tar.gz",
"platform": null,
"description": "|buildstatus|_\n|coverage|_\n|codecov|_\n\n\ud83e\udd81 Nala\n=======\n\nA delightful test framework for `C` projects.\n\nBased on `Narwhal`_ and `Narmock`_.\n\nFeatures\n========\n\n- Automatic test discovery\n- Use the same generic assertions everywhere\n- Assertion failures reported as diffs\n- Powerful mocking\n- Easy-to-use output capturing utilities\n- Traceback(s) on failure\n- Works well with errors reported by sanitizers\n- Test isolation with ``fork()``\n- Only run tests matching given pattern\n- Automatic build and run on file change\n- Optional parallel test execution to save time\n- Amalgamated source and header files ready to drop in your project\n- JSON test report\n\nInstallation\n============\n\nIt's recommended to install `Nala` with ``pip``. Only Python 3 is\nsupported.\n\n.. code-block:: bash\n\n $ pip install nala\n\nAlternatively, if mocking is not needed, you can download the\n`amalgamated`_ header and source files:\n\n- `nala.h`_\n- `nala.c`_\n\nDrop the two files in your project, make sure ``nala.c`` is compiled\nand linked just like the other source files of your test program and\nyou should be good to go.\n\nGetting started\n===============\n\n|tryit|_\n\nUse ``nala init foo`` to create a folder ``foo`` with two test files,\n``test_assertions.c`` and ``test_time.c``. The first uses all\nassertions and captures output, and the second mocks the time\nfunction.\n\n.. code-block:: bash\n\n $ nala init foo\n Run 'make -C foo' to build and run all tests!\n\nThe assertions tests looks like this:\n\n.. code-block:: c\n\n #include \"nala.h\"\n\n TEST(assertions)\n {\n int i;\n int array[] = { 1, 5, 2 };\n\n ASSERT_EQ(NULL, NULL);\n ASSERT_NE(1, 2);\n ASSERT_LT(1.0, 2.0);\n ASSERT_LE(1, 1);\n ASSERT_GT(2L, 1L);\n ASSERT_GE(1, 1);\n ASSERT_TRUE(true);\n ASSERT_FALSE(false);\n ASSERT_SUBSTRING(\"12345\", \"34\");\n ASSERT_NOT_SUBSTRING(\"12345\", \"4567\");\n ASSERT_MEMORY_EQ(\"abcd\", \"abcd\", 5);\n ASSERT_FILE_EQ(\"test_assertions.c\", \"test_assertions.c\");\n ASSERT_ARRAY_EQ(array, array, sizeof(array));\n ASSERT_FUNCTION_POINTER_EQ(assertions, assertions);\n ASSERT_FUNCTION_POINTER_NE(assertions, NULL);\n ASSERT(1 == 1);\n\n CAPTURE_OUTPUT(output, errput) {\n printf(\"output!\\n\");\n fprintf(stderr, \"errput!\\n\");\n }\n\n ASSERT_EQ(output, \"output!\\n\");\n ASSERT_EQ(errput, \"errput!\\n\");\n\n for (i = 0; i < 3; i++) {\n WITH_MESSAGE(\"i: %d\", i) {\n ASSERT_EQ(array[i], array[i]);\n }\n }\n }\n\nAnd the time tests:\n\n.. code-block:: c\n\n #include <time.h>\n #include \"nala.h\"\n\n TEST(mock_time)\n {\n time_mock_once(42);\n\n ASSERT_EQ(time(NULL), 42);\n }\n\nBuild and run all tests with ``make -s -C foo``.\n\n.. image:: https://github.com/eerimoq/nala/raw/master/docs/build-and-run.png\n\nBuild all tests but only run those whose name contains ``time``. This\nis done by giving ``ARGS=time``.\n\n.. image:: https://github.com/eerimoq/nala/raw/master/docs/build-and-run-one-test.png\n\nRun ``make -s -C foo auto`` to build and run all tests automatically\nwhen any source file in your project is modified. With the command\nrunning, make the time test fail by returning ``41`` instead of ``42``\nfrom the time mock.\n\n.. code-block:: c\n\n #include <time.h>\n #include \"nala.h\"\n\n TEST(mock_time)\n {\n time_mock_once(41);\n\n ASSERT_EQ(time(NULL), 42);\n }\n\nNotice how the test is built and run automatically.\n\n.. image:: https://github.com/eerimoq/nala/raw/master/docs/build-and-run-assert-eq-fail.png\n\nCreate a code coverage report and open it with Firefox.\n\n.. code-block::\n\n $ make -s -C foo coverage\n Code coverage report: /home/erik/workspace/nala/foo/build/coverage/index.html\n $ firefox /home/erik/workspace/nala/foo/build/coverage/index.html\n\nAPI\n===\n\nBelow is a list of all macros and functions in the API. They are all\ndefined/declared in `include/nala.h`_.\n\nAssertions\n----------\n\n.. code-block:: c\n\n ASSERT_EQ(actual, expected); // Assert that given characters, numbers, pointers or\n // strings are equal.\n ASSERT_NE(actual, expected); // Assert that given characters, numbers, pointers or\n // strings are not equal.\n ASSERT_LT(actual, expected); // Assert that actual is less than expected.\n ASSERT_LE(actual, expected); // Assert that actual is less than or equal to expected.\n ASSERT_GT(actual, expected); // Assert that actual is greater than expected.\n ASSERT_GE(actual, expected); // Assert that actual is greater than or equal to\n // expected.\n ASSERT_TRUE(actual); // Assert that given value is true.\n ASSERT_FALSE(actual); // Assert that given value is false.\n ASSERT_SUBSTRING(haystack, needle); // Assert that given haystack string contains given\n // needle string.\n ASSERT_NOT_SUBSTRING(haystack, needle); // Assert that given haystack string does not contain\n // given needle string.\n ASSERT_MEMORY_EQ(actual, expected, size); // Assert that given memory regions are equal.\n ASSERT_FILE_EQ(actual, expected); // Assert that given files are equal.\n ASSERT_ARRAY_EQ(actual, expected, size); // Assert that given arrays are equal.\n ASSERT_FUNCTION_POINTER_EQ(actual, expected); // Assert that given function pointers are equal.\n ASSERT_FUNCTION_POINTER_NE(actual, expected); // Assert that given function pointers are not equal.\n ASSERT(cond); // Assert that given condition is true.\n\nOther macros\n------------\n\n.. code-block:: c\n\n FAIL(message); // Fail current test with given message.\n CAPTURE_OUTPUT(stdout_name, stderr_name); // A capture output block.\n WITH_MESSAGE(format, ...); // Additional message on error block. May be nested.\n\nFunctions\n---------\n\n.. code-block:: c\n\n void *nala_alloc(size_t size); // Allocate a memory buffer of given size that is\n // automatically freed after the test. Always returns\n // a valid pointer.\n void nala_auto_free(void *buf_p); // Automatically free given buffer after the test.\n // free() is called to free the buffer.\n void nala_exit(int status); // Performs post-test checks and cleanup, and then\n // exits with status 0. The status parameter is\n // ignored.\n\nMocking\n=======\n\nGenerating mocks\n----------------\n\nThe ``nala generate_mocks`` command finds mocked functions in your\ntest code and generates ``nala_mocks.h``, ``nala_mocks.c`` and\n``nala_mocks.ldflags``. The first two files declare and define mocks,\nwhile the last file contains linker flags.\n\nUse ``--rename-parameters-file`` to rename function parameters, often\nuseful when mocking standard library functions. If not given, Nala\nrenames `a few function parameters`_ by default. Also, any\n``__``-prefix is removed from all parameters.\n\nUse ``--no-rename-parameters`` not to rename any function\nparameters. Overrides ``--rename-parameters-file``.\n\nUse ``--no-implementation`` when the implementation of functions\nmatching given Unix shell-style wildcards pattern are not available in\nthe binary (and therefore should not be called by the generated code,\nas the linker would give a relocation error). This option may be given\nmultipe times. An alternative to using this option is to manually\nimplement the missing functions. Here is an example implementation of\n``foo()`` that makes the test fail if called.\n\n.. code-block:: c\n\n int foo()\n {\n FAIL(\"No real implementation available!\\n\");\n\n return (0);\n }\n\nUse ``--no-real-variadic-functions`` not to add any real variadic\nfunctions. Nala adds `a few variadic functions`_ by default, given\nthat they are mocked.\n\nHere is an example of how to generate mocks:\n\n.. code-block:: bash\n\n $ nala cat *.c | gcc -DNALA_GENERATE_MOCKS -x c -E - | nala generate_mocks\n\n``nala cat *.c`` should only concatenate test source files, not any\nother source files in your project.\n\nNala requires test source code to be expanded by the preprocessor. You\ncan directly pipe the output of ``gcc -DNALA_GENERATE_MOCKS -x c -E\n-`` to the command-line utility.\n\nMocking object-internal function calls\n--------------------------------------\n\nThe GNU linker ``ld`` wrap feature (``--wrap=<symbol>``) does not wrap\nobject-internal function calls. As Nala implements mocking by wrapping\nfunctions, object-internal function calls can't be mocked just using\nthe linker. To mock these, after compilation, run ``nala\nwrap_internal_symbols ...`` for each object file, and then pass them\nto the linker.\n\nAlso, local (``static``) functions can't be mocked, only global\nfunctions can!\n\n.. code-block:: Makefile\n\n %.o: %.c\n $(CC) -o $@ $<\n nala wrap_internal_symbols nala_mocks.ldflags $@\n\nMock API\n--------\n\nA function mock will call the real implementation by default. Use the\nfunctions below to control mock object behaviour.\n\nVariadic functions will *not* call the real implementation by\ndefault. Give ``--implementation`` to ``nala generate_mocks`` to\ngenerate calls to the real function (taking a ``va_list`` instead of\n``...``).\n\nThere are plenty of mock-examples in the `examples folder`_. All\ninline examples below can also be found in the `mock_api_examples`_\nexample.\n\nFor all functions\n^^^^^^^^^^^^^^^^^\n\n``<params>`` is all char-pointer (string) and primitive type\nparameters of the mocked function.\n\nSame behaviour for every call.\n\n.. code-block:: c\n\n void FUNC_mock(<params>, <res>); // check parameters and return\n void FUNC_mock_ignore_in(<res>); // ignore parameters and return\n void FUNC_mock_none(); // no calls allowed\n void FUNC_mock_implementation(*); // replace implementation\n void FUNC_mock_real(); // real implementation\n\nAn example:\n\n.. code-block:: c\n\n /* int foo(int value); */\n\n TEST(foo_every_call)\n {\n foo_mock(1, 2);\n\n /* All calls to foo() expects its parameter to be 1 and returns 2. */\n ASSERT_EQ(foo(1), 2);\n ASSERT_EQ(foo(1), 2);\n }\n\nPer call control.\n\n.. code-block:: c\n\n int FUNC_mock_once(<params>, <res>); // check parameters and return once (per call)\n // returns a mock instance handle\n int FUNC_mock_ignore_in_once(<res>); // ignore parameters and return once (per call)\n // returns a mock instance handle\n void FUNC_mock_real_once(); // real implementation once (per call)\n\nAn example:\n\n.. code-block:: c\n\n /* int foo(int value); */\n\n TEST(foo_per_call)\n {\n foo_mock_once(1, 2);\n foo_mock_once(4, 5);\n\n /* First call to foo() expects its parameter to be 1 and returns 2. */\n ASSERT_EQ(foo(1), 2);\n\n /* Second call to foo() expects its parameter to be 4 and returns 5. */\n ASSERT_EQ(foo(4), 5);\n\n /* Third call will fail and the test will end. */\n foo(10);\n }\n\nChanges the behaviour of currect mock object (most recent ``*_mock()``\nor ``*_mock_once()`` call). Works for both per call and every call\nfunctions above.\n\n.. code-block:: c\n\n void FUNC_mock_set_errno(int); // errno on return, 0 by default\n void FUNC_mock_set_callback(*); // additional checks and/or actions\n // called just before returning from the mock\n\nAn example:\n\n.. code-block:: c\n\n /* int foo(int value); */\n\n TEST(foo_set_errno)\n {\n foo_mock_once(1, 2);\n foo_mock_set_errno(EINVAL);\n\n ASSERT_EQ(foo(1), 2);\n ASSERT_EQ(errno, EINVAL);\n }\n\nGet per call input parameters.\n\n.. code-block:: c\n\n *FUNC_mock_get_params_in(int); // get input parameters for given mock instance\n // handle\n\nAn example:\n\n.. code-block:: c\n\n /* typedef void (*callback_t)(void); */\n /* void bar(callback_t callback); */\n\n static void fie(void)\n {\n printf(\"fie() called!\\n\");\n }\n\n TEST(bar_get_params_call_callback)\n {\n int handle;\n\n handle = bar_mock_once();\n\n bar(fie);\n\n /* Call the callback (calls fie()). */\n bar_mock_get_params_in(handle)->callback();\n }\n\nFor pointer and array function parameters\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nChanges the behaviour of currect mock (most recent ``*_mock()`` or\n``*_mock_once()`` call). Works for both per call and every call\nfunctions above.\n\n.. code-block:: c\n\n void FUNC_mock_set_PARAM_in(*, size_t); // check on input\n void FUNC_mock_set_PARAM_in_assert(*); // custom assert function on input\n void FUNC_mock_set_PARAM_in_pointer(*); // check pointer (the address) on input\n void FUNC_mock_set_PARAM_out(*, size_t); // value on return\n void FUNC_mock_set_PARAM_out_copy(*); // custom output copy function\n\nAn example:\n\n.. code-block:: c\n\n /* struct foo_t { char *string_p }; */\n\n /* void fum(int *value_p, struct foo_t *foo_p); */\n\n static void assert_foo_string(struct foo_t *actual_p,\n struct foo_t *expected_p,\n size_t size)\n {\n ASSERT_EQ(size, sizeof(*expected_p));\n ASSERT_EQ(actual_p->string_p, expected_p->string_p);\n }\n\n TEST(fum_in_out)\n {\n int value;\n struct foo_t foo;\n\n fum_mock_once();\n\n /* Expect *value_p to be 1 when fum() is called, and assign 2 to\n it before returning. */\n value = 1;\n fum_mock_set_value_p_in(&value, sizeof(value));\n value = 2;\n fum_mock_set_value_p_out(&value, sizeof(value));\n\n /* Use a custom parameter assert function to check that\n foo_p->string_p is \"Hello!\" when fum() is called. */\n foo.string_p = \"Hello!\";\n fum_mock_set_foo_p_in(&foo, sizeof(foo));\n fum_mock_set_foo_p_in_assert(assert_foo_string);\n\n value = 1;\n foo.string_p = \"Hello!\";\n fum(&value, &foo);\n ASSERT_EQ(value, 2);\n }\n\nFor function parameters part of <params>\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nChanges the behaviour of currect mock object (most recent ``*_mock()``\nor ``*_mock_once()`` call). Works for both per call and every call\nfunctions above.\n\n.. code-block:: c\n\n void FUNC_mock_ignore_PARAM_in(); // ignore on input\n\nAn example:\n\n.. code-block:: c\n\n /* void foo(int value); */\n\n TEST(foo_ignore_value)\n {\n foo_mock_once(1, 2);\n foo_mock_ignore_value_in();\n\n ASSERT_EQ(foo(9), 2);\n }\n\nFor variadic functions\n^^^^^^^^^^^^^^^^^^^^^^\n\nVariadic function mocks are slightly different from the above. Their\nparameter list is extended with a format string (``format``) and an\nellipsis (``...``), as shown below.\n\n.. code-block:: c\n\n void FUNC_mock(<params>, <res>, format, ...);\n void FUNC_mock_once(<params>, <res>, format, ...);\n void FUNC_mock_ignore_in(<res>, format);\n void FUNC_mock_ignore_in_once(<res>, format);\n\nThe format string supports the following specifiers.\n\n.. code-block::\n\n %d - signed integer\n %u - unsigned integer\n %ld - signed long integer\n %lu - unsigned long integer\n %p - pointer address\n %s - string\n\nThe ``%p`` specifier takes no value when calling the mock function,\njust like pointers are not part of the mock function parameters\nlist. Instead, set pointers after the mock call.\n\n.. code-block:: c\n\n foo_mock(3, \"%d%p%s\", 5, \"the-string\");\n foo_mock_set_va_arg_in_pointer_at(1, NULL);\n\nThe variadic parameters are controlled by index instead of name.\n\n.. code-block:: c\n\n void FUNC_mock_ignore_va_arg_in_at(uint); // ignore on input\n void FUNC_mock_set_va_arg_in_at(uint, *, size_t); // check on input\n void FUNC_mock_set_va_arg_in_assert_at(uint, *); // custom assert function on input\n void FUNC_mock_set_va_arg_in_pointer_at(uint, *); // check pointer (the address) on input\n void FUNC_mock_set_va_arg_out_at(uint, *, size_t); // value on return\n void FUNC_mock_set_va_arg_out_copy_at(uint, *); // custom output copy function\n\nLimitations\n-----------\n\n- Structs and unions passed by value are ignored.\n\n- ``va_list`` parameters are ignored.\n\n- ``malloc()`` and ``free()`` can't be mocked if forking and using\n gcov. They probably can if wrapping ``__gcov_fork()`` in an\n suspend/resume-block.\n\n- ``static`` functions can't be mocked.\n\n- Only primitive data type members are asserted when comparing\n structs. Pointer and union members are not asserted, and probably\n never will be.\n\nDebugging tips\n==============\n\nNala executes each test in its own process. This means that following\nthe execution of a test with a debugger can be a bit tricky because\ndebuggers like `GDB`_ can only follow a single process at a time.\n\nIf you're using `GDB`, set a breakpoint at ``<test>_before_fork`` and\nthen run the program until it stops at the breakpoint. Before\ncontinuing the program execution, tell `GDB` to follow the forked test\nprocess by setting ``follow-fork-mode`` to ``child``.\n\nBelow are all commands to debug the ``assertions`` test in the example\nabove.\n\n.. code-block::\n\n $ gdb foo/build/app\n (gdb) b assertions_before_fork\n (gdb) r\n (gdb) set follow-fork-mode child\n (gdb) c\n\nThe ``gdb`` make target starts `GDB` and runs all commmands listed\nabove. Set the ``TEST`` make variable to the test to debug. Both\n``TEST=test_assertions::assertions`` and ``TEST=assertions`` are\naccepted. The test name may be partialy given, as long as it only\nmatches one test.\n\n.. code-block::\n\n $ make -s -C foo gdb TEST=assertions\n\nThe test program takes optional arguments as below, which also can be\nhelpful when debugging, especially ``--print-all-calls``.\n\n.. code-block::\n\n $ foo/build/app --help\n usage: foo/build/app [-h] [-v] [-c] [-a] [-r] [-f] [-j] [<test-pattern>]\n\n Run tests.\n\n positional arguments:\n test-pattern Only run tests matching given pattern. '^' matches\n the beginning and '$' matches the end of the test\n name.\n\n optional arguments:\n -h, --help Show this help message and exit.\n -v, --version Print version information.\n -c, --continue-on-failure Continue on test failure.\n -a, --print-all-calls Print all calls to ease debugging.\n -r, --report-json-file JSON test report file (default: report.json).\n -f, --print-test-file-func Print file:function for exactly one test.\n -j, --jobs Run given number of tests in parallel\n (default: 1).\n\nCompiler flags\n==============\n\nPass ``-no-pie -g -O0 -fsanitize=address`` to the compiler for better\nerror reporting.\n\nRead more about sanitizers here: https://en.wikipedia.org/wiki/AddressSanitizer\n\nOther unit test frameworks\n==========================\n\nOther C unit test frameworks with similar feature set as Nala.\n\n- `CMock`_ + `Unity`_\n\n- `cmocka`_\n\nIdeas\n=====\n\nNew set of generated parameter functions where ``_in()`` functions are\nrenamed to ``_in_buffer()``. New ``_in()`` functions are added,\nwithout the size parameter. Also remove the size parameter from the\nassert function, as it is seldom used.\n\n.. code-block:: c\n\n void FUNC_mock_set_PARAM_in(*); // check on input\n void FUNC_mock_set_PARAM_in_buffer(*, size_t); // check on input\n void FUNC_mock_set_PARAM_in_assert(*); // custom assert function on input\n void FUNC_mock_set_PARAM_in_pointer(*); // check pointer (the address) on input\n void FUNC_mock_set_PARAM_out(*); // value on return\n void FUNC_mock_set_PARAM_out_buffer(*, size_t); // value on return\n void FUNC_mock_set_PARAM_out_copy(*); // custom output copy function\n\nAn example:\n\n.. code-block:: c\n\n /* struct foo_t { char *string_p }; */\n\n /* void fum(int *value_p, struct foo_t *foo_p); */\n\n static void assert_foo_string(struct foo_t *actual_p, struct foo_t *expected_p)\n {\n /* Is size is needed (which is seldom is). */\n ASSERT_EQ(nala_mock_get_param_in_size(), sizeof(*expected_p));\n ASSERT_EQ(actual_p->string_p, expected_p->string_p);\n }\n\n TEST(fum_in_out)\n {\n int value;\n struct foo_t foo;\n\n fum_mock_once();\n\n /* Expect *value_p to be 1 when fum() is called, and assign 2 to\n it before returning. */\n value = 1;\n fum_mock_set_value_p_in(&value);\n value = 2;\n fum_mock_set_value_p_out(&value);\n\n /* Use a custom parameter assert function to check that\n foo_p->string_p is \"Hello!\" when fum() is called. */\n foo.string_p = \"Hello!\";\n fum_mock_set_foo_p_in(&foo);\n fum_mock_set_foo_p_in_assert(assert_foo_string);\n\n value = 1;\n foo.string_p = \"Hello!\";\n fum(&value, &foo);\n ASSERT_EQ(value, 2);\n }\n\n.. |buildstatus| image:: https://travis-ci.org/eerimoq/nala.svg?branch=master\n.. _buildstatus: https://travis-ci.org/eerimoq/nala\n\n.. |coverage| image:: https://coveralls.io/repos/github/eerimoq/nala/badge.svg?branch=master\n.. _coverage: https://coveralls.io/github/eerimoq/nala\n\n.. |codecov| image:: https://codecov.io/gh/eerimoq/nala/branch/master/graph/badge.svg\n.. _codecov: https://codecov.io/gh/eerimoq/nala\n\n.. _Narwhal: https://github.com/vberlier/narwhal\n.. _Narmock: https://github.com/vberlier/narmock\n\n.. |tryit| image:: https://img.shields.io/badge/try-online-f34b7d.svg\n.. _tryit: https://repl.it/@eerimoq/nala\n\n.. _amalgamated: https://sqlite.org/amalgamation.html\n.. _nala.h: https://raw.githubusercontent.com/eerimoq/nala/master/nala/dist/nala.h\n.. _nala.c: https://raw.githubusercontent.com/eerimoq/nala/master/nala/dist/nala.c\n\n.. _a few function parameters: https://github.com/eerimoq/nala/blob/master/nala/rename_parameters.txt\n\n.. _a few variadic functions: https://github.com/eerimoq/nala/blob/master/nala/real_variadic_functions.c\n\n.. _include/nala.h: https://github.com/eerimoq/nala/blob/master/include/nala.h\n\n.. _GDB: https://www.gnu.org/software/gdb/\n\n.. _CMock: https://github.com/ThrowTheSwitch/CMock\n\n.. _Unity: https://github.com/ThrowTheSwitch/Unity\n\n.. _cmocka: https://cmocka.org/\n\n.. _examples folder: https://github.com/eerimoq/nala/tree/master/examples\n\n.. _mock_api_examples: https://github.com/eerimoq/nala/tree/master/examples/mock_api_examples\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A test framework for C projects.",
"version": "0.180.0",
"project_urls": {
"Homepage": "https://github.com/eerimoq/nala"
},
"split_keywords": [
"c",
"test",
"mock"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3a18fa5841c98d05c94a5e9c8ee394c7acb90bbf4276e24ec45e281eb5c9d335",
"md5": "938bd8fbe0c6c47c4f9ad10805893f8d",
"sha256": "eb1becd018659d6df2e209b61b91a631f0a5ac8580467193ba8deb0953fc1140"
},
"downloads": -1,
"filename": "nala-0.180.0.tar.gz",
"has_sig": false,
"md5_digest": "938bd8fbe0c6c47c4f9ad10805893f8d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 63974,
"upload_time": "2022-07-15T04:15:35",
"upload_time_iso_8601": "2022-07-15T04:15:35.752613Z",
"url": "https://files.pythonhosted.org/packages/3a/18/fa5841c98d05c94a5e9c8ee394c7acb90bbf4276e24ec45e281eb5c9d335/nala-0.180.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-07-15 04:15:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eerimoq",
"github_project": "nala",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pycparser",
"specs": [
[
">=",
"2.21"
]
]
},
{
"name": "jinja2",
"specs": []
}
],
"lcname": "nala"
}
JSON
