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