t/test-lib-functions.sh

   1 # Test function library from Git with modifications.
   2 #
   3 # Modifications Copyright (C) 2016,2017 Kyle J. McKay.  All rights reserved.
   4 # Modifications made:
   5 #
   6 #  * Many "GIT_..." variables removed -- some were kept as TESTLIB_..." instead
   7 #    (Except "GIT_PATH" is new and is the full path to a "git" executable)
   8 #
   9 #  * IMPORTANT: test-lib-functions.sh SHOULD NOT EXECUTE ANY CODE!  A new
  10 #    function "test_lib_functions_init" has been added that will be called
  11 #    and MUST contain any lines of code to be executed.  This will ALWAYS
  12 #    be the LAST function defined in this file for easy locatability.
  13 #
  14 #  * Added test_tolerate_failure and $LINENO support unctions
  15 #
  16 #  * Anything related to valgrind or perf has been stripped out
  17 #
  18 #  * Many other minor changes and efficiencies
  19 #
  20 # Library of functions shared by all tests scripts, included by
  21 # test-lib.sh.
  22 #
  23 # Copyright (C) 2005 Junio C Hamano
  24 #
  25 # This program is free software: you can redistribute it and/or modify
  26 # it under the terms of the GNU General Public License as published by
  27 # the Free Software Foundation, either version 2 of the License, or
  28 # (at your option) any later version.
  29 #
  30 # This program is distributed in the hope that it will be useful,
  31 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  32 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  33 # GNU General Public License for more details.
  34 #
  35 # You should have received a copy of the GNU General Public License
  36 # along with this program.  If not, see http://www.gnu.org/licenses/ .
  37
  38 #
  39 ## IMPORTANT:  THIS FILE MUST NOT CONTAIN ANYTHING OTHER THAN FUNCTION
  40 ##             DEFINITION!!!  INITIALIZATION GOES IN THE LAST FUNCTION
  41 ##             DEFINED IN THIS FILE "test_lib_functions_init" IF REQUIRED!
  42 #
  43
  44 # The semantics of the editor variables are that of invoking
  45 # sh -c "$EDITOR \"$@\"" files ...
  46 #
  47 # If our trash directory contains shell metacharacters, they will be
  48 # interpreted if we just set $EDITOR directly, so do a little dance with
  49 # environment variables to work around this.
  50 #
  51 # In particular, quoting isn't enough, as the path may contain the same quote
  52 # that we're using.
  53 test_set_editor() {
  54         FAKE_EDITOR="$1"
  55         export FAKE_EDITOR
  56         EDITOR='"$FAKE_EDITOR"'
  57         export EDITOR
  58 }
  59
  60 test_decode_color() {
  61         awk '
  62                 function name(n) {
  63                         if (n == 0) return "RESET";
  64                         if (n == 1) return "BOLD";
  65                         if (n == 30) return "BLACK";
  66                         if (n == 31) return "RED";
  67                         if (n == 32) return "GREEN";
  68                         if (n == 33) return "YELLOW";
  69                         if (n == 34) return "BLUE";
  70                         if (n == 35) return "MAGENTA";
  71                         if (n == 36) return "CYAN";
  72                         if (n == 37) return "WHITE";
  73                         if (n == 40) return "BLACK";
  74                         if (n == 41) return "BRED";
  75                         if (n == 42) return "BGREEN";
  76                         if (n == 43) return "BYELLOW";
  77                         if (n == 44) return "BBLUE";
  78                         if (n == 45) return "BMAGENTA";
  79                         if (n == 46) return "BCYAN";
  80                         if (n == 47) return "BWHITE";
  81                 }
  82                 {
  83                         while (match($0, /\033\[[0-9;]*m/) != 0) {
  84                                 printf "%s<", substr($0, 1, RSTART-1);
  85                                 codes = substr($0, RSTART+2, RLENGTH-3);
  86                                 if (length(codes) == 0)
  87                                         printf "%s", name(0)
  88                                 else {
  89                                         n = split(codes, ary, ";");
  90                                         sep = "";
  91                                         for (i = 1; i <= n; i++) {
  92                                                 printf "%s%s", sep, name(ary[i]);
  93                                                 sep = ";"
  94                                         }
  95                                 }
  96                                 printf ">";
  97                                 $0 = substr($0, RSTART + RLENGTH, length($0) - RSTART - RLENGTH + 1);
  98                         }
  99                         print
 100                 }
 101         '
 102 }
 103
 104 lf_to_nul() {
 105         perl -pe 'y/\012/\000/'
 106 }
 107
 108 nul_to_q() {
 109         perl -pe 'y/\000/Q/'
 110 }
 111
 112 q_to_nul() {
 113         perl -pe 'y/Q/\000/'
 114 }
 115
 116 q_to_cr() {
 117         tr Q '\015'
 118 }
 119
 120 q_to_tab() {
 121         tr Q '\011'
 122 }
 123
 124 qz_to_tab_space() {
 125         tr QZ '\011\040'
 126 }
 127
 128 append_cr() {
 129         sed -e 's/$/Q/' | tr Q '\015'
 130 }
 131
 132 remove_cr() {
 133         tr '\015' Q | sed -e 's/Q$//'
 134 }
 135
 136 # In some bourne shell implementations, the "unset" builtin returns
 137 # nonzero status when a variable to be unset was not set in the first
 138 # place.
 139 #
 140 # Use sane_unset when that should not be considered an error.
 141
 142 sane_unset() {
 143         "unset" "$@" || :
 144         return 0
 145 }
 146
 147 test_tick() {
 148         if test -z "${test_tick+set}"
 149         then
 150                 test_tick=1112911993
 151         else
 152                 test_tick=$(($test_tick + 60))
 153         fi
 154         GIT_COMMITTER_DATE="$test_tick -0700"
 155         GIT_AUTHOR_DATE="$test_tick -0700"
 156         export GIT_COMMITTER_DATE GIT_AUTHOR_DATE
 157 }
 158
 159 # Stop execution and start a shell. This is useful for debugging tests and
 160 # only makes sense together with "-v".
 161 #
 162 # Be sure to remove all invocations of this command before submitting.
 163
 164 test_pause() {
 165         if test "$verbose" = t; then
 166                 "$SHELL_PATH" <&6 >&3 2>&4
 167         else
 168                 error >&5 "test_pause requires --verbose"
 169         fi
 170 }
 171
 172 # Call test_commit with the arguments "<message> [<file> [<contents> [<tag>]]]"
 173 #
 174 # This will commit a file with the given contents and the given commit
 175 # message, and tag the resulting commit with the given tag name.
 176 #
 177 # <file>, <contents>, and <tag> all default to <message>.
 178
 179 test_commit() {
 180         notick= &&
 181         signoff= &&
 182         while test $# != 0
 183         do
 184                 case "$1" in
 185                 --notick)
 186                         notick=yes
 187                         ;;
 188                 --signoff)
 189                         signoff="$1"
 190                         ;;
 191                 *)
 192                         break
 193                         ;;
 194                 esac
 195                 shift
 196         done &&
 197         file=${2:-"$1.t"} &&
 198         echo "${3-$1}" > "$file" &&
 199         git add "$file" &&
 200         if test -z "$notick"
 201         then
 202                 test_tick
 203         fi &&
 204         git commit $signoff -m "$1" &&
 205         git tag "${4:-$1}"
 206 }
 207
 208 # Call test_merge with the arguments "<message> <commit>", where <commit>
 209 # can be a tag pointing to the commit-to-merge.
 210
 211 test_merge() {
 212         test_tick &&
 213         git merge -m "$1" "$2" &&
 214         git tag "$1"
 215 }
 216
 217 # This function helps systems where core.filemode=false is set.
 218 # Use it instead of plain 'chmod +x' to set or unset the executable bit
 219 # of a file in the working directory and add it to the index.
 220
 221 test_chmod() {
 222         chmod "$@" &&
 223         git update-index --add "--chmod=$@"
 224 }
 225
 226 # Unset a configuration variable, but don't fail if it doesn't exist.
 227 test_unconfig() {
 228         config_dir=
 229         if test "$1" = -C
 230         then
 231                 shift
 232                 config_dir=$1
 233                 shift
 234         fi
 235         eval git ${config_dir:+-C \"\$config_dir\"} config --unset-all '"$@"' #"#"
 236         config_status=$?
 237         case "$config_status" in
 238         5) # ok, nothing to unset
 239                 config_status=0
 240                 ;;
 241         esac
 242         return $config_status
 243 }
 244
 245 # Set git config, automatically unsetting it after the test is over.
 246 test_config() {
 247         config_dir=
 248         if test "$1" = -C
 249         then
 250                 shift
 251                 config_dir=$1
 252                 shift
 253         fi
 254         test_when_finished "test_unconfig ${config_dir:+-C '$config_dir'} '$1'" &&
 255         eval git ${config_dir:+-C \"\$config_dir\"} config '"$@"' #"#"
 256 }
 257
 258 test_config_global() {
 259         test_when_finished "test_unconfig --global '$1'" &&
 260         git config --global "$@"
 261 }
 262
 263 write_script() {
 264         {
 265                 echo "#!${2-"$SHELL_PATH"}" &&
 266                 cat
 267         } >"$1" &&
 268         chmod +x "$1"
 269 }
 270
 271 # Use test_set_prereq to tell that a particular prerequisite is available.
 272 # The prerequisite can later be checked for in two ways:
 273 #
 274 # - Explicitly using test_have_prereq.
 275 #
 276 # - Implicitly by specifying the prerequisite tag in the calls to
 277 #   test_expect_{success,failure,code}.
 278 #
 279 # The single parameter is the prerequisite tag (a simple word, in all
 280 # capital letters by convention).
 281
 282 test_set_prereq() {
 283         satisfied_prereq="$satisfied_prereq$1 "
 284 }
 285
 286 # Usage: test_lazy_prereq PREREQ 'script'
 287 test_lazy_prereq() {
 288         lazily_testable_prereq="$lazily_testable_prereq$1 "
 289         eval test_prereq_lazily_$1=\$2
 290 }
 291
 292 test_run_lazy_prereq_() {
 293         script='
 294 mkdir -p "$TRASH_DIRECTORY/prereq-test-dir" &&
 295 (
 296         cd "$TRASH_DIRECTORY/prereq-test-dir" &&'"$2"'
 297 )'
 298         say >&3 "checking prerequisite: $1"
 299         say >&3 "$script"
 300         test_eval_ "$script"
 301         eval_ret=$?
 302         rm -rf "$TRASH_DIRECTORY/prereq-test-dir"
 303         if test "$eval_ret" = 0; then
 304                 say >&3 "prerequisite $1 ok"
 305         else
 306                 say >&3 "prerequisite $1 not satisfied"
 307         fi
 308         return $eval_ret
 309 }
 310
 311 test_have_prereq() {
 312         # prerequisites can be concatenated with ','
 313         save_IFS=$IFS
 314         IFS=,
 315         set -- $*
 316         IFS=$save_IFS
 317
 318         total_prereq=0
 319         ok_prereq=0
 320         missing_prereq=
 321
 322         for prerequisite
 323         do
 324                 case "$prerequisite" in
 325                 !*)
 326                         negative_prereq=t
 327                         prerequisite=${prerequisite#!}
 328                         ;;
 329                 *)
 330                         negative_prereq=
 331                 esac
 332
 333                 case " $lazily_tested_prereq " in
 334                 *" $prerequisite "*)
 335                         ;;
 336                 *)
 337                         case " $lazily_testable_prereq " in
 338                         *" $prerequisite "*)
 339                                 eval "script=\$test_prereq_lazily_$prerequisite" &&
 340                                 if test_run_lazy_prereq_ "$prerequisite" "$script"
 341                                 then
 342                                         test_set_prereq $prerequisite
 343                                 fi
 344                                 lazily_tested_prereq="$lazily_tested_prereq$prerequisite "
 345                         esac
 346                         ;;
 347                 esac
 348
 349                 total_prereq=$(($total_prereq + 1))
 350                 satisfied_this_prereq=
 351                 if test "$prerequisite" = "LASTOK"
 352                 then
 353                         if test -n "$test_last_subtest_ok"
 354                         then
 355                                 satisfied_this_prereq=t
 356                         fi
 357                 else
 358                         case "$satisfied_prereq" in
 359                         *" $prerequisite "*)
 360                                 satisfied_this_prereq=t
 361                         esac
 362                 fi
 363
 364                 case "$satisfied_this_prereq,$negative_prereq" in
 365                 t,|,t)
 366                         ok_prereq=$(($ok_prereq + 1))
 367                         ;;
 368                 *)
 369                         # Keep a list of missing prerequisites; restore
 370                         # the negative marker if necessary.
 371                         prerequisite=${negative_prereq:+!}$prerequisite
 372                         if test -z "$missing_prereq"
 373                         then
 374                                 missing_prereq=$prerequisite
 375                         else
 376                                 missing_prereq="$prerequisite,$missing_prereq"
 377                         fi
 378                 esac
 379         done
 380
 381         test $total_prereq = $ok_prereq
 382 }
 383
 384 test_declared_prereq() {
 385         case ",$test_prereq," in
 386         *,$1,*)
 387                 return 0
 388                 ;;
 389         esac
 390         return 1
 391 }
 392
 393 test_verify_prereq() {
 394         test -z "$test_prereq" ||
 395         test "x$test_prereq" = "x${test_prereq#*[!A-Z0-9_,!]}" ||
 396         error "bug in the test script: '$test_prereq' does not look like a prereq"
 397 }
 398
 399 test_expect_failure_lno() {
 400         callerlno="$1"
 401         shift
 402         test_start_
 403         test "$#" = 3 && { test_prereq=$1; shift; } || test_prereq=
 404         test "$#" = 2 ||
 405         error "bug in the test script: not 2 or 3 parameters to test-expect-failure"
 406         test_get_ "$2"
 407         set -- "$1" "$test_script_"
 408         test_verify_prereq
 409         export test_prereq
 410         if ! test_skip "$@"
 411         then
 412                 say >&3 "checking known breakage: $2"
 413                 if test_run_ "$2" expecting_failure
 414                 then
 415                         test_known_broken_ok_ "$1"
 416                         test_last_subtest_ok=1
 417                 else
 418                         test_known_broken_failure_ "$1"
 419                         test_last_subtest_ok=
 420                 fi
 421         fi
 422         test_finish_
 423         unset callerlno
 424 }
 425 test_expect_failure() {
 426         test_expect_failure_lno "" "$@"
 427 }
 428 alias test_expect_failure='test_expect_failure_lno "$LINENO"' >/dev/null 2>&1 || :
 429
 430 if test -n "$TESTLIB_NO_TOLERATE"; then
 431 test_tolerate_failure_lno() { test_expect_success_lno "$@"; }
 432 else
 433 test_tolerate_failure_lno() {
 434         callerlno="$1"
 435         shift
 436         test_start_
 437         test "$#" = 3 && { test_prereq=$1; shift; } || test_prereq=
 438         test "$#" = 2 ||
 439         error "bug in the test script: not 2 or 3 parameters to test-tolerate-failure"
 440         test_get_ "$2"
 441         set -- "$1" "$test_script_"
 442         test_verify_prereq
 443         export test_prereq
 444         if ! test_skip "$@"
 445         then
 446                 say >&3 "checking possible breakage: $2"
 447                 if test_run_ "$2" tolerating_failure
 448                 then
 449                         test_possibly_broken_ok_ "$1"
 450                         test_last_subtest_ok=1
 451                 else
 452                         test_possibly_broken_failure_ "$1"
 453                         test_last_subtest_ok=
 454                 fi
 455         fi
 456         test_finish_
 457         unset callerlno
 458 }
 459 fi
 460 test_tolerate_failure() {
 461         test_tolerate_failure_lno "" "$@"
 462 }
 463 alias test_tolerate_failure='test_tolerate_failure_lno "$LINENO"' >/dev/null 2>&1 || :
 464
 465 test_expect_success_lno() {
 466         callerlno="$1"
 467         shift
 468         test_start_
 469         test "$#" = 3 && { test_prereq=$1; shift; } || test_prereq=
 470         test "$#" = 2 ||
 471         error "bug in the test script: not 2 or 3 parameters to test-expect-success"
 472         test_get_ "$2"
 473         set -- "$1" "$test_script_"
 474         test_verify_prereq
 475         export test_prereq
 476         if ! test_skip "$@"
 477         then
 478                 say >&3 "expecting success: $2"
 479                 if test_run_ "$2"
 480                 then
 481                         test_ok_ "$1"
 482                         test_last_subtest_ok=1
 483                 else
 484                         test_failure_ "$callerlno" "$@"
 485                         test_last_subtest_ok=
 486                 fi
 487         fi
 488         test_finish_
 489         unset callerlno
 490 }
 491 test_expect_success() {
 492         test_expect_success_lno "" "$@"
 493 }
 494 alias test_expect_success='test_expect_success_lno "$LINENO"' >/dev/null 2>&1 || :
 495
 496 # test_external runs external test scripts that provide continuous
 497 # test output about their progress, and succeeds/fails on
 498 # zero/non-zero exit code.  It outputs the test output on stdout even
 499 # in non-verbose mode, and announces the external script with "# run
 500 # <n>: ..." before running it.  When providing relative paths, keep in
 501 # mind that all scripts run in "trash directory".
 502 # Usage: test_external description command arguments...
 503 # Example: test_external 'Perl API' perl ../path/to/test.pl
 504 test_external_lno() {
 505         callerlno="$1"
 506         shift
 507         test "$#" = 4 && { test_prereq=$1; shift; } || test_prereq=
 508         test "$#" = 3 ||
 509         error >&5 "bug in the test script: not 3 or 4 parameters to test_external"
 510         descr="$1"
 511         shift
 512         test_verify_prereq
 513         export test_prereq
 514         test_external_skipped=1
 515         if ! test_skip "$descr" "$@"
 516         then
 517                 # Announce the script to reduce confusion about the
 518                 # test output that follows.
 519                 say_color "" "# run $test_count: $descr ($*)"
 520                 # Export TEST_DIRECTORY, TRASH_DIRECTORY and TESTLIB_TEST_LONG
 521                 # to be able to use them in script
 522                 export TEST_DIRECTORY TRASH_DIRECTORY TESTLIB_TEST_LONG
 523                 # Run command; redirect its stderr to &4 as in
 524                 # test_run_, but keep its stdout on our stdout even in
 525                 # non-verbose mode.
 526                 "$@" 2>&4
 527                 if test "$?" = 0
 528                 then
 529                         if test $test_external_has_tap -eq 0; then
 530                                 test_ok_ "$descr"
 531                         else
 532                                 say_color "" "# test_external test $descr was ok"
 533                                 test_success=$(($test_success + 1))
 534                         fi
 535                         test_last_subtest_ok=1
 536                 else
 537                         if test $test_external_has_tap -eq 0; then
 538                                 test_failure_ "$callerlno" "$descr" "$@"
 539                         else
 540                                 say_color error "# test_external test $descr failed: $@"
 541                                 test_failure=$(($test_failure + 1))
 542                         fi
 543                         test_last_subtest_ok=
 544                 fi
 545                 test_external_skipped=
 546         fi
 547         unset callerlno
 548 }
 549 test_external() {
 550         test_external_lno "" "$@"
 551 }
 552 alias test_external='test_external_lno "$LINENO"' >/dev/null 2>&1 || :
 553
 554 # Like test_external, but in addition tests that the command generated
 555 # no output on stderr.
 556 test_external_without_stderr_lno() {
 557         callerlno="$1"
 558         shift
 559         # The temporary file has no (and must have no) security
 560         # implications.
 561         tmp=${TMPDIR:-/tmp}
 562         stderr="$tmp/git-external-stderr.$$.tmp"
 563         test_external_lno "$callerlno" "$@" 4> "$stderr"
 564         test -f "$stderr" || error "Internal error: $stderr disappeared."
 565         descr="no stderr: $1"
 566         shift
 567         say >&3 "# expecting no stderr from previous command"
 568         if test -n "$test_external_skipped" || test ! -s "$stderr"
 569         then
 570                 rm "$stderr"
 571
 572                 if test $test_external_has_tap -eq 0; then
 573                         test_ok_ "$descr"
 574                 else
 575                         say_color "" "# test_external_without_stderr test $descr was ok"
 576                         test_success=$(($test_success + 1))
 577                 fi
 578         else
 579                 test_last_subtest_ok=
 580                 if test "$verbose" = t
 581                 then
 582                         output=$(echo; echo "# Stderr is:"; cat "$stderr")
 583                 else
 584                         output=
 585                 fi
 586                 # rm first in case test_failure exits.
 587                 rm "$stderr"
 588                 if test $test_external_has_tap -eq 0; then
 589                         test_failure_ "$callerlno" "$descr" "$@" "$output"
 590                 else
 591                         say_color error "# test_external_without_stderr test $descr failed: $@: $output"
 592                         test_failure=$(($test_failure + 1))
 593                 fi
 594         fi
 595         unset callerlno
 596 }
 597 test_external_without_stderr() {
 598         test_external_without_stderr_lno "" "$@"
 599 }
 600 alias test_external_without_stderr='test_external_without_stderr_lno "$LINENO"' >/dev/null 2>&1 || :
 601
 602 # debugging-friendly alternatives to "test [-f|-d|-e]"
 603 # The commands test the existence or non-existence of $1. $2 can be
 604 # given to provide a more precise diagnosis.
 605 test_path_is_file() {
 606         if ! test -f "$1"
 607         then
 608                 echo "File $1 doesn't exist. $2"
 609                 false
 610         fi
 611 }
 612
 613 test_path_is_dir() {
 614         if ! test -d "$1"
 615         then
 616                 echo "Directory $1 doesn't exist. $2"
 617                 false
 618         fi
 619 }
 620
 621 # Check if the directory exists and is empty as expected, barf otherwise.
 622 test_dir_is_empty() {
 623         test_path_is_dir "$1" &&
 624         if test -n "$(ls -a1 "$1" | grep -E -v '^\.\.?$')"
 625         then
 626                 echo "Directory '$1' is not empty, it contains:"
 627                 ls -la "$1"
 628                 return 1
 629         fi
 630 }
 631
 632 test_path_is_missing() {
 633         if test -e "$1"
 634         then
 635                 echo "Path exists:"
 636                 ls -ld "$1"
 637                 if test $# -ge 1
 638                 then
 639                         echo "$*"
 640                 fi
 641                 false
 642         fi
 643 }
 644
 645 # test_line_count checks that a file has the number of lines it
 646 # ought to. For example:
 647 #
 648 #       test_expect_success 'produce exactly one line of output' '
 649 #               do something >output &&
 650 #               test_line_count = 1 output
 651 #       '
 652 #
 653 # is like "test $(wc -l <output) = 1" except that it passes the
 654 # output through when the number of lines is wrong.
 655
 656 test_line_count() {
 657         if test $# != 3
 658         then
 659                 error "bug in the test script: not 3 parameters to test_line_count"
 660         elif ! test $(( $(wc -l <"$3") )) "$1" "$2"
 661         then
 662                 echo "test_line_count: line count for $3 !$1 $2"
 663                 cat "$3"
 664                 return 1
 665         fi
 666 }
 667
 668 # Returns success if a comma separated string of keywords ($1) contains a
 669 # given keyword ($2).
 670 # Examples:
 671 # `list_contains "foo,bar" bar` returns 0
 672 # `list_contains "foo" bar` returns 1
 673
 674 list_contains() {
 675         case ",$1," in
 676         *,$2,*)
 677                 return 0
 678                 ;;
 679         esac
 680         return 1
 681 }
 682
 683 # This is not among top-level (test_expect_success | test_expect_failure)
 684 # but is a prefix that can be used in the test script, like:
 685 #
 686 #       test_expect_success 'complain and die' '
 687 #           do something &&
 688 #           do something else &&
 689 #           test_must_fail git checkout ../outerspace
 690 #       '
 691 #
 692 # Writing this as "! git checkout ../outerspace" is wrong, because
 693 # the failure could be due to a segv.  We want a controlled failure.
 694
 695 test_must_fail() {
 696         case "$1" in
 697         ok=*)
 698                 _test_ok=${1#ok=}
 699                 shift
 700                 ;;
 701         *)
 702                 _test_ok=
 703                 ;;
 704         esac
 705         exit_code=0
 706         "$@" ||
 707         exit_code=$?
 708         if test $exit_code -eq 0 && ! list_contains "$_test_ok" success
 709         then
 710                 echo >&2 "test_must_fail: command succeeded: $*"
 711                 return 1
 712         elif test_match_signal 13 $exit_code && list_contains "$_test_ok" sigpipe
 713         then
 714                 return 0
 715         elif test $exit_code -gt 129 && test $exit_code -le 192
 716         then
 717                 echo >&2 "test_must_fail: died by signal $(($exit_code - 128)): $*"
 718                 return 1
 719         elif test $exit_code -eq 127
 720         then
 721                 echo >&2 "test_must_fail: command not found: $*"
 722                 return 1
 723         elif test $exit_code -eq 126
 724         then
 725                 echo >&2 "test_must_fail: command not executable: $*"
 726                 return 1
 727         fi
 728         return 0
 729 }
 730
 731 # Similar to test_must_fail, but tolerates success, too.  This is
 732 # meant to be used in contexts like:
 733 #
 734 #       test_expect_success 'some command works without configuration' '
 735 #               test_might_fail git config --unset all.configuration &&
 736 #               do something
 737 #       '
 738 #
 739 # Writing "git config --unset all.configuration || :" would be wrong,
 740 # because we want to notice if it fails due to segv.
 741
 742 test_might_fail() {
 743         test_must_fail ok=success "$@"
 744 }
 745
 746 # Similar to test_must_fail and test_might_fail, but check that a
 747 # given command exited with a given exit code. Meant to be used as:
 748 #
 749 #       test_expect_success 'Merge with d/f conflicts' '
 750 #               test_expect_code 1 git merge "merge msg" B master
 751 #       '
 752
 753 test_expect_code() {
 754         want_code=$1
 755         shift
 756         "$@"
 757         exit_code=$?
 758         if test $exit_code = $want_code
 759         then
 760                 return 0
 761         fi
 762
 763         echo >&2 "test_expect_code: command exited with $exit_code, we wanted $want_code $*"
 764         return 1
 765 }
 766
 767 # test_cmp is a helper function to compare actual and expected output.
 768 # You can use it like:
 769 #
 770 #       test_expect_success 'foo works' '
 771 #               echo expected >expected &&
 772 #               foo >actual &&
 773 #               test_cmp expected actual
 774 #       '
 775 #
 776 # This could be written as either "cmp" or "diff -u", but:
 777 # - cmp's output is not nearly as easy to read as diff -u
 778 # - not all diff versions understand "-u"
 779
 780 test_cmp() {
 781         $TESTLIB_TEST_CMP "$@"
 782 }
 783
 784 # test_cmp_bin - helper to compare binary files
 785
 786 test_cmp_bin() {
 787         cmp "$@"
 788 }
 789
 790 # Call any command "$@" but be more verbose about its
 791 # failure. This is handy for commands like "test" which do
 792 # not output anything when they fail.
 793 verbose() {
 794         "$@" && return 0
 795         echo >&2 "command failed: $(git rev-parse --sq-quote "$@")"
 796         return 1
 797 }
 798
 799 # Check if the file expected to be empty is indeed empty, and barfs
 800 # otherwise.
 801
 802 test_must_be_empty() {
 803         if test -s "$1"
 804         then
 805                 echo "'$1' is not empty, it contains:"
 806                 cat "$1"
 807                 return 1
 808         fi
 809 }
 810
 811 # Tests that its two parameters refer to the same revision
 812 test_cmp_rev() {
 813         git rev-parse --verify "$1" >expect.rev &&
 814         git rev-parse --verify "$2" >actual.rev &&
 815         test_cmp expect.rev actual.rev
 816 }
 817
 818 # Print a sequence of integers in increasing order, either with
 819 # two arguments (start and end):
 820 #
 821 #     test_seq 1 5 -- outputs 1 2 3 4 5 one line at a time
 822 #
 823 # or with one argument (end), in which case it starts counting
 824 # from 1.
 825
 826 test_seq() {
 827         case $# in
 828         1)      set 1 "$@" ;;
 829         2)      ;;
 830         *)      error "bug in the test script: not 1 or 2 parameters to test_seq" ;;
 831         esac
 832         test_seq_counter__=$1
 833         while test "$test_seq_counter__" -le "$2"
 834         do
 835                 echo "$test_seq_counter__"
 836                 test_seq_counter__=$(( $test_seq_counter__ + 1 ))
 837         done
 838 }
 839
 840 # This function can be used to schedule some commands to be run
 841 # unconditionally at the end of the test to restore sanity:
 842 #
 843 #       test_expect_success 'test core.capslock' '
 844 #               git config core.capslock true &&
 845 #               test_when_finished "git config --unset core.capslock" &&
 846 #               hello world
 847 #       '
 848 #
 849 # That would be roughly equivalent to
 850 #
 851 #       test_expect_success 'test core.capslock' '
 852 #               git config core.capslock true &&
 853 #               hello world
 854 #               git config --unset core.capslock
 855 #       '
 856 #
 857 # except that the greeting and config --unset must both succeed for
 858 # the test to pass.
 859 #
 860 # Note that under --immediate mode, no clean-up is done to help diagnose
 861 # what went wrong.
 862
 863 test_when_finished() {
 864         # We cannot detect when we are in a subshell in general, but by
 865         # doing so on Bash is better than nothing (the test will
 866         # silently pass on other shells).
 867         test -z "$linting" || return 0
 868         test "${BASH_SUBSHELL-0}" = 0 && test -z "$test_subshell_active_" ||
 869         error "bug in test script: test_when_finished does nothing in a subshell"
 870         test_cleanup="{ $*
 871                 } && (exit \"\$eval_ret\"); eval_ret=\$?; $test_cleanup"
 872 }
 873
 874 # Most tests can use the created repository, but some may need to create more.
 875 # Usage: test_create_repo <directory>
 876 test_create_repo() {
 877         test "$#" = 1 ||
 878         error "bug in the test script: not 1 parameter to test-create-repo"
 879         repo="$1"
 880         mkdir -p "$repo"
 881         (
 882                 cd "$repo" || error "Cannot setup test environment"
 883                 git init --quiet "--template=$EMPTY_DIRECTORY" >&3 2>&4 ||
 884                 error "cannot run git init -- have you built things yet?"
 885                 ! [ -e .git/hooks ] || mv .git/hooks .git/hooks-disabled
 886         ) || exit
 887 }
 888
 889 # This function helps on symlink challenged file systems when it is not
 890 # important that the file system entry is a symbolic link.
 891 # Use test_ln_s_add instead of "ln -s x y && git add y" to add a
 892 # symbolic link entry y to the index.
 893
 894 test_ln_s_add() {
 895         if test_have_prereq SYMLINKS
 896         then
 897                 ln -s "$1" "$2" &&
 898                 git update-index --add "$2"
 899         else
 900                 printf '%s' "$1" >"$2" &&
 901                 ln_s_obj=$(git hash-object -w "$2") &&
 902                 git update-index --add --cacheinfo 120000 $ln_s_obj "$2" &&
 903                 # pick up stat info from the file
 904                 git update-index "$2"
 905         fi
 906 }
 907
 908 # This function writes out its parameters, one per line
 909 test_write_lines() {
 910         printf '%s\n' "$@"
 911 }
 912
 913 git() (
 914         "exec" "$GIT_PATH" "$@"
 915 )
 916
 917 perl() (
 918         "exec" "$PERL_PATH" "$@"
 919 )
 920
 921 # Given a variable $1, normalize the value of it to one of "true",
 922 # "false", or "auto" and store the result to it.
 923 #
 924 #     test_tristate TESTLIB_TEST_FLIBITY
 925 #
 926 # A variable set to an empty string is set to 'false'.
 927 # A variable set to 'false' or 'auto' keeps its value.
 928 # Anything else is set to 'true'.
 929 # An unset variable defaults to 'auto'.
 930 #
 931 # The last rule is to allow people to set the variable to an empty
 932 # string and export it to decline testing the particular feature
 933 # for versions both before and after this change.  We used to treat
 934 # both unset and empty variable as a signal for "do not test" and
 935 # took any non-empty string as "please test".
 936
 937 test_tristate() {
 938         if eval "test \"z\${$1+set}\" = \"zset\""
 939         then
 940                 # explicitly set
 941                 eval "set -- \"\$1\" \"\$$1\""
 942                 case "$2" in [-+]0?*|0?*)
 943                         set -- "$1" "${2#[-+]}"
 944                         set -- "$1" "$2" "${2%%[!0]*}"
 945                         set -- "$1" "${2#"$3"}"
 946                 esac
 947                 case "$2" in
 948                         [Aa][Uu][Tt][Oo])
 949                                 set "$1" "auto";;
 950                         ""|[Ff][Aa][Ll][Ss][Ee]|[Oo][Ff][Ff]|[Nn][Oo]|[-+]0|0)
 951                                 set "$1" "false";;
 952                         *)
 953                                 # Git is actually more picky than this in that
 954                                 # only true/on/yes/(int)!=0 qualify else an err
 955                                 # but the original code treated those as true
 956                                 set "$1" "true";;
 957                 esac
 958                 eval "$1=\"\$2\""
 959         else
 960                 eval "$1=\"auto\""
 961         fi
 962 }
 963
 964 # Exit the test suite, either by skipping all remaining tests or by
 965 # exiting with an error. If "$1" is "auto", we then we assume we were
 966 # opportunistically trying to set up some tests and we skip. If it is
 967 # "true", then we report a failure.
 968 #
 969 # The error/skip message should be given by $2.
 970 #
 971 test_skip_or_die() {
 972         case "$1" in
 973         auto)
 974                 skip_all=$2
 975                 test_done
 976                 ;;
 977         true)
 978                 error "$2"
 979                 ;;
 980         *)
 981                 error "BUG: test tristate is '$1' (real error: $2)"
 982         esac
 983 }
 984
 985 # The following mingw_* functions obey POSIX shell syntax, but are actually
 986 # bash scripts, and are meant to be used only with bash on Windows.
 987
 988 # A test_cmp function that treats LF and CRLF equal and avoids to fork
 989 # diff when possible.
 990 mingw_test_cmp() {
 991         # Read text into shell variables and compare them. If the results
 992         # are different, use regular diff to report the difference.
 993         local test_cmp_a= test_cmp_b=
 994
 995         # When text came from stdin (one argument is '-') we must feed it
 996         # to diff.
 997         local stdin_for_diff=
 998
 999         # Since it is difficult to detect the difference between an
1000         # empty input file and a failure to read the files, we go straight
1001         # to diff if one of the inputs is empty.
1002         if test -s "$1" && test -s "$2"
1003         then
1004                 # regular case: both files non-empty
1005                 mingw_read_file_strip_cr_ test_cmp_a <"$1"
1006                 mingw_read_file_strip_cr_ test_cmp_b <"$2"
1007         elif test -s "$1" && test "$2" = -
1008         then
1009                 # read 2nd file from stdin
1010                 mingw_read_file_strip_cr_ test_cmp_a <"$1"
1011                 mingw_read_file_strip_cr_ test_cmp_b
1012                 stdin_for_diff='<<<"$test_cmp_b"'
1013         elif test "$1" = - && test -s "$2"
1014         then
1015                 # read 1st file from stdin
1016                 mingw_read_file_strip_cr_ test_cmp_a
1017                 mingw_read_file_strip_cr_ test_cmp_b <"$2"
1018                 stdin_for_diff='<<<"$test_cmp_a"'
1019         fi
1020         test -n "$test_cmp_a" &&
1021         test -n "$test_cmp_b" &&
1022         test "$test_cmp_a" = "$test_cmp_b" ||
1023         eval "diff -u \"\$@\" $stdin_for_diff"
1024 }
1025
1026 # $1 is the name of the shell variable to fill in
1027 mingw_read_file_strip_cr_() {
1028         # Read line-wise using LF as the line separator
1029         # and use IFS to strip CR.
1030         local line
1031         while :
1032         do
1033                 if IFS=$'\r' read -r -d $'\n' line
1034                 then
1035                         # good
1036                         line=$line$'\n'
1037                 else
1038                         # we get here at EOF, but also if the last line
1039                         # was not terminated by LF; in the latter case,
1040                         # some text was read
1041                         if test -z "$line"
1042                         then
1043                                 # EOF, really
1044                                 break
1045                         fi
1046                 fi
1047                 eval "$1=\$$1\$line"
1048         done
1049 }
1050
1051 # Like "env FOO=BAR some-program", but run inside a subshell, which means
1052 # it also works for shell functions (though those functions cannot impact
1053 # the environment outside of the test_env invocation).
1054 test_env() {
1055         (
1056                 while test $# -gt 0
1057                 do
1058                         case "$1" in
1059                         *=*)
1060                                 eval "${1%%=*}=\${1#*=}"
1061                                 eval "export ${1%%=*}"
1062                                 shift
1063                                 ;;
1064                         *)
1065                                 "$@"
1066                                 exit
1067                                 ;;
1068                         esac
1069                 done
1070         )
1071 }
1072
1073 # Returns true if the numeric exit code in "$2" represents the expected signal
1074 # in "$1". Signals should be given numerically.
1075 test_match_signal() {
1076         if test "$2" = "$((128 + $1))"
1077         then
1078                 # POSIX
1079                 return 0
1080         elif test "$2" = "$((256 + $1))"
1081         then
1082                 # ksh
1083                 return 0
1084         fi
1085         return 1
1086 }
1087
1088 # Read up to "$1" bytes (or to EOF) from stdin and write them to stdout.
1089 test_copy_bytes() {
1090         dd bs=1 count="$1" 2>/dev/null
1091 }
1092
1093 #
1094 # THIS SHOULD ALWAYS BE THE LAST FUNCTION DEFINED IN THIS FILE
1095 #
1096 # Any client that sources this file should immediately execute this function
1097 # afterwards.
1098 #
1099 # THERE SHOULD NOT BE ANY DIRECTLY EXECUTED LINES OF CODE IN THIS FILE
1100 #
1101 test_lib_functions_init() {
1102         satisfied_prereq=" "
1103         lazily_testable_prereq= lazily_tested_prereq=
1104 }