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 -   cmp_mem(got, expected, n)
 122 -   cmp_mem(got, expected, n, fmt, ...)
 123
 124     Tests that the first n bytes of the memory you got is what you expected.
 125     You have to take care that the pointers are valid and n is not greater than
 126     the the amount of memory allocated for either got or expected.
 127
 128         char *a = "foo";
 129         char *b = "bar";
 130         cmp_mem(a, b, 3)
 131
 132     prints
 133
 134         not ok 1
 135         #   Failed test at t/cmp_mem.c line 9.
 136         #     Difference starts at offset 0
 137         #          got: '0x66'
 138         #     expected: '0x62'
 139
 140 -   like(got, expected)
 141 -   like(got, expected, fmt, ...)
 142 -   unlike(got, unexpected)
 143 -   unlike(got, unexpected, fmt, ...)
 144
 145     Tests that the string you got matches the expected extended POSIX regex.
 146     unlike is the reverse. These macros are the equivalent of a skip on
 147     Windows.
 148
 149         like("stranger", "^s.(r).*\\1$", "matches the regex");
 150
 151     prints:
 152
 153         ok 1 - matches the regex
 154
 155 -   pass()
 156 -   pass(fmt, ...)
 157 -   fail()
 158 -   fail(fmt, ...)
 159
 160     Speciy that a test succeeded or failed. Use these when the statement is
 161     longer than you can fit into the argument given to an ok() test.
 162
 163 -   dies_ok(code)
 164 -   dies_ok(code, fmt, ...)
 165 -   lives_ok(code)
 166 -   lives_ok(code, fmt, ...)
 167
 168     Tests whether the given code causes your program to exit. The code gets
 169     passed to a macro that will test it in a forked process. If the code
 170     succeeds it will be executed in the parent process. You can test things
 171     like passing a function a null pointer and make sure it doesnt
 172     dereference it and crash.
 173
 174         dies_ok({abort();}, "abort does close your program");
 175         dies_ok({int x = 0/0;}, "divide by zero crash");
 176         lives_ok({pow(3.0, 5.0);}, "nothing wrong with taking 3**5");
 177
 178     On Windows, these macros are the equivalent of a skip.
 179
 180 -   done_testing()
 181
 182     Summarizes the tests that occurred and exits the main function. If
 183     there was no plan, it will print out the number of tests as.
 184
 185         1..5
 186
 187     It will also print a diagnostic message about how many
 188     failures there were.
 189
 190         # Looks like you failed 2 tests of 3 run.
 191
 192     If all planned tests were successful, it will return 0. If any test fails,
 193     it will return the number of failed tests (including ones that were
 194     missing). If they all passed, but there were missing tests, it will return
 195     255.
 196
 197 -   note(fmt, ...)
 198 -   diag(fmt, ...)
 199
 200     print out a message to the tap output. note prints to stdout and diag
 201     prints to stderr. Each line is preceeded by a "# " so that you know its a
 202     diagnostic message.
 203
 204         note("This is\na note\nto describe\nsomething.");
 205
 206     prints:
 207
 208         # This is
 209         # a note
 210         # to describe
 211         # something
 212
 213     ok() and these functions return ints so you can use them like:
 214
 215         ok(1) && note("yo!");
 216         ok(0) || diag("I have no idea what just happened");
 217
 218 -   skip(test, n)
 219 -   skip(test, n, fmt, ...)
 220 -   end_skip
 221
 222     Skip a series of n tests if test is true. You may give a reason why you are
 223     skipping them or not. The (possibly) skipped tests must occur between the
 224     skip and end_skip macros.
 225
 226         skip(TRUE, 2);
 227         ok(1);
 228         ok(0);
 229         end_skip;
 230
 231     prints:
 232
 233         ok 1 # skip
 234         ok 2 # skip
 235
 236 -   todo()
 237 -   todo(fmt, ...)
 238 -   end_todo
 239
 240     Specifies a series of tests that you expect to fail because they are not
 241     yet implemented.
 242
 243         todo()
 244         ok(0);
 245         end_todo;
 246
 247     prints:
 248
 249         not ok 1 # TODO
 250         #   Failed (TODO) test at todo.c line 7
 251
 252 -   BAIL_OUT()
 253 -   BAIL_OUT(fmt, ...)
 254
 255     Immediately stops all testing.
 256
 257         BAIL_OUT("Can't go no further");
 258
 259     prints
 260
 261         Bail out!  Can't go no further
 262
 263     and exits with 255.
 264