![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/t/README b/t/README
index 25f7d2d2e3cf70d54f5b854ad4199c831a74ae2a..c85abaffb3b8c2142e87f6e0525fa67c6b62c1a1 100644 (file)
--- a/t/README
+++ b/t/README
--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
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'.
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.
- 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.
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.:
- 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.
'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' \
- 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>]]
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
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 whether a file has the length it is expected to.
- - test_path_is_file <file> [<diagnosis>]
- test_path_is_dir <dir> [<diagnosis>]
+ - test_path_is_file <path> [<diagnosis>]
+ test_path_is_dir <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 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
----------------------