Skip to main content

.

Project description

buildstatus codecov

🦁 Nala

A 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

  • Easy-to-use output capturing utilities

  • Amalgamated source file and header ready to drop in your project

  • Mocking support

  • Works well with errors reported by sanitizers

  • Test isolation with fork()

Installation

It’s recommended to install Nala with pip.

$ pip install nala

Alternatively, if mocking is not needed, you can download the amalgamated header and source files:

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.

Example

Use nala init to create a test suite in the current directory.

$ mkdir test
$ cd test
$ nala init
Run 'make' to build and run the test suite!

The test suite is found in main.c and contains two tests; the first uses all assertions and captures output, and second mocks the time function.

#include <time.h>
#include "nala.h"
#include "__mocks__.h"

TEST(assertions)
{
    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_SUBSTRING("12345", "34");
    ASSERT_NOT_SUBSTRING("12345", "4567");
    ASSERT_MEMORY("abcd", "abcd", 5);
    ASSERT(1 == 1);

    CAPTURE_OUTPUT(stdoutput, stderrput) {
        printf("std!\n");
        fprintf(stderr, "err!\n");
    }

    ASSERT_EQ(stdoutput, "std!\n");
    ASSERT_EQ(stderrput, "err!\n");
}

TEST(mock_time)
{
    time_mock_once(42);

    ASSERT_EQ(time(NULL), 42);
}

Build and run the tests.

$ make
std!
err!

Test results:

  PASSED assertions (0.38 ms)
  PASSED mock_time (0.28 ms)

Tests: 2 passed, 2 total
Time: 0.65 ms

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.

All commands are shown below for the test called foo.

$ gdb ./a.out
(gdb) b foo_before_fork
(gdb) r
(gdb) set follow-fork-mode child
(gdb) c

Mocking

Generating mocks

The nala generate_mocks command finds the functions mocked in your code and generates __mocks__.h, __mocks__.c and __mocks__.ld. The first two files declare and define mocks, while the last file contains linker flags.

$ gcc -E *.c | nala generate_mocks

Nala requires source code to be expanded by the preprocessor. You can directly pipe the output of gcc -E to the command-line utility.

Mock API

The created mocks provides the following functions.

For all functions

<func>_mock(<params>, <res>)      - check parameters and return
<func>_mock_once(<params>, <res>) - check parameters and return once (per call)
<func>_mock_ignore_in(<res>)      - ignore parameters and return
<func>_mock_ignore_in_once(<res>) - ignore parameters and return once (per call)
<func>_mock_none()                - no calls allowed
<func>_mock_set_errno(int)        - errno on return
<func>_mock_implementation(*)     - replace implementation
<func>_mock_disable()             - call real implementation
<func>_mock_reset()               - mock reset
<func>_mock_assert_completed()    - completion checks

For selected function parameters

<func>_mock_ignore_<param>_in()               - ignore on input
<func>_mock_set_<param>_in(*, size_t)         - check on input
<func>_mock_set_<param>_in_pointer(*, size_t) - check pointer (the address) on input
<func>_mock_set_<param>_out(*, size_t)        - value on return

For variadic functions

<func>_mock_ignore_va_arg_in_at(uint)          - ignore on input
<func>_mock_set_va_arg_in_at(uint, *, size_t)  - check on input
<func>_mock_set_va_arg_in_pointer_at(uint, *)  - check pointer on input
<func>_mock_set_va_arg_out_at(uint, *, size_t) - value on return

Module functions

nala_reset_all_mocks()            - reset everything
nala_assert_all_mocks_completed() - completion checks

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nala-0.6.0.tar.gz (26.0 kB view details)

Uploaded Source

Built Distribution

nala-0.6.0-py2.py3-none-any.whl (30.9 kB view details)

Uploaded Python 2Python 3

File details

Details for the file nala-0.6.0.tar.gz.

File metadata

  • Download URL: nala-0.6.0.tar.gz
  • Upload date:
  • Size: 26.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.9.1 pkginfo/1.4.1 requests/2.18.1 setuptools/38.5.0 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/2.7.12

File hashes

Hashes for nala-0.6.0.tar.gz
Algorithm Hash digest
SHA256 6c5e2a35ae62f89de71d6fffc6179a9bafc412e3621a8ae0e90458f4cce9a29d
MD5 9dc171f006557169f04b9880dfb785bb
BLAKE2b-256 227b6b5b9a557d1047e0d405cc924edd5688b9f4fdea5aaa7e7be01a282fb0a3

See more details on using hashes here.

File details

Details for the file nala-0.6.0-py2.py3-none-any.whl.

File metadata

  • Download URL: nala-0.6.0-py2.py3-none-any.whl
  • Upload date:
  • Size: 30.9 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.9.1 pkginfo/1.4.1 requests/2.18.1 setuptools/38.5.0 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/2.7.12

File hashes

Hashes for nala-0.6.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 d1f28e541b9b6e9606bfc2aa44d3f5fa9742ac75ce4691d10ffe52d882828696
MD5 f5bf4321a72edd0bebcf40887bd3ed34
BLAKE2b-256 cdfd4af2b3f80962db8fe5e624661c989f4c6b8f2e7141a08efbea2c193b0ac2

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page