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