NAME
====

libtap - Write tests in C

SYNOPSIS
========

    #include <tap.h>

    int main () {
        plan(5);
        int bronze = 1, silver = 2, gold = 3;
        ok(bronze < silver, "bronze is less than silver");
        ok(bronze > silver, "not quite");
        is("gold", "gold", "gold is gold");
        cmp_ok(silver, "<", gold, "%d <= %d", silver, gold);
        like("platinum", ".*inum", "platinum matches .*inum");
        done_testing();
    }

results in:

    1..5
    ok 1 - bronze is less than silver
    not ok 2 - not quite
    #   Failed test 'not quite'
    #   at t/synopsis.c line 7.
    ok 3 - gold is gold
    ok 4 - 2 <= 3
    ok 5 - platinum matches .*inum
    # Looks like you failed 1 test of 5 run.

DESCRIPTION
===========

tap is an easy to read and easy to write way of creating tests for
your software. This library creates functions that can be used to
generate it for your C programs. It is implemented using macros
that include file and line info automatically, and makes it so that
the format message of each test is optional. It is mostly based on
the Test::More Perl module.

INSTALL
=======

On **Unix** systems:

    $ make
    $ make install

For more detailed installation instructions (eg, for **Windows**), see `INSTALL`.

FUNCTIONS
=========

-   plan(tests)
-   plan(NO_PLAN)
-   plan(SKIP_ALL);
-   plan(SKIP_ALL, fmt, ...)

    Use this to start a series of tests. When you know how many tests there
    will be, you can put a number as a number of tests you expect to run. If
    you do not know how many tests there will be, you can use plan(NO_PLAN)
    or not call this function. When you pass it a number of tests to run, a
    message similar to the following will appear in the output:

        1..5

    If you pass it SKIP_ALL, the whole test will be skipped.

-   ok(test)
-   ok(test, fmt, ...)

    Specify a test. the test can be any statement returning a true or false
    value. You may optionally pass a format string describing the test.

        ok(r = reader_new("Of Mice and Men"), "create a new reader");
        ok(reader_go_to_page(r, 55), "can turn the page");
        ok(r->page == 55, "page turned to the right one");

    Should print out:

        ok 1 - create a new reader
        ok 2 - can turn the page
        ok 3 - page turned to the right one

    On failure, a diagnostic message will be printed out.

        not ok 3 - page turned to the right one
        #   Failed test 'page turned to the right one'
        #   at reader.c line 13.

-   is(got, expected)
-   is(got, expected, fmt, ...)
-   isnt(got, unexpected)
-   isnt(got, unexpected, fmt, ...)

    Tests that the string you got is what you expected. with isnt, it is the
    reverse.

        is("this", "that", "this is that");

    prints:

        not ok 1 - this is that
        #   Failed test 'this is that'
        #   at is.c line 6.
        #          got: 'this'
        #     expected: 'that'

-   cmp_ok(a, op, b)
-   cmp_ok(a, op, b, fmt, ...)

    Compares two ints with any binary operator that doesn't require an lvalue.
    This is nice to use since it provides a better error message than an
    equivalent ok.

        cmp_ok(420, ">", 666);

    prints:

        not ok 1
        #   Failed test at cmpok.c line 5.
        #     420
        #         >
        #     666

-   cmp_mem(got, expected, n)
-   cmp_mem(got, expected, n, fmt, ...)

    Tests that the first n bytes of the memory you got is what you expected.
    NULL pointers for got and expected are handled (if either is NULL,
    the test fails), but you need to ensure n is not too large.

        char *a = "foo";
        char *b = "bar";
        cmp_mem(a, b, 3)

    prints

        not ok 1
        #   Failed test at t/cmp_mem.c line 9.
        #     Difference starts at offset 0
        #          got: 0x66
        #     expected: 0x62

-   like(got, expected)
-   like(got, expected, fmt, ...)
-   unlike(got, unexpected)
-   unlike(got, unexpected, fmt, ...)

    Tests that the string you got matches the expected extended POSIX regex.
    unlike is the reverse. These macros are the equivalent of a skip on
    Windows.

        like("stranger", "^s.(r).*\\1$", "matches the regex");

    prints:

        ok 1 - matches the regex

-   pass()
-   pass(fmt, ...)
-   fail()
-   fail(fmt, ...)

    Speciy that a test succeeded or failed. Use these when the statement is
    longer than you can fit into the argument given to an ok() test.

-   dies_ok(code)
-   dies_ok(code, fmt, ...)
-   lives_ok(code)
-   lives_ok(code, fmt, ...)

    Tests whether the given code causes your program to exit. The code gets
    passed to a macro that will test it in a forked process. If the code
    succeeds it will be executed in the parent process. You can test things
    like passing a function a null pointer and make sure it doesnt
    dereference it and crash.

        dies_ok({abort();}, "abort does close your program");
        dies_ok({int x = 0/0;}, "divide by zero crash");
        lives_ok({pow(3.0, 5.0);}, "nothing wrong with taking 3**5");

    On Windows, these macros are the equivalent of a skip.

-   done_testing()

    Summarizes the tests that occurred and exits the main function. If
    there was no plan, it will print out the number of tests as.

        1..5

    It will also print a diagnostic message about how many
    failures there were.

        # Looks like you failed 2 tests of 3 run.

    If all planned tests were successful, it will return 0. If any
    test fails, it will return 1. If they all passed, but there
    were missing tests, it will return 2.

-   diag(fmt, ...)

    print out a message to the tap output on stdout. Each line is
    preceeded by a "# " so that you know its a diagnostic message.

        diag("This is\na diag\nto describe\nsomething.");

    prints:

        # This is
        # a diag
        # to describe
        # something

    ok() and this function return an int so you can use it like:

        ok(0) || diag("doh!");

-   skip(test, n)
-   skip(test, n, fmt, ...)
-   end_skip

    Skip a series of n tests if test is true. You may give a reason why you are
    skipping them or not. The (possibly) skipped tests must occur between the
    skip and end_skip macros.

        skip(TRUE, 2);
        ok(1);
        ok(0);
        end_skip;

    prints:

        ok 1 # skip
        ok 2 # skip

-   todo()
-   todo(fmt, ...)
-   end_todo

    Specifies a series of tests that you expect to fail because they are not
    yet implemented.

        todo()
        ok(0);
        end_todo;

    prints:

        not ok 1 # TODO
        #   Failed (TODO) test at todo.c line 7

-   BAIL_OUT()
-   BAIL_OUT(fmt, ...)

    Immediately stops all testing.

        BAIL_OUT("Can't go no further");

    prints

        Bail out!  Can't go no further

    and exits with 255.