[1/5] t/README: make the 'Skipping tests' section less confusing
diff mbox series

Message ID 20181127225445.30045-1-avarab@gmail.com
State New
Headers show
  • [1/5] t/README: make the 'Skipping tests' section less confusing
Related show

Commit Message

Ævar Arnfjörð Bjarmason Nov. 27, 2018, 10:54 p.m. UTC
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@gmail.com>
 t/README | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff mbox series

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
-	    skip_all='skipping perl interface tests, perl not available'
+	    skip_all="skipping symlink tests, the filesystem doesn't support it"