diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.in | 197 | ||||
| -rw-r--r-- | doc/dejagnu.texi | 198 |
2 files changed, 266 insertions, 129 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in index 1c0bd6a..1753a6e 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -1,6 +1,7 @@ -# Makefile.in generated automatically by automake 1.4-p4 from Makefile.am +# Makefile.in generated automatically by automake 1.5 from Makefile.am. -# Copyright (C) 1994, 1995-8, 1999 Free Software Foundation, Inc. +# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 +# Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, # with or without modifications, as long as this notice is preserved. @@ -10,8 +11,9 @@ # even the implied warranty of MERCHANTABILITY or FITNESS FOR A # PARTICULAR PURPOSE. -# AUTOMAKE_OPTIONS = +@SET_MAKE@ +# AUTOMAKE_OPTIONS = SHELL = @SHELL@ @@ -33,13 +35,9 @@ infodir = @infodir@ mandir = @mandir@ includedir = @includedir@ oldincludedir = /usr/include - -DESTDIR = - pkgdatadir = $(datadir)/@PACKAGE@ pkglibdir = $(libdir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ - top_builddir = .. ACLOCAL = @ACLOCAL@ @@ -48,64 +46,70 @@ AUTOMAKE = @AUTOMAKE@ AUTOHEADER = @AUTOHEADER@ INSTALL = @INSTALL@ -INSTALL_PROGRAM = @INSTALL_PROGRAM@ $(AM_INSTALL_PROGRAM_FLAGS) +INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_DATA = @INSTALL_DATA@ INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_HEADER = $(INSTALL_DATA) transform = @program_transform_name@ - NORMAL_INSTALL = : PRE_INSTALL = : POST_INSTALL = : NORMAL_UNINSTALL = : PRE_UNINSTALL = : POST_UNINSTALL = : +AMTAR = @AMTAR@ +AWK = @AWK@ BOARDS = @BOARDS@ CC = @CC@ CONFIG = @CONFIG@ CXX = @CXX@ +DEPDIR = @DEPDIR@ EXEEXT = @EXEEXT@ -LEX = @LEX@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ MAINT = @MAINT@ -MAKEINFO = @MAKEINFO@ +OBJEXT = @OBJEXT@ PACKAGE = @PACKAGE@ TCLSH = @TCLSH@ VERSION = @VERSION@ YACC = @YACC@ +am__include = @am__include@ +am__quote = @am__quote@ +install_sh = @install_sh@ tclsh = @tclsh@ - -man_MANS = runtest.1 # FIXME: We need to generate an info doc from SGML somehow, but for # now, don't install the old texinfo document from version 1.3 # info_TEXINFOS = dejagnu.texi DOCBOOK = @DOCBOOK@ + +man_MANS = runtest.1 TARGETS = overview.html overview.ps overview.pdf overview.rtf +subdir = doc mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs -CONFIG_CLEAN_FILES = -man1dir = $(mandir)/man1 -MANS = $(man_MANS) +CONFIG_CLEAN_FILES = +DIST_SOURCES = NROFF = nroff -DIST_COMMON = README Makefile.am Makefile.in configure configure.in - - -DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST) +MANS = $(man_MANS) +DIST_COMMON = README Makefile.am Makefile.in configure configure.in +all: all-am -TAR = gtar -GZIP_ENV = --best -all: all-redirect .SUFFIXES: -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4) - cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile - -Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status $(BUILT_SOURCES) - cd $(top_builddir) \ - && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status - +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4) + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +Makefile: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.in $(top_builddir)/config.status + cd $(top_builddir) && \ + CONFIG_HEADERS= CONFIG_LINKS= \ + CONFIG_FILES=$(subdir)/$@ $(SHELL) ./config.status +uninstall-info-am: -install-man1: +man1dir = $(mandir)/man1 +install-man1: $(man1_MANS) $(man_MANS) + @$(NORMAL_INSTALL) $(mkinstalldirs) $(DESTDIR)$(man1dir) - @list='$(man1_MANS)'; \ - l2='$(man_MANS)'; for i in $$l2; do \ + @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ case "$$i" in \ *.1*) list="$$list $$i" ;; \ esac; \ @@ -115,14 +119,16 @@ install-man1: else file=$$i; fi; \ ext=`echo $$i | sed -e 's/^.*\\.//'`; \ inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ inst=`echo $$inst | sed '$(transform)'`.$$ext; \ echo " $(INSTALL_DATA) $$file $(DESTDIR)$(man1dir)/$$inst"; \ $(INSTALL_DATA) $$file $(DESTDIR)$(man1dir)/$$inst; \ done - uninstall-man1: - @list='$(man1_MANS)'; \ - l2='$(man_MANS)'; for i in $$l2; do \ + @$(NORMAL_UNINSTALL) + @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ case "$$i" in \ *.1*) list="$$list $$i" ;; \ esac; \ @@ -130,100 +136,112 @@ uninstall-man1: for i in $$list; do \ ext=`echo $$i | sed -e 's/^.*\\.//'`; \ inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ inst=`echo $$inst | sed '$(transform)'`.$$ext; \ echo " rm -f $(DESTDIR)$(man1dir)/$$inst"; \ rm -f $(DESTDIR)$(man1dir)/$$inst; \ done -install-man: $(MANS) - @$(NORMAL_INSTALL) - $(MAKE) $(AM_MAKEFLAGS) install-man1 -uninstall-man: - @$(NORMAL_UNINSTALL) - $(MAKE) $(AM_MAKEFLAGS) uninstall-man1 tags: TAGS TAGS: -distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) -subdir = doc +top_distdir = .. +distdir = $(top_distdir)/$(PACKAGE)-$(VERSION) distdir: $(DISTFILES) - here=`cd $(top_builddir) && pwd`; \ - top_distdir=`cd $(top_distdir) && pwd`; \ - distdir=`cd $(distdir) && pwd`; \ - cd $(top_srcdir) \ - && $(AUTOMAKE) --include-deps --build-dir=$$here --srcdir-name=$(top_srcdir) --output-dir=$$top_distdir --gnu doc/Makefile @for file in $(DISTFILES); do \ - d=$(srcdir); \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test "$$dir" != "$$file" && test "$$dir" != "."; then \ + $(mkinstalldirs) "$(distdir)/$$dir"; \ + fi; \ if test -d $$d/$$file; then \ - cp -pr $$d/$$file $(distdir)/$$file; \ + cp -pR $$d/$$file $(distdir) \ + || exit 1; \ else \ test -f $(distdir)/$$file \ - || ln $$d/$$file $(distdir)/$$file 2> /dev/null \ - || cp -p $$d/$$file $(distdir)/$$file || :; \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ fi; \ done -info-am: -info: info-am -dvi-am: -dvi: dvi-am check-am: all-am check: check-am -installcheck-am: -installcheck: installcheck-am -install-exec-am: -install-exec: install-exec-am +all-am: Makefile $(MANS) -install-data-am: install-man -install-data: install-data-am +installdirs: + $(mkinstalldirs) $(DESTDIR)$(man1dir) -install-am: all-am - @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am install: install-am -uninstall-am: uninstall-man +install-exec: install-exec-am +install-data: install-data-am uninstall: uninstall-am -all-am: Makefile $(MANS) -all-redirect: all-am -install-strip: - $(MAKE) $(AM_MAKEFLAGS) AM_INSTALL_PROGRAM_FLAGS=-s install -installdirs: - $(mkinstalldirs) $(DESTDIR)$(mandir)/man1 +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install mostlyclean-generic: clean-generic: distclean-generic: - -rm -f Makefile $(CONFIG_CLEAN_FILES) - -rm -f config.cache config.log stamp-h stamp-h[0-9]* + -rm -f Makefile $(CONFIG_CLEAN_FILES) stamp-h stamp-h[0-9]* maintainer-clean-generic: -mostlyclean-am: mostlyclean-generic + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am -mostlyclean: mostlyclean-am +clean-am: clean-generic mostlyclean-am -clean-am: clean-generic mostlyclean-am +distclean: distclean-am -clean: clean-am +distclean-am: clean-am distclean-generic -distclean-am: distclean-generic clean-am +dvi: dvi-am -distclean: distclean-am +dvi-am: -maintainer-clean-am: maintainer-clean-generic distclean-am - @echo "This command is intended for maintainers to use;" - @echo "it deletes files that may require special tools to rebuild." +info: info-am + +info-am: + +install-data-am: install-man + +install-exec-am: + +install-info: install-info-am + +install-man: install-man1 + +installcheck-am: maintainer-clean: maintainer-clean-am -.PHONY: install-man1 uninstall-man1 install-man uninstall-man tags \ -distdir info-am info dvi-am dvi check check-am installcheck-am \ -installcheck install-exec-am install-exec install-data-am install-data \ -install-am install uninstall-am uninstall all-redirect all-am all \ -installdirs mostlyclean-generic distclean-generic clean-generic \ -maintainer-clean-generic clean mostlyclean distclean maintainer-clean +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic + +uninstall-am: uninstall-info-am uninstall-man + +uninstall-man: uninstall-man1 + +.PHONY: all all-am check check-am clean clean-generic distclean \ + distclean-generic distdir dvi dvi-am info info-am install \ + install-am install-data install-data-am install-exec \ + install-exec-am install-info install-info-am install-man \ + install-man1 install-strip installcheck installcheck-am \ + installdirs maintainer-clean maintainer-clean-generic \ + mostlyclean mostlyclean-generic uninstall uninstall-am \ + uninstall-info-am uninstall-man uninstall-man1 docs: $(TARGETS) @@ -281,7 +299,6 @@ install-doc: $(TARGETS) $(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps $(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf $(INSTALL_DATA) $(srcdir)/runtest.1 $(mandir)/man1/ - # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. .NOEXPORT: diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi index 4d163c9..fb624a0 100644 --- a/doc/dejagnu.texi +++ b/doc/dejagnu.texi @@ -453,15 +453,6 @@ case: @item PASS A test has succeeded. That is, it demonstrated that the assertion is true. -@cindex XFAIL, avoiding for POSIX -@item XFAIL -@sc{posix} 1003.3 does not incorporate the notion of expected failures, -so @code{PASS}, instead of @code{XPASS}, must also be returned for test -cases which were expected to fail and did not. This means that -@code{PASS} is in some sense more ambiguous than if @code{XPASS} is also -used. For information on @code{XPASS} and @code{XFAIL}, see -@ref{Invoking runtest,,Using @code{runtest}}. - @item FAIL @cindex failure, POSIX definition A test @emph{has} produced the bug it was intended to capture. That is, @@ -469,9 +460,6 @@ it has demonstrated that the assertion is false. The @code{FAIL} message is based on the test case only. Other messages are used to indicate a failure of the framework. -As with @code{PASS}, @sc{posix} tests must return @code{FAIL} rather -than @code{XFAIL} even if a failure was expected. - @item UNRESOLVED @cindex ambiguity, required for POSIX A test produced indeterminate results. Usually, this means the test @@ -516,8 +504,9 @@ real test case yet. @end ftable @noindent -The only remaining output message left is intended to test features that -are specified by the applicable @sc{posix} standard as conditional: +The only remaining @sc{posix} output message left is intended to test +features that are specified by the applicable @sc{posix} standard as +conditional: @ftable @code @item UNSUPPORTED @@ -529,14 +518,73 @@ running the test case. For example, a test for the system subroutine @code{gethostname} would never work on a target board running only a boot monitor. @end ftable - + DejaGnu uses the same output procedures to produce these messages for all test suites, and these procedures are already known to conform to @sc{posix} 1003.3. For a DejaGnu test suite to conform to @sc{posix} -1003.3, you must avoid the @code{setup_xfail} procedure as described in -the @code{PASS} section above, and you must be careful to return +1003.3, you must avoid the @code{setup_xfail} and @code{setup_kfail} +procedures (see below), and you must be careful to return @code{UNRESOLVED} where appropriate, as described in the @code{UNRESOLVED} section above. + + +The additional messages are: + +@ftable @code + +@item XFAIL +A test is expected to fail in some environment(s) due to some bug +in the environment that we hope is fixed someday (but we can't do +nothing about as it is not a bug in the tool that we are testing). +The procedure @code{setup_xfail} is used to indicate that a failure +is expected. + +@cindex XFAIL, avoiding for POSIX +@sc{posix} 1003.3 does not incorporate the notion of expected failures, +so @sc{posix} tests must return @code{FAIL} rather +than @code{XFAIL} even if a failure was expected. + +@item KFAIL +A test is known to fail in some environment(s) due to a known bug +in the tool being tested (identified by a bug id string). This +exists so that, after a bug is identified and properly registered +in a bug tracking database (Gnats, for instance), the count of +failures can be kept as zero. Having zero as a baseline in all +platforms allow the tool developers to immediately detect regressions +caused by changes (which may affect some platforms and not others). +The connection with a bug tracking database allows for automatic +generation of the BUGS section of man pages or Release Notes, as +well as a "Bugs Fixed this Release" section (by comparing to a +previous release set of known failures). +The procedure @code{setup_kfail} is used to indicate a failure is +known to exist. + +@cindex KFAIL, avoiding for POSIX +As with @code{XFAIL}, @sc{posix} tests must return @code{FAIL} rather +than @code{KFAIL} even if a failure was due to a known bug. + + +@item XPASS +A test was expected to fail with @code{XFAIL} but passed instead. +Whatever problem that used to exist in the environment was corrected +The test may also be failing to detect the failure due to some +environment or output changes, so this possibility must be investigated +as well. + +@item KPASS +A test was expected to fail with @code{KFAIL} but passed instead. +Someone may have fixed the bug and failed to unmark the test. +As for XPASS, the test may also be failing to detect the +failure due to some environment or output changes, so this possibility +must also be checked. + +@code{PASS}, instead of @code{XPASS} or @code{KPASS}, must also be +returned for test cases which were expected to fail and did not, +if @sc{posix} 1003.3 compliance is required. +This means that @code{PASS} is in some sense more ambiguous than if +@code{XPASS} and @code{KPASS} are also used. + +@end ftable @node Future Directions @section Future directions @@ -616,6 +664,22 @@ A pleasant kind of failure: a test was expected to fail, but succeeded. This may indicate progress; inspect the test case to determine whether you should amend it to stop expecting failure. +@item KPASS +@kindex KPASS +@cindex successful test, unexpected +@cindex unexpected success +A pleasant kind of failure: a test was known to fail, but succeeded. +This may indicate progress; inspect the test case to determine whether +you should amend it to stop expecting failure. + +@item KPASS +@kindex KPASS +@cindex successful test, unexpected +@cindex unexpected success +A pleasant kind of failure: a test was known to fail, but succeeded. +This may indicate progress; inspect the test case to determine whether +you should amend it to stop expecting failure. + @item FAIL @kindex FAIL @cindex failing test, unexpected @@ -628,9 +692,19 @@ regress; inspect the test case and the failing software to locate the bug. @cindex expected failure @cindex failing test, expected A test failed, but it was expected to fail. This result indicates no -change in a known bug. If a test fails because the operating system -where the test runs lacks some facility required by the test, the -outcome is @code{UNSUPPORTED} instead. +change in a known environment bug. If a test fails because the operating +system where the test runs lacks some facility required by the test +(i.e. failure is due to the lack of a feature, not the existence of a bug), +the outcome is @code{UNSUPPORTED} instead. + +@item KFAIL +@kindex KFAIL +@cindex known failure +@cindex failing test, known +A test failed, but it was known to fail. This result indicates no +change in a known bug. If a test fails because of a problem in the +environment, not in the tool being tested, that is expected to be +fixed one day, the outcome is @code{XFAIL} instead. @item UNRESOLVED @kindex UNRESOLVED @@ -764,8 +838,8 @@ values}. @cindex test output, displaying all Display all test output. By default, @code{runtest} shows only the output of tests that produce unexpected results; that is, tests with -status @samp{FAIL} (unexpected failure), @samp{XPASS} (unexpected -success), or @samp{ERROR} (a severe error in the test case itself). +status @samp{FAIL} (unexpected failure), @samp{XPASS} or @samp{KPASS} +(unexpected success), or @samp{ERROR} (a severe error in the test case itself). Specify @samp{--all} to see output for tests with status @samp{PASS} (success, as expected) @samp{XFAIL} (failure, as expected), or @samp{WARNING} (minor error in the test case itself). @@ -844,8 +918,9 @@ recorded by your configuration's choice of host. This choice does not change how anything is actually configured unless --build is also specified; it affects @emph{only} DejaGnu procedures that compare the host string with particular values. The procedures @code{ishost}, -@code{istarget}, @code{isnative}, and @code{setup_xfail} are affected by -@samp{--host}. In this usage, @code{host} refers to the machine that the +@code{istarget}, @code{isnative}, @code{setup_xfail} and +@code{setup_kfail} are affected by @samp{--host}. +In this usage, @code{host} refers to the machine that the tests are to be run on, which may not be the same as the @code{build} machine. If @code{--build} is also specified, then @code{--host} refers to the machine that the tests wil, be run on, not the machine DejaGnu is @@ -1736,8 +1811,9 @@ the verbosity level use @code{note}. @item pass "@var{string}" @cindex test case, declaring success Declares a test to have passed. @code{pass} writes in the -log files a message beginning with @samp{PASS} (or @code{XPASS}, if -failure was expected), appending the argument @var{string}. +log files a message beginning with @samp{PASS} +(or @code{XPASS}/@code{KPASS}, if failure was expected), +appending the argument @var{string}. @item fail "@var{string}" @cindex test case, declaring failure @@ -1860,18 +1936,44 @@ common shell wildcard characters to specify sets of names). The output; use it as a link to a bug-tracking system such as @sc{gnats} (@pxref{Overview,, Overview, gnats.info, Tracking Bugs With GNATS}). +See notes under setup_kfail (below). + +@item setup_kfail "@var{config} @r{[}@var{bugid}@r{]}" +@c two spaces above to make it absolutely clear there's whitespace---a +@c crude sort of italic correction! +@cindex test case, known failure +@cindex failure, known +@cindex known failure +Declares that the test is known to fail on a particular set of +configurations. The @var{config} argument must be a list of full +three-part @code{configure} target name; in particular, you may not use +the shorter nicknames supported by @code{configure} (but you can use the +common shell wildcard characters to specify sets of names). The +@var{bugid} argument is mandatory, and used only in the logging file +output; use it as a link to a bug-tracking system such as @sc{gnats} +(@pxref{Overview,, Overview, gnats.info, Tracking Bugs With GNATS}). + @cindex @code{XFAIL}, producing +@cindex @code{KFAIL}, producing @cindex @code{XPASS}, producing -Once you use @code{setup_xfail}, the @code{fail} and @code{pass} -procedures produce the messages @samp{XFAIL} and @samp{XPASS} -respectively, allowing you to distinguish expected failures (and -unexpected success!) from other test outcomes. - -@emph{Warning:} you must clear the expected failure after using -@code{setup_xfail} in a test case. Any call to @code{pass} or -@code{fail} clears the expected failure implicitly; if the test has some -other outcome, e.g. an error, you can call @code{clear_xfail} to clear -the expected failure explicitly. Otherwise, the expected-failure +@cindex @code{KPASS}, producing +Once you use @code{setup_xfail} or @code{setup_kfail}, the @code{fail} +and @code{pass} procedures produce the messages @samp{XFAIL} or @samp{KFAIL} +and @samp{XPASS} or @samp{KPASS} respectively, allowing you to distinguish +expected/known failures (and unexpected success!) from other test outcomes. + +If a test is marked as both expected to fail and known to fail for a +certain configuration, a @samp{KFAIL} message will be generated. +As @samp{KFAIL} messages are expected to draw more attention than +the @samp{XFAIL} ones this will hopefuly ensure the test result is not +overlooked. + +@emph{Warning:} you must clear the expected/known failure after using +@code{setup_xfail} or @code{setup_kfail} in a test case. Any call to +@code{pass} or @code{fail} clears the expectedknown failure implicitly; +if the test has some other outcome, e.g. an error, you can call +@code{clear_xfail} to clear the expected failure or @code{clear_kfail} +to clear the known failure explicitly. Otherwise, the expected-failure declaration applies to whatever test runs next, leading to surprising results. @@ -1952,6 +2054,24 @@ list of configuration target names. It is only necessary to call @code{clear_xfail} if a test case ends without calling either @code{pass} or @code{fail}, after calling @code{setup_xfail}. +@item clear_kfail @var{config} +@cindex cancelling known failure +@cindex known failure, cancelling +Cancel a known failure (previously declared with @code{setup_kfail}) +for a particular set of configurations. The @var{config} argument is a +list of configuration target names. It is only necessary to call +@code{clear_kfail} if a test case ends without calling either +@code{pass} or @code{fail}, after calling @code{setup_kfail}. + +@item clear_kfail @var{config} +@cindex cancelling known failure +@cindex known failure, cancelling +Cancel a known failure (previously declared with @code{setup_kfail}) +for a particular set of configurations. The @var{config} argument is a +list of configuration target names. It is only necessary to call +@code{clear_kfail} if a test case ends without calling either +@code{pass} or @code{fail}, after calling @code{setup_kfail}. + @item verbose @r{[}-log@r{]} @r{[}-n@r{]} @r{[}--@r{]} "@var{string}" @var{number} @cindex @code{verbose} builtin function Test cases can use this function to issue helpful messages depending on @@ -2627,9 +2747,9 @@ For troubleshooting, a third kind of output file is useful: use @code{runtest} always produces a summary output file @file{@var{tool}.sum}. This summary shows the names of all test files run; for each test file, one line of output from each @code{pass} -command (showing status @samp{PASS} or @samp{XPASS}) or @code{fail} -command (status @samp{FAIL} or @samp{XFAIL}); trailing summary -statistics that count passing and failing tests (expected and +command (showing status @samp{PASS}, @samp{XPASS} or @samp{KPASS}) or +@code{fail} command (status @samp{FAIL}, @samp{XFAIL} or @samp{KFAIL}); +trailing summary statistics that count passing and failing tests (expected and unexpected); and the full pathname and version number of the tool tested. (All possible outcomes, and all errors, are always reflected in the summary output file, regardless of whether or not you specify |