begriffs open source - libtap/blob - README

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