Merge branch 'jk/save-getenv-result'
[gitweb.git] / t / README
index 28711cc508f9e5dfb2f2ef238be14926d56f9a12..11ce7675e32e7042f0ae5ddee1b65a0f6516f175 100644 (file)
--- a/t/README
+++ b/t/README
@@ -186,6 +186,22 @@ appropriately before running "make".
        this feature by setting the GIT_TEST_CHAIN_LINT environment
        variable to "1" or "0", respectively.
 
+--stress::
+--stress=<N>::
+       Run the test script repeatedly in multiple parallel jobs until
+       one of them fails.  Useful for reproducing rare failures in
+       flaky tests.  The number of parallel jobs is, in order of
+       precedence: <N>, or the value of the GIT_TEST_STRESS_LOAD
+       environment variable, or twice the number of available
+       processors (as shown by the 'getconf' utility), or 8.
+       Implies `--verbose -x --immediate` to get the most information
+       about the failure.  Note that the verbose output of each test
+       job is saved to 't/test-results/$TEST_NAME.stress-<nr>.out',
+       and only the output of the failed test job is shown on the
+       terminal.  The names of the trash directories get a
+       '.stress-<nr>' suffix, and the trash directory of the failed
+       test job is renamed to end with a '.stress-failed' suffix.
+
 You can also set the GIT_TEST_INSTALLED environment variable to
 the bindir of an existing git installation to test that installation.
 You still need to have built this git sandbox, from which various
@@ -425,7 +441,8 @@ This test harness library does the following things:
  - Creates an empty test directory with an empty .git/objects database
    and chdir(2) into it.  This directory is 't/trash
    directory.$test_name_without_dotsh', with t/ subject to change by
-   the --root option documented above.
+   the --root option documented above, and a '.stress-<N>' suffix
+   appended by the --stress option.
 
  - Defines standard test helper functions for your scripts to
    use.  These functions are designed to make all scripts behave