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