-x::
Turn on shell tracing (i.e., `set -x`) during the tests
- themselves. Implies `--verbose`. Note that in non-bash shells,
- this can cause failures in some tests which redirect and test
- the output of shell functions. Use with caution.
+ themselves. Implies `--verbose`.
+ Ignored in test scripts that set the variable 'test_untraceable'
+ to a non-empty value, unless it's run with a Bash version
+ supporting BASH_XTRACEFD, i.e. v4.1 or later.
-d::
--debug::
$ sh ./t9200-git-cvsexport-commit.sh --run='-3 21'
-As noted above, the test set is built going though items left to
-right, so this:
+As noted above, the test set is built by going through the items
+from left to right, so this:
$ sh ./t9200-git-cvsexport-commit.sh --run='1-4 !3'
-will run tests 1, 2, and 4. Items that comes later have higher
+will run tests 1, 2, and 4. Items that come later have higher
precedence. It means that this:
$ sh ./t9200-git-cvsexport-commit.sh --run='!3 1-4'
everything up to a certain test.
+Running tests with special setups
+---------------------------------
+
+The whole test suite could be run to test some special features
+that cannot be easily covered by a few specific test cases. These
+could be enabled by running the test suite with correct GIT_TEST_
+environment set.
+
+GIT_TEST_SPLIT_INDEX=<boolean> forces split-index mode on the whole
+test suite. Accept any boolean values that are accepted by git-config.
+
+GIT_TEST_FULL_IN_PACK_ARRAY=<boolean> exercises the uncommon
+pack-objects code path where there are more than 1024 packs even if
+the actual number of packs in repository is below this limit. Accept
+any boolean values that are accepted by git-config.
+
+GIT_TEST_OE_SIZE=<n> exercises the uncommon pack-objects code path
+where we do not cache object size in memory and read it from existing
+packs on demand. This normally only happens when the object size is
+over 2GB. This variable forces the code path on any object larger than
+<n> bytes.
+
+GIT_TEST_OE_DELTA_SIZE=<n> exercises the uncomon pack-objects code
+path where deltas larger than this limit require extra memory
+allocation for bookkeeping.
+
Naming Tests
------------
-------------
The test script is written as a shell script. It should start
-with the standard "#!/bin/sh" with copyright notices, and an
+with the standard "#!/bin/sh", and an
assignment to variable 'test_description', like this:
#!/bin/sh
- #
- # Copyright (c) 2005 Junio C Hamano
- #
test_description='xxx test (option --frotz)
causing the next test to start in an unexpected directory. Do so
inside a subshell if necessary.
+ - save and verify the standard error of compound commands, i.e. group
+ commands, subshells, and shell functions (except test helper
+ functions like 'test_must_fail') like this:
+
+ ( cd dir && git cmd ) 2>error &&
+ test_cmp expect error
+
+ When running the test with '-x' tracing, then the trace of commands
+ executed in the compound command will be included in standard error
+ as well, quite possibly throwing off the subsequent checks examining
+ the output. Instead, save only the relevant git command's standard
+ error:
+
+ ( cd dir && git cmd 2>../error ) &&
+ test_cmp expect error
+
- Break the TAP output
The raw output from your test may be interpreted by a TAP harness. TAP
their output.
You can glean some further possible issues from the TAP grammar
- (see http://search.cpan.org/perldoc?TAP::Parser::Grammar#TAP_Grammar)
+ (see https://metacpan.org/pod/TAP::Parser::Grammar#TAP-GRAMMAR)
but the best indication is to just run the tests with prove(1),
it'll complain if anything is amiss.
Keep in mind:
- - Inside <script> part, the standard output and standard error
+ - Inside the <script> part, the standard output and standard error
streams are discarded, and the test harness only reports "ok" or
"not ok" to the end user running the tests. Under --verbose, they
are shown to help debugging the tests.
- test_have_prereq <prereq>
- Check if we have a prerequisite previously set with
- test_set_prereq. The most common use of this directly is to skip
- all the tests if we don't have some essential prerequisite:
+ Check if we have a prerequisite previously set with test_set_prereq.
+ The most common way to use this explicitly (as opposed to the
+ implicit use when an argument is passed to test_expect_*) is to skip
+ all the tests at the start of the test script if we don't have some
+ essential prerequisite:
if ! test_have_prereq PERL
then
test_expect_code 1 git merge "merge msg" B master
'
- - test_must_fail <git-command>
+ - test_must_fail [<options>] <git-command>
Run a git command and ensure it fails in a controlled way. Use
this instead of "! <git-command>". When git-command dies due to a
treats it as just another expected failure, which would let such a
bug go unnoticed.
- - test_might_fail <git-command>
+ Accepts the following options:
+
+ ok=<signal-name>[,<...>]:
+ Don't treat an exit caused by the given signal as error.
+ Multiple signals can be specified as a comma separated list.
+ Currently recognized signal names are: sigpipe, success.
+ (Don't use 'success', use 'test_might_fail' instead.)
+
+ - test_might_fail [<options>] <git-command>
Similar to test_must_fail, but tolerate success, too. Use this
instead of "<git-command> || :" to catch failures due to segv.
+ Accepts the same options as test_must_fail.
+
- test_cmp <expected> <actual>
Check whether the content of the <actual> file matches the
<expected> file. This behaves like "cmp" but produces more
helpful output when the test is run with "-v" option.
+ - test_cmp_rev <expected> <actual>
+
+ Check whether the <expected> rev points to the same commit as the
+ <actual> rev.
+
- test_line_count (= | -lt | -ge | ...) <length> <file>
Check whether a file has the length it is expected to.
Test is not run by root user, and an attempt to write to an
unwritable file is expected to fail correctly.
- - LIBPCRE
+ - PCRE
- Git was compiled with USE_LIBPCRE=YesPlease. Wrap any tests
+ Git was compiled with support for PCRE. Wrap any tests
that use git-grep --perl-regexp or git-grep -P in these.
+ - LIBPCRE1
+
+ Git was compiled with PCRE v1 support via
+ USE_LIBPCRE1=YesPlease. Wrap any PCRE using tests that for some
+ reason need v1 of the PCRE library instead of v2 in these.
+
+ - LIBPCRE2
+
+ Git was compiled with PCRE v2 support via
+ USE_LIBPCRE2=YesPlease. Wrap any PCRE using tests that for some
+ reason need v2 of the PCRE library instead of v1 in these.
+
- CASE_INSENSITIVE_FS
Test is run on a case insensitive file system.
Test is run on a filesystem which converts decomposed utf-8 (nfd)
to precomposed utf-8 (nfc).
+ - PTHREADS
+
+ Git wasn't compiled with NO_PTHREADS=YesPlease.
+
Tips for Writing Tests
----------------------