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 -   like(got, expected)
  98 -   like(got, expected, fmt, ...)
  99 -   unlike(got, expected)
 100 -   unlike(got, expected, fmt, ...)
 101
 102     Tests that the string you got matches the expected extended POSIX regex.
 103     unlike is the reverse. These macros are the equivalent of a skip on
 104     Windows.
 105
 106         like("stranger", "^s.(r).*\\1$", "matches the regex");
 107
 108     prints:
 109
 110         ok 1 - matches the regex
 111
 112 -   pass()
 113 -   pass(fmt, ...)
 114 -   fail()
 115 -   fail(fmt, ...)
 116
 117     Speciy that a test succeeded or failed. Use these when the statement is
 118     longer than you can fit into the argument given to an ok() test.
 119
 120 -   dies_ok(code)
 121 -   dies_ok(code, fmt, ...)
 122 -   lives_ok(code)
 123 -   lives_ok(code, fmt, ...)
 124
 125     Tests whether the given code causes your program to exit. The code gets
 126     passed to a macro that will test it in a forked process. If the code
 127     succeeds it will be executed in the parent process. You can test things
 128     like passing a function a null pointer and make sure it doesnt
 129     dereference it and crash.
 130
 131         dies_ok({abort();}, "abort does close your program");
 132         dies_ok({int x = 0/0;}, "divide by zero crash");
 133         lives ok({pow(3.0, 5.0)}, "nothing wrong with taking 3**5");
 134
 135     On Windows, these macros are the equivalent of a skip.
 136
 137 -   exit_status()
 138
 139     Summarizes the tests that occurred. If there was no plan, it will print
 140     out the number of tests as.
 141
 142         1..5
 143
 144     It will also print a diagnostic message about how many
 145     failures there were.
 146
 147         # Looks like you failed 2 tests of 3 run.
 148
 149     If all planned tests were successful, it will return 0. If any test fails,
 150     it will return the number of failed tests (including ones that were
 151     missing). If they all passed, but there were missing tests, it will return
 152     255.
 153
 154 -   note(fmt, ...)
 155 -   diag(fmt, ...)
 156
 157     print out a message to the tap output. note prints to stdout and diag
 158     prints to stderr. Each line is preceeded by a "# " so that you know its a
 159     diagnostic message.
 160
 161         note("This is\na note\nto describe\nsomething.");
 162
 163     prints:
 164
 165         # This is
 166         # a note
 167         # to describe
 168         # something
 169
 170     ok() and these functions return ints so you can use them like:
 171
 172         ok(1) && note("yo!");
 173         ok(0) || diag("I have no idea what just happened");
 174
 175 -   skip(test, n)
 176 -   skip(test, n, fmt, ...)
 177 -   endskip
 178
 179     Skip a series of n tests if test is true. You may give a reason why you are
 180     skipping them or not. The (possibly) skipped tests must occur between the
 181     skip and endskip macros.
 182
 183         skip(TRUE, 2);
 184         ok(1);
 185         ok(0);
 186         endskip;
 187
 188     prints:
 189
 190         ok 1 # skip
 191         ok 2 # skip
 192
 193 -   todo()
 194 -   todo(fmt, ...)
 195 -   endtodo
 196
 197     Specifies a series of tests that you expect to fail because they are not
 198     yet implemented.
 199
 200         todo()
 201         ok(0);
 202         endtodo;
 203
 204     prints:
 205
 206         not ok 1 # TODO
 207         #   Failed (TODO) test at todo.c line 7
 208