Minitester aims to be a simple framework for writing automated tests, and more
specifically unit tests, for programs written in C.

== Test suites ==

A test suite is a regular C file, which contains 0 or more test cases (defined
below). In addition to the test cases, they may contain any amount of arbitrary
C code, used (or not) as helper to the test cases. The only restriction is that
test suites should not contain a main function, as it would conflict with the
one minitester uses to drive the tests.

A test suite that does not contain test cases is valid, even though it might
not be useful.


== Test cases ==

A test case is a regular C function whose name begins with "test_", written in
test suite. It should take no argument, and return void.

To be able to report success and failures, test cases rely on minitester's
macros, defined below.


== Macros ==

A test suite may include mt.h to get access to 2 macros:

- MT_ASSERT( expr )
if expr evaluates to false, minitester will record the failure and generate a
message indicating it. Not that failing an assertion does not interrupt the
test case, which will keep running until it explicitly returns. MT_ASSERT may
be used directly in test cases, or in any function called by them.

- MT_ABORT()
This macro will record the failure to complete the test case, generate a
message about it, and immediately exit. This may only be called directly from a
test case, not from a function called by one.

Note that is is not required for a test suite to include mt.h and to use these
two macros, but that since these are the only way to report failure of test
cases, test suites that don't use them are usually of limited interest.


== Building the test application ==

Once test suites have been written, they should be compiled as regular C files
(e.g.: gcc -c my_suite.c).

The next step is to generate a driver program that will load the test suites
and execute the test cases. To do this, run testgen.rb, with the following
syntax:

	testgen.rb <out.c> <test_suite_1> [<test_suite_2>]

The first parameter is the name of the program to generate, and the following
arguments are the name of the compiled test suites produced previously.

Once this is done, compile the generated program, and mt.c  as you would
compile any C program (e.g.: gcc -c out.c mt.c).

Finally, link together mt.o, the compiled generated program, the compiled test
suites, and the object files or libraries that contain the functions being
called from the test cases.


== Running the test application ==

To run the tests, simply run the test driver binary created above. It will
print the name of the test suites it runs, print any message generated by
failed MT_ASSERTS or by MT_ABORT, and finally, some statistics about the total
number of test cases and of assertions, and how many of these were successful.

To only get the messages from MT_ASSERTS and MT_ABORT, run the test driver with
"-s" as a parameter. This is useful when calling it from makefiles, as it
generates errors in the same format as compilers do, to make it easy for text
editors to show the relevant part of the source code.