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