t/README: Update "Skipping tests" to align with best practices
The example I initially added to "Skipping tests" wasn't very good. We'd rather skip tests using the three-arg prereq form to the test_* functions, not bail out with a skip message. Change the documentation to reflect that, but retain the bailout example under a disclaimer which explains that it's probably not a good idea to use it. 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 28, 2010 at 10:34 UTC
99d9050d256d1a928ce6d13fe275d8fd4bfcbdee
1 file changed
+18
-3
t/README
+18
-3
@@ -319,9 +319,21 @@ Keep in mind:
319
Skipping tests
320
--------------
321
322
-If you need to skip all the remaining tests you should set skip_all
323
-and immediately call test_done. The string you give to skip_all will
324
-be used as an explanation for why the test was skipped. for instance:
322
+If you need to skip tests you should do so be using the three-arg form
323
+of the test_* functions (see the "Test harness library" section
324
+below), e.g.:
325
+
326
+ test_expect_success PERL 'I need Perl' "
327
+ '$PERL_PATH' -e 'hlagh() if unf_unf()'
328
+ "
329
+
330
+The advantage of skipping tests like this is that platforms that don't
331
+have the PERL and other optional dependencies get an indication of how
332
+many tests they're missing.
333
+
334
+If the test code is too hairy for that (i.e. does a lot of setup work
335
+outside test assertions) you can also skip all remaining tests by
336
+setting skip_all and immediately call test_done:
337
338
if ! test_have_prereq PERL
339
then
@@ -329,6 +341,9 @@ be used as an explanation for why the test was skipped. for instance:
341
test_done
342
fi
343
344
+The string you give to skip_all will be used as an explanation for why
345
+the test was skipped.
346
+
347
End with test_done
348
------------------
349