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 done_testing();

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)

54 - plan(SKIP_ALL);

55 - plan(SKIP_ALL, fmt, ...)

57 Use this to start a series of tests. When you know how many tests there

58 will be, you can put a number as a number of tests you expect to run. If

59 you do not know how many tests there will be, you can use plan(NO_PLAN)

60 or not call this function. When you pass it a number of tests to run, a

61 message similar to the following will appear in the output:

63 1..5

65 If you pass it SKIP_ALL, the whole test will be skipped.

67 - ok(test)

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

70 Specify a test. the test can be any statement returning a true or false

71 value. You may optionally pass a format string describing the test.

73 ok(r = reader_new("Of Mice and Men"), "create a new reader");

74 ok(reader_go_to_page(r, 55), "can turn the page");

75 ok(r->page == 55, "page turned to the right one");

77 Should print out:

79 ok 1 - create a new reader

80 ok 2 - can turn the page

81 ok 3 - page turned to the right one

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

85 not ok 3 - page turned to the right one

86 # Failed test 'page turned to the right one'

87 # at reader.c line 13.

89 - is(got, expected)

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

91 - isnt(got, expected)

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

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

95 reverse.

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

99 prints:

100

101 not ok 1 - this is that

102 # Failed test 'this is that'

103 # at is.c line 6.

104 # got: 'this'

105 # expected: 'that'

106

107 - cmp_ok(a, op, b)

108 - cmp_ok(a, op, b, fmt, ...)

109

110 Compares two ints with any binary operator that doesn't require an lvalue.

111 This is nice to use since it provides a better error message than an

112 equivalent ok.

113

114 cmp_ok(420, ">", 666);

115

116 prints:

117

118 not ok 1

119 # Failed test at cmpok.c line 5.

120 # 420

121 # >

122 # 666

123

124 - like(got, expected)

125 - like(got, expected, fmt, ...)

126 - unlike(got, expected)

127 - unlike(got, expected, fmt, ...)

128

129 Tests that the string you got matches the expected extended POSIX regex.

130 unlike is the reverse. These macros are the equivalent of a skip on

131 Windows.

132

133 like("stranger", "^s.(r).*\\1$", "matches the regex");

134

135 prints:

136

137 ok 1 - matches the regex

138

139 - pass()

140 - pass(fmt, ...)

141 - fail()

142 - fail(fmt, ...)

143

144 Speciy that a test succeeded or failed. Use these when the statement is

145 longer than you can fit into the argument given to an ok() test.

146

147 - dies_ok(code)

148 - dies_ok(code, fmt, ...)

149 - lives_ok(code)

150 - lives_ok(code, fmt, ...)

151

152 Tests whether the given code causes your program to exit. The code gets

153 passed to a macro that will test it in a forked process. If the code

154 succeeds it will be executed in the parent process. You can test things

155 like passing a function a null pointer and make sure it doesnt

156 dereference it and crash.

157

158 dies_ok({abort();}, "abort does close your program");

159 dies_ok({int x = 0/0;}, "divide by zero crash");

160 lives_ok({pow(3.0, 5.0);}, "nothing wrong with taking 3**5");

161

162 On Windows, these macros are the equivalent of a skip.

163

164 - done_testing()

165

166 Summarizes the tests that occurred and exits the main function. If

167 there was no plan, it will print out the number of tests as.

168

169 1..5

170

171 It will also print a diagnostic message about how many

172 failures there were.

173

174 # Looks like you failed 2 tests of 3 run.

175

176 If all planned tests were successful, it will return 0. If any test fails,

177 it will return the number of failed tests (including ones that were

178 missing). If they all passed, but there were missing tests, it will return

179 255.

180

181 - note(fmt, ...)

182 - diag(fmt, ...)

183

184 print out a message to the tap output. note prints to stdout and diag

185 prints to stderr. Each line is preceeded by a "# " so that you know its a

186 diagnostic message.

187

188 note("This is\na note\nto describe\nsomething.");

189

190 prints:

191

192 # This is

193 # a note

194 # to describe

195 # something

196

197 ok() and these functions return ints so you can use them like:

198

199 ok(1) && note("yo!");

200 ok(0) || diag("I have no idea what just happened");

201

202 - skip(test, n)

203 - skip(test, n, fmt, ...)

204 - endskip

205

206 Skip a series of n tests if test is true. You may give a reason why you are

207 skipping them or not. The (possibly) skipped tests must occur between the

208 skip and endskip macros.

209

210 skip(TRUE, 2);

211 ok(1);

212 ok(0);

213 endskip;

214

215 prints:

216

217 ok 1 # skip

218 ok 2 # skip

219

220 - todo()

221 - todo(fmt, ...)

222 - endtodo

223

224 Specifies a series of tests that you expect to fail because they are not

225 yet implemented.

226

227 todo()

228 ok(0);

229 endtodo;

230

231 prints:

232

233 not ok 1 # TODO

234 # Failed (TODO) test at todo.c line 7

235

236 - BAIL_OUT()

237 - BAIL_OUT(fmt, ...)

238

239 Immediately stops all testing.

240

241 BAIL_OUT("Can't go no further");

242

243 prints

244

245 Bail out! Can't go no further

246

247 and exits with 255.

248