I added this section in b5500d16cd ("t/README: Add a section about
skipping tests", 2010-07-02), but apparently didn't notice that there
was an existing "Skipping Tests" section added in
fbd458a3f6 ("t/README: Add 'Skipping Tests' section below 'Running
Tests'", 2008-06-20).
Then since 20873f45e7 ("t/README: Document the do's and don'ts of
tests", 2010-07-02) and 0445e6f0a1 ("test-lib: '--run' to run only
specific tests", 2014-04-30) we've started to refer to "Skipping
tests" or "Skipping Tests" sections in prose elsewhere.
Let's clean up this confusion by renaming the section, and while we're
at it improve the example. Usually we don't use the PERL prerequisite,
and we should accurately describe why you'd want to use prerequisites,
as opposed to GIT_SKIP_TESTS. So let's say "Tests that depend[...]"
instead of "If you need to skip tests[...]" here.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx>
---
t/README | 22 +++++++++++-----------
1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/t/README b/t/README
index 28711cc508..b6ec28f634 100644
--- a/t/README
+++ b/t/README
@@ -494,7 +494,7 @@ And here are the "don'ts:"
The harness will catch this as a programming error of the test.
Use test_done instead if you need to stop the tests early (see
- "Skipping tests" below).
+ "Using test prerequisites" below).
- Don't use '! git cmd' when you want to make sure the git command
exits with failure in a controlled way by calling "die()". Instead,
@@ -587,28 +587,28 @@ And here are the "don'ts:"
it'll complain if anything is amiss.
-Skipping tests
---------------
+Using test prerequisites
+------------------------
-If you need to skip tests you should do so by using the three-arg form
-of the test_* functions (see the "Test harness library" section
-below), e.g.:
+Tests that depend on something which may not be present on the system
+should use the three-arg form of the test_* functions (see the "Test
+harness library" section below), e.g.:
- test_expect_success PERL 'I need Perl' '
- perl -e "hlagh() if unf_unf()"
+ test_expect_success SYMLINKS 'setup' '
+ ln -s target link
'
The advantage of skipping tests like this is that platforms that don't
-have the PERL and other optional dependencies get an indication of how
+have the SYMLINKS and other optional dependencies get an indication of how
many tests they're missing.
If the test code is too hairy for that (i.e. does a lot of setup work
outside test assertions) you can also skip all remaining tests by
setting skip_all and immediately call test_done:
- if ! test_have_prereq PERL
+ if ! test_have_prereq SYMLINKS
then
- skip_all='skipping perl interface tests, perl not available'
+ skip_all="skipping symlink tests, the filesystem doesn't support it"
test_done
fi
--
2.20.0.rc1.379.g1dd7ef354c
