From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 11 Mar 2025 21:25:00 +0000 (-0700)
Subject: t: document test_lazy_prereq
X-Git-Tag: v2.50.0-rc0~153^2~5
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ab362fc6f4cf795a8e3e868cb6fc3ae0102c8d42;p=thirdparty%2Fgit.git

t: document test_lazy_prereq

The t/README file talked about test_set_prereq but lacked
explanation on test_lazy_prereq, which is a more modern way to
define prerequisites.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

diff --git a/t/README b/t/README
index 53e5b4a710..3ce9f5a393 100644
--- a/t/README
+++ b/t/README
@@ -818,7 +818,7 @@ Skipping tests
 --------------
 
 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
+of the test_expect_* functions (see the "Test harness library" section
 below), e.g.:
 
     test_expect_success PERL 'I need Perl' '
@@ -965,6 +965,27 @@ see test-lib-functions.sh for the full list and their options.
 	    test_done
 	fi
 
+ - test_lazy_prereq <prereq> <script>
+
+   Declare the way to determine if a test prerequisite <prereq> is
+   satisified or not, but delay the actual determination until the
+   prerequisite is actually used by "test_have_prereq" or the
+   three-arg form of the test_expect_* functions.  For example, this
+   is how the SYMLINKS prerequisite is declared to see if the platform
+   supports symbolic links:
+
+	test_lazy_prereq SYMLINKS '
+		ln -s x y && test -h y
+	'
+
+   The script is lazily invoked when SYMLINKS prerequisite is first
+   queried by either "test_have_prereq SYMLINKS" or "test_expect_*
+   SYMLINKS ...".  The script is run in a temporary directory inside
+   a subshell, so you do not have to worry about removing temporary
+   files you create there.  When the script exits with status 0, the
+   prerequisite is set.  Exiting with non-zero status makes the
+   prerequisite unsatisified.
+
  - test_expect_code <exit-code> <command>
 
    Run a command and ensure that it exits with the given exit code.