=head1 Unit testing

Ermyth provides a simple yet powerful and specialised unit testing framework.
Tests are grouped by putting them in files. For example all tests regarding
metadata go into F<test/metadata.C>. Tests are compiled to .t files, which are
simple executables that get run by make test.

=head2 Test boilerplate

The very first line each testgroup should be

   #include "unit/test.h"

and the very last line should be

   #include "unit/runtest.h"

=head2 Defining tests

Defining tests is very simple:

   test<number> ()
   {
     // do something here
   }

=head2 Assertions

Ermyth's unit test framework provides five assertions:

=over

=item ensure (expr)

Writes an error if C<expr> does not evaluate to a true value.

=item ensure_streq (str, expected)

Checks with strcmp whether C<str> and C<expected> are equal.
Both C<str> and C<expected> need to be one of C<char *>,
C<char const *>, C<char const * const> or an C<unsigned> variant of one.

=item ensure_null (expr)

Checks whether expr is NULL or 0.
This check requires C<expr> to be
L<EqualityComparable|http://www.generic-programming.org/languages/conceptcpp/concept_web.php?header=concepts#EqualityComparable>.

=item ensure_equals (actual, expected)

Checks whether C<actual> evaluates to C<expected>.
This check requires C<actual> and C<expected> to be
L<EqualityComparable|http://www.generic-programming.org/languages/conceptcpp/concept_web.php?header=concepts#EqualityComparable>.

=item ensure_distance (actual, expected, tolerance)

Checks whether C<actual> is at most C<tolerance> away from C<expected>.
To allow this comparison, C<actual> and C<tolerance> need to be
L<Addable|http://www.generic-programming.org/languages/conceptcpp/concept_web.php?header=concepts#Addable>
and their sum together with C<expected> needs to be
L<LessThanComparable|http://www.generic-programming.org/languages/conceptcpp/concept_web.php?header=concepts#LessThanComparable>.


=head2 Example

The following example can be found in F<test/metadata.C>:

   #include "unit/test.h"

   test<1> ()
   {
     metadata *md;
     myuser_t *mu = myuser_add ("name", "pass", "email", 0);

     mu->add_metadata ("cow", "moo");
     ensure_streq (md->value, "moo");
     mu->del_metadata ("cow");
     mu->add_metadata ("cow2", "moo2");
     mu->clear_metadata ();
     ensure_null (md);
   }

   #include "unit/runtest.h"