begriffs open source - libtap/blob - README

   1 NAME
   2 ====
   3
   4 libtap - Write tests in C
   5
   6 SYNOPSIS
   7 ========
   8
   9     #include <tap.h>
  10
  11     int foo () {return 3;}
  12
  13     int main () {
  14         plan(4);
  15         ok(foo() == 3);
  16         ok(foo() == 55);
  17         ok(foo() > 2, "foo returns a number greater than 2");
  18         ok(foo() <= 8732, "foo is less than or equal to %d", 8732);
  19         return exit_status();
  20     }
  21
  22 results in:
  23
  24     1..4
  25     ok 1
  26     not ok 2
  27     #   Failed test at synopsis.c line 8.
  28     ok 3 - foo returns a number greater than 2
  29     ok 4 - foo is less than or equal to 8732
  30     # Looks like you failed 1 test of 4 run.
  31
  32
  33 DESCRIPTION
  34 ===========
  35
  36 tap is an easy to read and easy to write way of creating tests for your
  37 software. This library creates functions that can be used to generate it for
  38 your C programs. It is mostly based on the Test::More Perl module.
  39
  40 FUNCTIONS
  41 =========
  42
  43 -   plan(tests)
  44 -   plan(NO_PLAN)
  45
  46     Use this to start a series of tests. When you know how many tests there
  47     will be, you can put a number as a number of tests you expect to run. If
  48     you do not know how many tests there will be, you can use plan(NO_PLAN)
  49     or not call this function. When you pass it a number of tests to run, a
  50     message similar to the following will appear in the output:
  51
  52         1..5
  53
  54 -   ok(test)
  55 -   ok(test, fmt, ...)
  56
  57     Specify a test. the test can be any statement returning a true or false
  58     value. You may optionally pass a format string describing the test.
  59
  60         ok(r = reader_new("Of Mice and Men"), "create a new reader");
  61         ok(reader_go_to_page(r, 55), "can turn the page");
  62         ok(r->page == 55, "page turned to the right one");
  63
  64     Should print out:
  65
  66         ok 1 - create a new reader
  67         ok 2 - can turn the page
  68         ok 3 - page turned to the right one
  69
  70     On failure, a diagnostic message will be printed out.
  71
  72         not ok 3 - page turned to the right one
  73         #   Failed test 'page turned to the right one'
  74         #   at reader.c line 13.
  75
  76 -   pass()
  77 -   pass(fmt, ...)
  78 -   fail()
  79 -   fail(fmt, ...)
  80
  81     Speciy that a test succeeded or failed. Use these when the statement is
  82     longer than you can fit into the argument given to an ok() test.
  83
  84 -   dies_ok(code)
  85 -   dies_ok(code, fmt, ...)
  86 -   lives_ok(code)
  87 -   lives_ok(code, fmt, ...)
  88
  89     tests whether the given code causes your program to exit. The code gets
  90     passed to a macro that will test it in a forked process. If the code
  91     succeeds it will be executed in the parent process. You can test things
  92     like passing a function a null pointer and make sure it doesnt
  93     dereference it and crash.
  94
  95         dies_ok({abort();}, "abort does close your program");
  96         dies_ok({int x = 0/0;}, "divide by zero crash");
  97         double d = 0;
  98         lives ok({d = pow(3.0, 5.0)}, "nothing wrong with taking 3**5");
  99         ok(d > pow(3.0, 4.0), "3**5 is greater than 3**4");
 100
 101 -   exit_status()
 102
 103     Summarizes the tests that occurred. If there was no plan, it will print
 104     out the number of tests as.
 105
 106         1..5
 107
 108     it will also exit with EXIT_SUCCESS or EXIT_FAILURE depending on whether
 109     there were any failures. If there was a plan and the number of tests are
 110     not equal to the expected number, it will exit with a failure and print a
 111     message about it. It will also print a diagnostic message about how many
 112     failures there were.
 113
 114         # Looks like you failed 2 tests of 3 run.
 115
 116 -   note(fmt, ...)
 117 -   diag(fmt, ...)
 118
 119     print out a message to the tap output. note prints to stdout and diag
 120     prints to stderr. Each line is preceeded by a "# " so that you know its a
 121     diagnostic message.
 122
 123         note("This is\na note\nto describe\nsomething.");
 124
 125     prints:
 126
 127         # This is
 128         # a note
 129         # to describe
 130         # something
 131
 132     ok() and these functions return ints so you can use them like:
 133
 134         ok(1) && note("yo!");
 135         ok(0) || diag("I have no idea what just happened");
 136
 137