.TH ticc_unit_test 1 "2015 November 26"

.SH NAME
TiCC Unit Tests - A 'poor mans' C++ Unit testing Framework
.SH SYNOPSIS

.B #include "ticcutils/UnitTest.h"

.SH DESCRIPTION
Ticc Unit Tests provides some powerful functions, combined in a single header
file, which give you a simple way to implement Unit Tests.

Ticc Unit Tests aims at easy usage, an quick implementation, of test suites
without compiling and linking issues. It is possible to create a test suite by
just adding a few assertions around C++ expressions, and Ticc Unit Test will
start working at once: counting the number of tests, failures and providing a
summary at program end.

Compared to other frameworks, like Boost, CPPUNIT or Google there are some
limitations. [But who cares? more to say!]

.SH List of Functions.

.B assertEqual(expression1,expression2)
.RS
test if
.B expression1
equals
.B expression2

If not so: signal the problem and increment the number of detected failures
If so: signal success. (except when part of a
.BR testSerie .
see below)

It is wise to use brackets around the expression, otherwise the compiler may get
confused. See
.B Example " 1"
below.
.RE

.B assertTrue(expression)
.RS
test if
.B expression
evaluates to
.B true

If not so: signal the problem and increment the number of detected failures
If so: signal success. (except when part of a
.BR testSerie .
see below)

It is wise to use brackets around the expression, otherwise the compiler may get
confused. See
.B Example " 1"
below.
.RE

.B assertMessage(message,expression)
.RS
the same as
.B assertTrue()
but also displays
.B message
on failure.
.RE

.B assertThrow(expression,exception)
.RS
test if
.B expression
throws the given
.B exception

If not so: signal the problem and increment the number of detected failures
If so: signal success. (except when part of a
.BR testSerie .
see below)

It is wise to use brackets around the expression, otherwise the compiler may get
confused. See
.B Example " 1"
below.
.RE

.B assertNoThrow(expression)
.RS
test if
.B expression
doesn't throw.

If not so: signal the problem and increment the number of detected failures
If so: signal success. (except when part of a
.BR testSerie .
see below)

It is wise to use brackets around the expression, otherwise the compiler may get
confused. See
.B Example " 1"
below.
.RE

.SH Setting up a testSerie

.B startTestSerie(message)
.RS
Signal the beginning of a series of tests, using
.B message

When a
.B testSerie
is active, all success messages of the
.B assert*
macro's are suppressed. Failures are still signaled. At the end of a
.B testSerie
a summary is given.

.B testSerie
automatically ends at the end of the program block it is declared in.
.RE

.SH suppressing output.
Sometimes it is desirable to suppress excessive success messages, for instance
when one of the
.B assert*
functions is called in a loop.

This can be achieved with the macro's:

.B TEST_SILENT_ON()
and
.B TEST_SILENT_OFF()

all failures are still displayed as to inform you off any trouble.

.SH Summarizing Tests
The Ticc Unit test will automatically give a summary of the results at the end
of the program. It also returns the number of failures to the shell.

It is however possible to call
.BR summarize_tests(expected) .
The advantage is, that you can provide a number
.B expected
to signal that you expected some failures, and that it is
.B not
a showstopper.

.SH EXAMPLES

.BR Example " 1"
.RS
.nf
#include <string>
#include <iostream>
#include "ticcutils/UnitTest.h"
int main(){
  assertEqual( (1+2), (2+1) );
  assertTrue( 0 == 1 );
}
.fi
.RE

The output of this program is:
.RS
.nf
test: main(6):  OK
test: main(7):   FAILED
main(7) : '0' != TRUE
performed 2 tests, 1 failures. We expected 0 failures.
overall   FAILED
.fi
.RE

When an extra line is added at the end of main():
.RS
.nf
  summarize_tests(1);
.fi
.RE

The output changes to:
.RS
.nf
test: main(6):  OK
test: main(7):   FAILED
main(7) : '0' != TRUE
TiCC tests performed 2 tests, with 1 failures. that was what we expected.
overall:  OK
.fi
.RE

.BR Example " 2"
.RS
.nf
#include <string>
#include <iostream>
#include <stdexcept>
#include <cmath>
#include "ticcutils/UnitTest.h"

void helper(){
  throw std::runtime_error("fout");
}

int main(){
  assertThrow( helper(), std::runtime_error );
  assertNoThrow( 1/std::sqrt(0) );
}
.fi
.RE

So we force a runtime error in our helper function, and detect it.
We also attempt a division by zero. But on my system, this will result in an
.B inf
result and
.B NOT
in an exception. Therefor the
.B assertNoThrow()
will be satisfied.

The output of this program is:
.RS
.nf
test: main(13):  OK
test: main(14):  OK
TiCC tests performed 2 tests, with 0 failures. that was what we expected.
overall:  OK
.fi
.RE

.BR Example " 3"
.RS
.nf
.fi
.RE

So we call a separate function to perform a series of tests.

The output of this program is:
.RS
.nf
test: main(17):  OK
Serie:	test1 (Test some numb stuff)
	test1(): all 6 tests OK
test: main(19):  OK
TiCC tests performed 8 tests, with 0 failures. that was what we expected.
overall:  OK
.fi
.RE

As you an see, the results of the tests inside the series are summarized. This
gives us cleaner output.

.SH LIMITATIONS
There is no
.B overall
error detection. So your test program may still fail unexpectedly. For instance on a zero pointer exception or an I/O error.

.SH AUTHORS
Ko van der Sloot lamasoftware@science.ru.nl