![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/t/README b/t/README
index a1eb7c8720ad3e91f78fca6d58acd336c71171a0..c85abaffb3b8c2142e87f6e0525fa67c6b62c1a1 100644 (file)
--- a/t/README
+++ b/t/README
# Repeat until no more failures
$ prove -j 15 --state=failed,save ./t[0-9]*.sh
# Repeat until no more failures
$ prove -j 15 --state=failed,save ./t[0-9]*.sh
+You can give DEFAULT_TEST_TARGET=prove on the make command (or define it
+in config.mak) to cause "make test" to run tests under prove.
+GIT_PROVE_OPTS can be used to pass additional options, e.g.
+
+ $ make DEFAULT_TEST_TARGET=prove GIT_PROVE_OPTS='--timer --jobs 16' test
+
You can also run each test individually from command line, like this:
$ sh ./t3010-ls-files-killed-modified.sh
You can also run each test individually from command line, like this:
$ sh ./t3010-ls-files-killed-modified.sh
--debug::
This may help the person who is developing a new test.
It causes the command defined with test_debug to run.
--debug::
This may help the person who is developing a new test.
It causes the command defined with test_debug to run.
+ The "trash" directory (used to store all temporary data
+ during testing) is not deleted even if there are no
+ failed tests so that you can inspect its contents after
+ the test finished.
--immediate::
This causes the test to immediately exit upon the first
--immediate::
This causes the test to immediately exit upon the first
not see any output, this option implies --verbose. For
convenience, it also implies --tee.
not see any output, this option implies --verbose. For
convenience, it also implies --tee.
+ Note that valgrind is run with the option --leak-check=no,
+ as the git process is short-lived and some errors are not
+ interesting. In order to run a single command under the same
+ conditions manually, you should set GIT_VALGRIND to point to
+ the 't/valgrind/' directory and use the commands under
+ 't/valgrind/bin/'.
+
--tee::
In addition to printing the test output to the terminal,
write it to files named 't/test-results/$TEST_NAME.out'.
--tee::
In addition to printing the test output to the terminal,
write it to files named 't/test-results/$TEST_NAME.out'.
If you create files under t/ directory (i.e. here) that is not
the top-level test script, never name the file to match the above
pattern. The Makefile here considers all such files as the
If you create files under t/ directory (i.e. here) that is not
the top-level test script, never name the file to match the above
pattern. The Makefile here considers all such files as the
-top-level test script and tries to run all of them. A care is
+top-level test script and tries to run all of them. Care is
especially needed if you are creating a common test library
file, similar to test-lib.sh, because such a library file may
not be suitable for standalone execution.
especially needed if you are creating a common test library
file, similar to test-lib.sh, because such a library file may
not be suitable for standalone execution.
test ...
That way all of the commands in your tests will succeed or fail. If
test ...
That way all of the commands in your tests will succeed or fail. If
- you must ignore the return value of something (e.g., the return
- after unsetting a variable that was already unset is unportable) it's
- best to indicate so explicitly with a semicolon:
-
- unset HLAGH;
- git merge hla &&
- git push gh &&
- test ...
+ you must ignore the return value of something, consider using a
+ helper function (e.g. use sane_unset instead of unset, in order
+ to avoid unportable return value for unsetting a variable that was
+ already unset), or prepending the command with test_might_fail or
+ test_must_fail.
- Check the test coverage for your tests. See the "Test coverage"
below.
- Check the test coverage for your tests. See the "Test coverage"
below.
- Don't blindly follow test coverage metrics, they're a good way to
- spot if you've missed something. If a new function you added
- doesn't have any coverage you're probably doing something wrong,
+ Don't blindly follow test coverage metrics; if a new function you added
+ doesn't have any coverage, then you're probably doing something wrong,
but having 100% coverage doesn't necessarily mean that you tested
everything.
Tests that are likely to smoke out future regressions are better
than tests that just inflate the coverage metrics.
but having 100% coverage doesn't necessarily mean that you tested
everything.
Tests that are likely to smoke out future regressions are better
than tests that just inflate the coverage metrics.
+ - When a test checks for an absolute path that a git command generated,
+ construct the expected value using $(pwd) rather than $PWD,
+ $TEST_DIRECTORY, or $TRASH_DIRECTORY. It makes a difference on
+ Windows, where the shell (MSYS bash) mangles absolute path names.
+ For details, see the commit message of 4114156ae9.
+
Don't:
- exit() within a <script> part.
Don't:
- exit() within a <script> part.
Skipping tests
--------------
Skipping tests
--------------
-If you need to skip tests you should do so be using the three-arg form
+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.:
of the test_* functions (see the "Test harness library" section
below), e.g.:
- test_expect_success [<prereq>] <message> <script>
- test_expect_success [<prereq>] <message> <script>
- Usually takes two strings as parameter, and evaluates the
+ Usually takes two strings as parameters, and evaluates the
<script>. If it yields success, test is considered
successful. <message> should state what it is testing.
<script>. If it yields success, test is considered
successful. <message> should state what it is testing.
'tree=$(git-write-tree)'
If you supply three parameters the first will be taken to be a
'tree=$(git-write-tree)'
If you supply three parameters the first will be taken to be a
- prerequisite, see the test_set_prereq and test_have_prereq
+ prerequisite; see the test_set_prereq and test_have_prereq
documentation below:
test_expect_success TTY 'git --paginate rev-list uses a pager' \
documentation below:
test_expect_success TTY 'git --paginate rev-list uses a pager' \
Like test_expect_success this function can optionally use a three
argument invocation with a prerequisite as the first argument.
Like test_expect_success this function can optionally use a three
argument invocation with a prerequisite as the first argument.
- - test_expect_code [<prereq>] <code> <message> <script>
-
- Analogous to test_expect_success, but pass the test if it exits
- with a given exit <code>
-
- test_expect_code 1 'Merge with d/f conflicts' 'git merge "merge msg" B master'
-
- test_debug <script>
This takes a single argument, <script>, and evaluates it only
- test_debug <script>
This takes a single argument, <script>, and evaluates it only
- test_tick
Make commit and tag names consistent by setting the author and
- test_tick
Make commit and tag names consistent by setting the author and
- committer times to defined stated. Subsequent calls will
+ committer times to defined state. Subsequent calls will
advance the times by a fixed amount.
- test_commit <message> [<filename> [<contents>]]
advance the times by a fixed amount.
- test_commit <message> [<filename> [<contents>]]
Merges the given rev using the given message. Like test_commit,
creates a tag and calls test_tick before committing.
Merges the given rev using the given message. Like test_commit,
creates a tag and calls test_tick before committing.
- - test_set_prereq SOME_PREREQ
+ - test_set_prereq <prereq>
Set a test prerequisite to be used later with test_have_prereq. The
test-lib will set some prerequisites for you, see the
Set a test prerequisite to be used later with test_have_prereq. The
test-lib will set some prerequisites for you, see the
test_have_prereq directly, or the three argument invocation of
test_expect_success and test_expect_failure.
test_have_prereq directly, or the three argument invocation of
test_expect_success and test_expect_failure.
- - test_have_prereq SOME PREREQ
+ - 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
Check if we have a prerequisite previously set with
test_set_prereq. The most common use of this directly is to skip
'Perl API' \
"$PERL_PATH" "$TEST_DIRECTORY"/t9700/test.pl
'Perl API' \
"$PERL_PATH" "$TEST_DIRECTORY"/t9700/test.pl
+ - test_expect_code <exit-code> <command>
+
+ Run a command and ensure that it exits with the given exit code.
+ For example:
+
+ test_expect_success 'Merge with d/f conflicts' '
+ test_expect_code 1 git merge "merge msg" B master
+ '
+
- test_must_fail <git-command>
Run a git command and ensure it fails in a controlled way. Use
- test_must_fail <git-command>
Run a git command and ensure it fails in a controlled way. Use
<expected> file. This behaves like "cmp" but produces more
helpful output when the test is run with "-v" option.
<expected> file. This behaves like "cmp" but produces more
helpful output when the test is run with "-v" option.
- - test_path_is_file <file> [<diagnosis>]
- test_path_is_dir <dir> [<diagnosis>]
+ - test_line_count (= | -lt | -ge | ...) <length> <file>
+
+ Check whether a file has the length it is expected to.
+
+ - test_path_is_file <path> [<diagnosis>]
+ test_path_is_dir <path> [<diagnosis>]
test_path_is_missing <path> [<diagnosis>]
test_path_is_missing <path> [<diagnosis>]
- Check whether a file/directory exists or doesn't. <diagnosis> will
- be displayed if the test fails.
+ Check if the named path is a file, if the named path is a
+ directory, or if the named path does not exist, respectively,
+ and fail otherwise, showing the <diagnosis> text.
- test_when_finished <script>
- test_when_finished <script>
Test is not run by root user, and an attempt to write to an
unwritable file is expected to fail correctly.
Test is not run by root user, and an attempt to write to an
unwritable file is expected to fail correctly.
+ - LIBPCRE
+
+ Git was compiled with USE_LIBPCRE=YesPlease. Wrap any tests
+ that use git-grep --perl-regexp or git-grep -P in these.
+
Tips for Writing Tests
----------------------
Tips for Writing Tests
----------------------