t/README: Document the prereq functions, and 3-arg test_*
There was no documentation for the test_set_prereq and test_have_prereq functions, or the three-arg form of test_expect_success and test_expect_failure. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Jul 2, 2010 at 14:59 UTC
9a897893a76063a1fbe07f62ba78ab8f5308dbd3
1 file changed
+34
-3
t/README
+34
-3
@@ -246,9 +246,9 @@ Test harness library
246
There are a handful helper functions defined in the test harness
247
library for your script to use.
248
249
- - test_expect_success <message> <script>
249
+ - test_expect_success [<prereq>] <message> <script>
250
251
- This takes two strings as parameter, and evaluates the
251
+ Usually takes two strings as parameter, and evaluates the
252
<script>. If it yields success, test is considered
253
successful. <message> should state what it is testing.
254
@@ -258,7 +258,14 @@ library for your script to use.
258
'git-write-tree should be able to write an empty tree.' \
259
'tree=$(git-write-tree)'
260
261
- - test_expect_failure <message> <script>
261
+ If you supply three parameters the first will be taken to be a
262
+ prerequisite, see the test_set_prereq and test_have_prereq
263
+ documentation below:
264
+
265
+ test_expect_success TTY 'git --paginate rev-list uses a pager' \
266
+ ' ... '
267
+
268
+ - test_expect_failure [<prereq>] <message> <script>
269
270
This is NOT the opposite of test_expect_success, but is used
271
to mark a test that demonstrates a known breakage. Unlike
@@ -267,6 +274,9 @@ library for your script to use.
274
success and "still broken" on failure. Failures from these
275
tests won't cause -i (immediate) to stop.
276
277
+ Like test_expect_success this function can optionally use a three
278
+ argument invocation with a prerequisite as the first argument.
279
+
280
- test_debug <script>
281
282
This takes a single argument, <script>, and evaluates it only
@@ -299,6 +309,27 @@ library for your script to use.
309
Merges the given rev using the given message. Like test_commit,
310
creates a tag and calls test_tick before committing.
311
312
+ - test_set_prereq SOME_PREREQ
313
+
314
+ Set a test prerequisite to be used later with test_have_prereq. The
315
+ test-lib will set some prerequisites for you, e.g. PERL and PYTHON
316
+ which are derived from ./GIT-BUILD-OPTIONS (grep test_set_prereq
317
+ test-lib.sh for more). Others you can set yourself and use later
318
+ with either test_have_prereq directly, or the three argument
319
+ invocation of test_expect_success and test_expect_failure.
320
+
321
+ - test_have_prereq SOME PREREQ
322
+
323
+ Check if we have a prerequisite previously set with
324
+ test_set_prereq. The most common use of this directly is to skip
325
+ all the tests if we don't have some essential prerequisite:
326
+
327
+ if ! test_have_prereq PERL
328
+ then
329
+ skip_all='skipping perl interface tests, perl not available'
330
+ test_done
331
+ fi
332
+
333
Tips for Writing Tests
334
----------------------
335