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