3 # Copyright (C) 2011-2024 Free Software Foundation, Inc.
5 # This program is free software; you can redistribute it and/or modify
6 # it under the terms of the GNU General Public License as published by
7 # the Free Software Foundation; either version 2, or (at your option)
10 # This program is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 # GNU General Public License for more details.
15 # You should have received a copy of the GNU General Public License
16 # along with this program. If not, see <https://www.gnu.org/licenses/>.
18 # Helper functions used by TAP-producing tests of the Automake testsuite.
21 # IMPORTANT: All the functions defined in this file can *not* be used
22 # from within a subshell, unless explicitly noted otherwise.
25 # The counts of the TAP test results seen so far: total count and
34 # not COMMAND [ARGS...]
35 # ---------------------
36 # Run the given command and invert its exit status.
39 # plan_ [unknown|later|lazy|now|NUMBER-OF-PLANNED-TESTS]
40 # ------------------------------------------------------
41 # Print a TAP plan for the given number of tests. This must be called
42 # before reporting any test result. If called with the special argument
43 # "unknown" or "later", it will do nothing, expecting the calling script
44 # to declare the plan later. If called with the special argument "lazy"
45 # or "now", it will print a TAP plan that accounts for the number of tests
49 if test $# -eq 0; then
50 bailout_
"plan_: missing argument"
51 elif test $# -ge 2; then
52 bailout_
"plan_: too many arguments"
53 elif test x
"$planned_" != x
"none" && test x
"$planned_" != x
"later"; then
54 bailout_
"plan_: called to many times"
55 elif test x
"$1" = x
"unknown" ||
test x
"$1" = x
"later"; then
56 # This means we want to get back later to declaring the TAP plan.
59 elif test x
"$1" = x
"lazy" ||
test x
"$1" = x
"now"; then
60 planned_
=$tap_count_ # Number of test results seen so far.
61 elif test $1 -ge 0; then
64 bailout_
"plan_: invalid argument '$1'"
72 # Report the given text as TAP diagnostic. Assumes the string denoting
73 # TAP diagnostic lines is stored in the '$diag_string_' variable; this is
74 # done to allow better interplay with TAP drivers that allow such a string
78 test $# -eq 0 ||
echo "$diag_string_ $*"
81 # Used by the 'diag_' function above. User-overridable.
86 # Give a warning (using TAP diagnostic).
90 0) diag_
"WARNING: (unknown warning)";;
91 *) diag_
"WARNING: $*";;
95 # result_ RESULT [-D DIRECTIVE] [-r REASON] [--] [DESCRIPTION...]
96 # ---------------------------------------------------------------
97 # Report a test case with the given RESULT (valid values are "ok" and
98 # "not ok") and the given DESCRIPTION (if any). If DIRECTIVE is given
99 # and non-empty (valid values being "TODO" and "SKIP"), it will be
100 # reported too, with the REASON (if given) appended.
103 set +x
# Don't pollute the log files.
104 test $# -gt 0 || bailout_
"result_: missing argument"
105 tap_result_
=$1; shift
108 *) bailout_
"result_: invalid result '$tap_result'" ;;
110 tap_directive_
= tap_reason_
=
111 while test $# -gt 0; do
113 -D|
--directive) tap_directive_
=$2; shift;;
114 -r|
--reason) tap_reason_
=$2; shift;;
116 -*) bailout_
"result_: invalid option '$1'";;
121 case $tap_directive_ in
123 *) bailout_
"result_: invalid directive '$directive_'" ;;
125 tap_count_
=$
(($tap_count_ + 1))
126 case $tap_result_,$tap_directive_ in
128 tap_pass_count_
=$
(($tap_pass_count_ + 1)) ;;
129 not\ ok
,TODO
) # Expected failure.
130 tap_xfail_count_
=$
(($tap_xfail_count_ + 1)) ;;
132 tap_fail_count_
=$
(($tap_fail_count_ + 1)) ;;
133 ok
,TODO
) # Unexpected pass.
134 tap_xpass_count_
=$
(($tap_xpass_count_ + 1)) ;;
136 tap_skip_count_
=$
(($tap_skip_count_ + 1)) ;;
138 bailout_
"internal error in 'result_'" ;;
140 tap_text_
="$tap_result_ $tap_count_"
141 if test x
"$*" != x
; then
142 tap_text_
="$tap_text_ - $*"
144 if test x
"$tap_directive_" != x
; then
145 tap_text_
="$tap_text_ # $tap_directive_"${tap_reason_:+" $tap_reason_"}
147 printf '%s\n' "$tap_text_"
148 set -x # Restore shell xtraces.
151 # Shorthand for common usages of 'result_'.
152 ok_
() { result_
'ok' ${1+"$@"}; }
153 not_ok_
() { result_
'not ok' ${1+"$@"}; }
154 skip_
() { result_
'ok' -D SKIP
${1+"$@"}; }
156 # skip_row_ COUNT [-r REASON] [--] [DESCRIPTION...]
157 # -------------------------------------------------
158 # Report a COUNT of skipped test, with the given reason and descriptions
159 # (if any). Useful to avoid cascade failures in case a fair number of
160 # tests depend on an earlier one that failed.
163 skip_count_
=$1; shift
164 for i_
in $
(seq_
$skip_count_); do skip_
${1+"$@"}; done
167 # skip_all_ [REASON ...]
168 # ----------------------
169 # Skip all the tests in a test script. Must be used before calling 'plan_'
170 # or reporting any test result. Can't be used from within a subshell.
173 echo "1..0 # SKIP" ${1+"$@"}
178 # bailout_ [REASON ...]
179 # ---------------------
180 # Stop the execution of the current test suite right now, due to an
181 # unrecoverable error. Can be called at any point, but cannot be used
182 # from within a subshell.
185 echo 'Bail out!' ${1+"$@"}
189 # fatal_ [REASON ...]
190 # -------------------
191 # Same as 'bailout_'; for compatibility with 'plain-functions.sh'.
197 # framework_failure_ [REASON ...]
198 # -------------------------------
199 # Stop the execution of the current test suite right now, due to an
200 # unrecoverable error in the set-up of the test case. Can be called
201 # at any point, but cannot be used from within a subshell.
202 framework_failure_
()
204 bailout_
"set-up failure"${1+": $*"}
207 # command_ok_ TEST-DESCRIPTION [OPTIONS..] [--] CMD [ARGS...]
208 # -----------------------------------------------------------
209 # Helper subroutine for when a TAP result must be determined by the
210 # outcome of a command.
213 tap_directive_
= tap_reason_
=
214 test $# -gt 0 || bailout_
"command_ok_: missing argument"
215 tap_description_
=$1; shift
216 while test $# -gt 0; do
218 -D|
--directive) tap_directive_
=$2; shift;;
219 -r|
--reason) tap_reason_
=$2; shift;;
221 -*) bailout_
"command_ok_: invalid option '$1'";;
226 tap_result_
="ok"; "$@" || tap_result_
="not ok"
227 result_
"$tap_result_" -D "$tap_directive_" -r "$tap_reason_" \
228 -- "$tap_description_"