Checkmk (1) Linux Manual Page

NAME

checkmk – Awk script for generating C unit tests for use with the Check unit testing framework.

SYNOPSIS

checkmk [ clean_mode=1 ] [ input-file ]

DESCRIPTION

Generate C-language source files containing unit tests for use with the Check unit testing framework. The aim of this script is to automate away some of the typical boilerplate one must write when writing a test suite using Check: specifically, the instantiation of an SRunner, Suite(s), and TCase(s), and the building of relationships between these objects and the test functions.

This tool is intended to be used by those who are familiar with the Check unit testing framework. Familiarity with the framework will be assumed throughout this manual.

The Check framework, along with information regarding it, is available at http://check.sourceforge.net/ <URL:http://check.sourceforge.net/>.

The input-file argument to checkmk uses a simple, C-preprocessor-like syntax to declare test functions, and to describe their relationships to Suites and TCases in Check. checkmk then uses this information to automatically write a main() function containing all of the necessary declarations, and whatever code is needed to run the test suites. The final C-language output is printed to checkmk‘s standard output.

Facilities are provided for the insertion of user code into the generated main() function, to provide for the use of logging, test fixtures or specialized exit values.

While it is possible to omit the input-file argument to checkmk and provide the input file on checkmk‘s standard input instead, it is generally recommended to provide it as an argument. Doing this allows checkmk to be aware of the file’s name, to place references to it in the initial comments of the C-language output, and to intersperse C #line directives throughout, to facilitate in debugging problems by directing the user to the original input file.

OPTIONS

The only officially supported option is specifying a true value (using Awk’s definition for "true") for the variable clean_mode. This causes checkmk not to place appropriate #line directives in the source code, which some might find to be unnecessary clutter.

The author recommends against the use of this option, as it will cause C compilers and debugging tools to refer to lines in the automatically generated output, rather than the original input files to checkmk. This would encourage users to edit the output files instead of the original input files, would make it difficult for intelligent editors or IDEs to pull up the right file to edit, and could result in the fixes being overwritten when the output files are regenerated.

#line directives are automatically supressed when the input file is provided on standard input instead of as a command-line argument.

BASIC EXAMPLE

In its most basic form, an input file can be simply a prologue and a test function. Anything that appears before the first test function is in the prologue, and will be copied into the output verbatim. The test function is begun by a line in the form:

#test test_name

Where test_name is the name of your test function. This will be used to name a C function, so it must be a valid C identifier.

Here is a small, complete example:


-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
/* A complete test example */
#include <stdio.h>
#test the_test
                                                                        int nc;
const char msg[] = "

    Hello, world!
";
nc = printf("%s", msg);
fail_unless(nc == (sizeof msg - 1) /* for terminating NUL. */
);
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

If you place the above into a file named basic_complete.ts and process it using the following command:

$ checkmk basic_complete.ts > basic_complete.c

basic_complete.c will contain output similar to:

— — — — — — — — — — — — — — — — — — — — — — — — —
/*
* DO NOT EDIT THIS FILE. Generated by checkmk.
* Edit the original source file “in” instead.
*/
#include <check.h>
/* A complete test example */
#include <stdio.h>
START_TEST(the_test)
{
int nc;
const char msg[] = “

Hello, world!
”;
nc = printf(“%s”, msg);
fail_unless(nc == (sizeof msg – 1) /* for terminating NUL. */
);
}
END_TEST
int main(void)
{
Suite *s1 = suite_create(“Core”);
TCase *tc1_1 = tcase_create(“Core”);
SRunner *sr = srunner_create(s1);
int nf;
suite_add_tcase(s1, tc1_1);
tcase_add_test(tc1_1, the_test);
srunner_run_all(sr, CK_ENV);
nf = srunner_ntests_failed(sr);
srunner_free(sr);
return nf == 0 ? 0 : 1;
}
— — — — — — — — — — — — — — — — — — — — — — — — —

In real usage, basic_complete.c would also contain #line directives.

DIRECTIVE SUMMARY

Here is a complete summary of all the C-preprocessor-style directives that are understood by checkmk. See below for more details.

# test test_name
# suite TestSuiteName
# tcase TestCaseName
# main-pre
# main-post

All directives are case-insensitive. Whitespace may appear at the beginning of the line before the #, between the # and the directive, between the directive and any argument, and at the end of the line.

TEST-DEFINING DIRECTIVES

Here is a more detailed explanation of the directives that may be used to define test functions and their containers.

TEST FUNCTIONS

# test test_name

This is the most basic directive for creating a template for input to checkmk. It is the only directive that is required: there must be at least one #test directive appearing in the template, or checkmk will fail with an error message. The #test directive may be specified several times, each one beginning the definition of a new test function.

The test_name argument will be used as the name of a test function in the C-language output, so it must be a valid C identifier. That is, it must begin with an alphabetic character or the underscore (_), followed by optional alpha-numeric characters and/or underscores.

Universal Character Names (introduced in C99) are also allowed, of the form

checkmk (1) Linux Manual Page