GitHub - vomlehn/limpet: C/C++ definitions that allow tests to be easily embedded within source files. (Rust-like)

vomlehn / limpet Public

Notifications You must be signed in to change notification settings
Fork 0
Star 0

C/C++ definitions that allow tests to be easily embedded within source files. (Rust-like)

Notifications

Name		Name	Last commit message	Last commit date
Latest commit History 91 Commits
include		include
test		test
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README		README
runtests		runtests

Repository files navigation

Limpet is a set of header files that make it easy to embed tests
in C and C++ code and control their execution. The flag LIMPET is
defined on the compiler command line to enable the tests. When it is
not defined, no tests will be defined or run.

A Complete Example
==================
The following code #includes the beader file limpet.h, which can be used
with C and C++. Actual test cases are in the section demarcated by 
#ifdef LIMPET...#endif:

    /*
     * Example use of Limpet included in README file
     *
     * To compile, use:
     *
     *      cc  -Iinclude -DLIMPET=LIMPET_LINUX -o simple test/simple.cc
     */

    #include <stdio.h>
    #include <stdlib.h>
    #include <unistd.h>

    #include <limpet.h>

    int main(int argc, char *argv[]) {
        fprintf(stderr, "Should never get to main()");
        exit(EXIT_FAILURE);
    }

    #ifdef LIMPET
    LIMPET_TEST(simple_good) {
        printf("doc-example: This is printed by test simple_good\n");
        limpet_assert_eq(0, 0);
    }

    LIMPET_TEST(simple_bad) {
        printf("doc-example: This is printed by test simple_bad\n");
        limpet_assert_ne(0, 0);
    }

    #endif /* LIMPET */

where the include in the compile command should be replaced by the
relative or absolute path of the the limpet/include directory. This
directory has limpet.h and a subdirectory, limpet.d, containing other
header files used by limpet.

To run, use:

    ./simple

As implied in the example above, when built for LIMPET, the tests will
halt before main is called. This avoids the possibility of overlooking
that test code is being included when not configured for testing.

Platform Support
================
The symbol defined on the compilation command line, LIMPET, is set
to a value to indicate which version of Limpet is to be build. There
are presently two possibilities:

    LIMPET_LINUX                    Use this for Linux testing when running
                                    multiple tests in parallel. Configuration
                                    variables are supplied on the command
                                    line when running the test.

    LIMPET_SINGLE_THREADED_LINUX    This is also works on Linux, but runs
                                    the tests in a single threaded fashion.
                                    It's not really intend for production use
                                    but rather as an example of how Limpet can
                                    be used on single thread systems, such as
                                    simple embedded systems. Configuration
                                    variables are supplied to the compiler
                                    via the -D option.

Configuration Variables
=======================
Configuration variables are available to control execution:

LIMPET_MAX_JOBS When parallel execution is supported, this limits the
                number of tests run in parallel.

LIMPET_RUNLIST  A space-separated list of tests to run.

LIMPET_VERBOSE  If "true", prints the test log, if "false" it doesn't. The
                default is "false".

LIMPET_TIMEOUT  A floating point value specifying the amount of time
                a test can be run before being killed. The default is
                30 seconds. A value of zero means tests will not be
                halted.

Values for configuration variables may be set in two ways:

1.  If the platform used supports envirnment variables, variables with
    the above names can be set

2.  If the platform doesn't support environment variables, the values can
    be specified on the compiler command line, e.g. -DLIMPET_TIMEOUT=2.5
    The single-threaded platform noted above uses this method.

Supporting Limpet On Other Systems
==================================
Limpet is comprised of code that uses various interfaces to abstract the
underlying kernel or real time system. The limpet.d/limpet-sysdep.h file
lists interfaces that must be implemented, with some additional interfaces
in limpet.d/limpet-single-threaded.h. Following the system-dependent
examples in limpet-linux.h and limpet-single-threaded-linux.h n the
limpet.d directory should be straight forward, but the author will be
happy to incorporate useful suggestions and, especially, proposed written
documentation, in this package for the future.

Possible Future Enhancements
============================
o   Add a flag or flags that select modes of execution: 

    1.  All tests are run and main() is not called. This is the default.
    2.  Each test exits immediately without doing anything and main()
        is called normally. The tests can be run manually by calling
        limpet_runtests(), if desired.

        In this way, the same executable can be used in in testing mode
        and in production mode. This supports the "test as you fky, fly
        as you test" philosophy.
--
David VomLehn
dvomlehn@gmail.com