From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 22 Mar 2018 21:24:19 +0000 (-0700)
Subject: Merge branch 'sg/doc-test-must-fail-args' into maint
X-Git-Tag: v2.16.3~10
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/68559c464a8d22d4c3cc0a258fb4317125ddd099?ds=inline;hp=-c

Merge branch 'sg/doc-test-must-fail-args' into maint

Devdoc update.

* sg/doc-test-must-fail-args:
t: document 'test_must_fail ok=<signal-name>'
---

68559c464a8d22d4c3cc0a258fb4317125ddd099
diff --combined t/README
index b3f7b449c3,c69b1eaf6d..1a1361a806
--- a/t/README
+++ b/t/README
@@@ -332,10 -332,13 +332,10 @@@ Writing Test
  -------------
  
  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)
  
@@@ -655,7 -658,7 +655,7 @@@ library for your script to use
  		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
@@@ -663,22 -666,27 +663,32 @@@
     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.
@@@ -810,18 -818,6 +820,18 @@@ use these, and "test_set_prereq" for ho
     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.
diff --combined t/test-lib-functions.sh
index 67b5994afb,26b149ac1d..8a8a9329ee
--- a/t/test-lib-functions.sh
+++ b/t/test-lib-functions.sh
@@@ -610,6 -610,14 +610,14 @@@ list_contains () 
  #
  # Writing this as "! git checkout ../outerspace" is wrong, because
  # the failure could be due to a segv.  We want a controlled failure.
+ #
+ # 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_must_fail () {
  	case "$1" in
@@@ -656,6 -664,8 +664,8 @@@
  #
  # Writing "git config --unset all.configuration || :" would be wrong,
  # because we want to notice if it fails due to segv.
+ #
+ # Accepts the same options as test_must_fail.
  
  test_might_fail () {
  	test_must_fail ok=success "$@"
@@@ -705,60 -715,6 +715,60 @@@ test_cmp_bin() 
  	cmp "$@"
  }
  
 +# Use this instead of test_cmp to compare files that contain expected and
 +# actual output from git commands that can be translated.  When running
 +# under GETTEXT_POISON this pretends that the command produced expected
 +# results.
 +test_i18ncmp () {
 +	test -n "$GETTEXT_POISON" || test_cmp "$@"
 +}
 +
 +# Use this instead of "grep expected-string actual" to see if the
 +# output from a git command that can be translated either contains an
 +# expected string, or does not contain an unwanted one.  When running
 +# under GETTEXT_POISON this pretends that the command produced expected
 +# results.
 +test_i18ngrep () {
 +	eval "last_arg=\${$#}"
 +
 +	test -f "$last_arg" ||
 +	error "bug in the test script: test_i18ngrep requires a file" \
 +	      "to read as the last parameter"
 +
 +	if test $# -lt 2 ||
 +	   { test "x!" = "x$1" && test $# -lt 3 ; }
 +	then
 +		error "bug in the test script: too few parameters to test_i18ngrep"
 +	fi
 +
 +	if test -n "$GETTEXT_POISON"
 +	then
 +		# pretend success
 +		return 0
 +	fi
 +
 +	if test "x!" = "x$1"
 +	then
 +		shift
 +		! grep "$@" && return 0
 +
 +		echo >&2 "error: '! grep $@' did find a match in:"
 +	else
 +		grep "$@" && return 0
 +
 +		echo >&2 "error: 'grep $@' didn't find a match in:"
 +	fi
 +
 +	if test -s "$last_arg"
 +	then
 +		cat >&2 "$last_arg"
 +	else
 +		echo >&2 "<File '$last_arg' is empty>"
 +	fi
 +
 +	return 1
 +}
 +
  # Call any command "$@" but be more verbose about its
  # failure. This is handy for commands like "test" which do
  # not output anything when they fail.
@@@ -1074,37 -1030,3 +1084,37 @@@ nongit () 
  		"$@"
  	)
  }
 +
 +# convert stdin to pktline representation; note that empty input becomes an
 +# empty packet, not a flush packet (for that you can just print 0000 yourself).
 +packetize() {
 +	cat >packetize.tmp &&
 +	len=$(wc -c <packetize.tmp) &&
 +	printf '%04x%s' "$(($len + 4))" &&
 +	cat packetize.tmp &&
 +	rm -f packetize.tmp
 +}
 +
 +# Parse the input as a series of pktlines, writing the result to stdout.
 +# Sideband markers are removed automatically, and the output is routed to
 +# stderr if appropriate.
 +#
 +# NUL bytes are converted to "\\0" for ease of parsing with text tools.
 +depacketize () {
 +	perl -e '
 +		while (read(STDIN, $len, 4) == 4) {
 +			if ($len eq "0000") {
 +				print "FLUSH\n";
 +			} else {
 +				read(STDIN, $buf, hex($len) - 4);
 +				$buf =~ s/\0/\\0/g;
 +				if ($buf =~ s/^[\x2\x3]//) {
 +					print STDERR $buf;
 +				} else {
 +					$buf =~ s/^\x1//;
 +					print $buf;
 +				}
 +			}
 +		}
 +	'
 +}