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