begriffs open source - libtap/blob

1 NAME

2 ====

4 libtap - Write tests in C

6 SYNOPSIS

7 ========

9 #include <tap.h>

11 int foo () {return 3;}

12 char *bar () {return "fnord";}

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 return exit_status();

22 }

24 results in:

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.

42 DESCRIPTION

43 ===========

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.

49 FUNCTIONS

50 =========

52 - plan(tests)

53 - plan(NO_PLAN)

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:

61 1..5

63 - ok(test)

64 - ok(test, fmt, ...)

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.

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");

73 Should print out:

75 ok 1 - create a new reader

76 ok 2 - can turn the page

77 ok 3 - page turned to the right one

79 On failure, a diagnostic message will be printed out.

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.

85 - is(got, expected)

86 - is(got, expected, fmt, ...)

87 - isnt(got, expected)

88 - isnt(got, expected, fmt, ...)

90 Tests that the string you got is what you expected. with isnt, it is the

91 reverse.

93 is("this", "that", "this is that");

95 prints:

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 - exit_status()

161

162 Summarizes the tests that occurred. If there was no plan, it will print

163 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