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