[PATCH] t/README: document more test helpers

[Jonathan Nieder <jrnieder@gmail.com>]

There is no documentation in t/README for test_must_fail,
test_might_fail, test_cmp, or test_when_finished.

Reported-by: Jakub Narebski <jnareb@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Jakub Narebski wrote:

> Sidenote: test_when_finished, introduced by Jonathan Nieder in 3bf7886
> (test-lib: Let tests specify commands to be run at end of test,
> 2010-05-02) is not documented in t/README.

Good catch.

> Also, shouldn't it be
> named 'when_finished_test' rather than 'test_when_finished'?

It uses the test_* name to avoid a land-grab by test-lib.sh for other
namespaces.

> Currently 'test_when_finished' / 'when_finished_test' is used only in
> t0000-basic and t7509-commit.

Right, I have some ideas for using this but it is hard to find time.

Thanks for the comments.  Patch is on top of 6fd4529 (t/README:
proposed rewording..., 2010-07-05) from 'next'.

 t/README |   31 +++++++++++++++++++++++++++++++
 1 files changed, 31 insertions(+), 0 deletions(-)

diff --git a/t/README b/t/README
index 271f868..9df0ae9 100644
--- a/t/README
+++ b/t/README
@@ -448,6 +448,37 @@ library for your script to use.
 	    'Perl API' \
 	    "$PERL_PATH" "$TEST_DIRECTORY"/t9700/test.pl
 
+ - test_must_fail <git-command>
+
+   Run a git command and ensure it fails in a controlled way.  Use
+   this instead of "! <git-command>" to fail when git commands
+   segfault.
+
+ - test_might_fail <git-command>
+
+   Similar to test_must_fail, but tolerate success, too.  Use this
+   instead of "<git-command> || :" to catch failures due to segv.
+
+ - 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.
+
+ - test_when_finished <script>
+
+   Prepend <script> to a list of commands to run to clean up
+   at the end of the current test.  If some clean-up command
+   fails, the test will not pass.
+
+   Example:
+
+	test_expect_success 'branch pointing to non-commit' '
+		git rev-parse HEAD^{tree} >.git/refs/heads/invalid &&
+		test_when_finished "git update-ref -d refs/heads/invalid" &&
+		...
+	'
+
 
 Tips for Writing Tests
 ----------------------
-- 
1.7.2.rc1