begriffs open source - libtap/blob - README.md

   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     char *bar () {return "fnord";}
  13
  14     int main () {
  15         plan(5);
  16         ok(foo() == 3);
  17         is(bar(), "eek");
  18         ok(foo() <= 8732, "foo <= %d", 8732);
  19         like(bar(), "f(yes|no)r*[a-f]$", "is like");
  20         cmp_ok(foo(), ">=", 10, "foo is greater than ten");
  21         done_testing();
  22     }
  23
  24 results in:
  25
  26     1..5
  27     ok 1
  28     not ok 2
  29     #   Failed test at synopsis.c line 9.
  30     #          got: 'fnord'
  31     #     expected: 'eek'
  32     ok 3 - foo <= 8732
  33     ok 4 - is like
  34     not ok 5 - foo is greater than ten
  35     #   Failed test 'foo is greater than ten'
  36     #   at synopsis.c line 12.
  37     #     3
  38     #         >=
  39     #     10
  40     # Looks like you failed 2 tests of 5 run.
  41
  42 DESCRIPTION
  43 ===========
  44
  45 tap is an easy to read and easy to write way of creating tests for your
  46 software. This library creates functions that can be used to generate it for
  47 your C programs. It is mostly based on the Test::More Perl module.
  48
  49 FUNCTIONS
  50 =========
  51
  52 -   plan(tests)
  53 -   plan(NO_PLAN)
  54 -   plan(SKIP_ALL);
  55 -   plan(SKIP_ALL, fmt, ...)
  56
  57     Use this to start a series of tests. When you know how many tests there
  58     will be, you can put a number as a number of tests you expect to run. If
  59     you do not know how many tests there will be, you can use plan(NO_PLAN)
  60     or not call this function. When you pass it a number of tests to run, a
  61     message similar to the following will appear in the output:
  62
  63         1..5
  64
  65     If you pass it SKIP_ALL, the whole test will be skipped.
  66
  67 -   ok(test)
  68 -   ok(test, fmt, ...)
  69
  70     Specify a test. the test can be any statement returning a true or false
  71     value. You may optionally pass a format string describing the test.
  72
  73         ok(r = reader_new("Of Mice and Men"), "create a new reader");
  74         ok(reader_go_to_page(r, 55), "can turn the page");
  75         ok(r->page == 55, "page turned to the right one");
  76
  77     Should print out:
  78
  79         ok 1 - create a new reader
  80         ok 2 - can turn the page
  81         ok 3 - page turned to the right one
  82
  83     On failure, a diagnostic message will be printed out.
  84
  85         not ok 3 - page turned to the right one
  86         #   Failed test 'page turned to the right one'
  87         #   at reader.c line 13.
  88
  89 -   is(got, expected)
  90 -   is(got, expected, fmt, ...)
  91 -   isnt(got, expected)
  92 -   isnt(got, expected, fmt, ...)
  93
  94     Tests that the string you got is what you expected. with isnt, it is the
  95     reverse.
  96
  97         is("this", "that", "this is that");
  98
  99     prints:
 100
 101         not ok 1 - this is that
 102         #   Failed test 'this is that'
 103         #   at is.c line 6.
 104         #          got: 'this'
 105         #     expected: 'that'
 106
 107 -   cmp_ok(a, op, b)
 108 -   cmp_ok(a, op, b, fmt, ...)
 109
 110     Compares two ints with any binary operator that doesn't require an lvalue.
 111     This is nice to use since it provides a better error message than an
 112     equivalent ok.
 113
 114         cmp_ok(420, ">", 666);
 115
 116     prints:
 117
 118         not ok 1
 119         #   Failed test at cmpok.c line 5.
 120         #     420
 121         #         >
 122         #     666
 123
 124 -   like(got, expected)
 125 -   like(got, expected, fmt, ...)
 126 -   unlike(got, expected)
 127 -   unlike(got, expected, fmt, ...)
 128
 129     Tests that the string you got matches the expected extended POSIX regex.
 130     unlike is the reverse. These macros are the equivalent of a skip on
 131     Windows.
 132
 133         like("stranger", "^s.(r).*\\1$", "matches the regex");
 134
 135     prints:
 136
 137         ok 1 - matches the regex
 138
 139 -   pass()
 140 -   pass(fmt, ...)
 141 -   fail()
 142 -   fail(fmt, ...)
 143
 144     Speciy that a test succeeded or failed. Use these when the statement is
 145     longer than you can fit into the argument given to an ok() test.
 146
 147 -   dies_ok(code)
 148 -   dies_ok(code, fmt, ...)
 149 -   lives_ok(code)
 150 -   lives_ok(code, fmt, ...)
 151
 152     Tests whether the given code causes your program to exit. The code gets
 153     passed to a macro that will test it in a forked process. If the code
 154     succeeds it will be executed in the parent process. You can test things
 155     like passing a function a null pointer and make sure it doesnt
 156     dereference it and crash.
 157
 158         dies_ok({abort();}, "abort does close your program");
 159         dies_ok({int x = 0/0;}, "divide by zero crash");
 160         lives_ok({pow(3.0, 5.0);}, "nothing wrong with taking 3**5");
 161
 162     On Windows, these macros are the equivalent of a skip.
 163
 164 -   done_testing()
 165
 166     Summarizes the tests that occurred and exits the main function. If
 167     there was no plan, it will print out the number of tests as.
 168
 169         1..5
 170
 171     It will also print a diagnostic message about how many
 172     failures there were.
 173
 174         # Looks like you failed 2 tests of 3 run.
 175
 176     If all planned tests were successful, it will return 0. If any test fails,
 177     it will return the number of failed tests (including ones that were
 178     missing). If they all passed, but there were missing tests, it will return
 179     255.
 180
 181 -   note(fmt, ...)
 182 -   diag(fmt, ...)
 183
 184     print out a message to the tap output. note prints to stdout and diag
 185     prints to stderr. Each line is preceeded by a "# " so that you know its a
 186     diagnostic message.
 187
 188         note("This is\na note\nto describe\nsomething.");
 189
 190     prints:
 191
 192         # This is
 193         # a note
 194         # to describe
 195         # something
 196
 197     ok() and these functions return ints so you can use them like:
 198
 199         ok(1) && note("yo!");
 200         ok(0) || diag("I have no idea what just happened");
 201
 202 -   skip(test, n)
 203 -   skip(test, n, fmt, ...)
 204 -   endskip
 205
 206     Skip a series of n tests if test is true. You may give a reason why you are
 207     skipping them or not. The (possibly) skipped tests must occur between the
 208     skip and endskip macros.
 209
 210         skip(TRUE, 2);
 211         ok(1);
 212         ok(0);
 213         endskip;
 214
 215     prints:
 216
 217         ok 1 # skip
 218         ok 2 # skip
 219
 220 -   todo()
 221 -   todo(fmt, ...)
 222 -   endtodo
 223
 224     Specifies a series of tests that you expect to fail because they are not
 225     yet implemented.
 226
 227         todo()
 228         ok(0);
 229         endtodo;
 230
 231     prints:
 232
 233         not ok 1 # TODO
 234         #   Failed (TODO) test at todo.c line 7
 235
 236 -   BAIL_OUT()
 237 -   BAIL_OUT(fmt, ...)
 238
 239     Immediately stops all testing.
 240
 241         BAIL_OUT("Can't go no further");
 242
 243     prints
 244
 245         Bail out!  Can't go no further
 246
 247     and exits with 255.
 248