2012-09-04 23:07:32 +00:00
|
|
|
.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
|
|
|
|
|
.\" All rights reserved.
|
|
|
|
|
.\"
|
|
|
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
|
|
|
.\" modification, are permitted provided that the following conditions
|
|
|
|
|
.\" are met:
|
|
|
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
|
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
|
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
|
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
|
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
|
|
|
.\"
|
|
|
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND
|
|
|
|
|
.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
|
|
|
|
|
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
|
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
|
|
|
.\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY
|
|
|
|
|
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
|
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
|
|
|
|
|
.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
|
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
|
|
|
|
|
.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
|
|
|
|
|
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
|
|
|
|
|
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
Import atf-0.21:
Released on October 23rd, 2014.
* Restored the atf(7) manual page to serve as a reference to all the other
manual pages shipped by ATF.
* Added the -s flag to atf-sh to support specifying the shell interpreter
to be used.
* Removed ATF_WORKDIR. The only remaining consumers have been converted to
use the standard TMPDIR environment variable. As a benefit, and because
Kyua forces the TMPDIR to live within the test case's work directory,
any stale files left behind by ATF will be automatically cleaned up.
* Documented the environment variables recognized by each component in the
relevant manual pages. This information was lost with the atf-config(1)
removal.
* Added a new "require.diskspace" metadata property to test cases so that
they can specify the minimum amount of disk space required for the test
to run.
* Renamed the atf-{c,c++,sh}-api(3) manual pages to atf-{c,c++,sh}(3) for
discoverability purposes. Symbolic links are provided for the time
being to still make the old names visible.
* Issue #5: Recommend the (expected, actual) idiom for calls to the test
macros in the manual pages.
* Issue #7: Stopped catching unhandled exceptions in atf-c++ tests. This
propagates the crash to the caller, which in turn allows it to obtain
proper debugging information. In particular, Kyua should now be able to
extract a stacktrace pinpointing the problem.
* Issue #8: Fixed atf-c/macros_test:use test failures spotted by the clang
that ships with FreeBSD 11.0-CURRENT.
* Issue #12: Improved documentation of atf-sh(3) and atf-check(1) by better
explaining how they relate to each other.
* Issue #14: Stopped setting 'set -e' in atf-sh. This setting was
initially added as a way to enable a "strict" mode in the library and to
make test cases fail fast when they run unprotected commands. However,
doing so in the library is surprising as the responsibility of enabling
'set -e' should be on the user's code. Also, 'set -e' introduces
inconsistent behavior on subshells and users do not expect that.
* Issue #15: Fixed atf_utils_{fork,wait} to support nested calls.
* Issue #16: Fixed test failures (by removing a long-standing hack) on
systems that lack \e support in printf(1).
* Issue #19: Removed stale references to atf-config and atf-run.
2014-10-30 17:14:07 +00:00
|
|
|
.Dd October 5, 2014
|
2012-09-04 23:07:32 +00:00
|
|
|
.Dt ATF-TEST-CASE 4
|
|
|
|
|
.Os
|
|
|
|
|
.Sh NAME
|
|
|
|
|
.Nm atf-test-case
|
|
|
|
|
.Nd generic description of test cases
|
|
|
|
|
.Sh DESCRIPTION
|
|
|
|
|
A
|
|
|
|
|
.Em test case
|
|
|
|
|
is a piece of code that stress-tests a specific feature of the software.
|
|
|
|
|
This feature is typically self-contained enough, either in the amount of
|
|
|
|
|
code that implements it or in the general idea that describes it, to
|
|
|
|
|
warrant its independent testing.
|
|
|
|
|
Given this, test cases are very fine-grained, but they attempt to group
|
|
|
|
|
similar smaller tests which are semantically related.
|
|
|
|
|
.Pp
|
|
|
|
|
A test case is defined by three components regardless of the language it is
|
|
|
|
|
implemented in: a header, a body and a cleanup routine.
|
|
|
|
|
The
|
|
|
|
|
.Em header
|
|
|
|
|
is, basically, a declarative piece of code that defines several
|
|
|
|
|
properties to describe what the test case does and how it behaves.
|
|
|
|
|
In other words: it defines the test case's
|
|
|
|
|
.Em meta-data ,
|
|
|
|
|
further described in the
|
|
|
|
|
.Sx Meta-data
|
|
|
|
|
section.
|
|
|
|
|
The
|
|
|
|
|
.Em body
|
|
|
|
|
is the test case itself.
|
|
|
|
|
It executes all actions needed to reproduce the test, and checks for
|
|
|
|
|
failures.
|
|
|
|
|
This body is only executed if the abstract conditions specified by the
|
|
|
|
|
header are met.
|
|
|
|
|
The
|
Import atf-0.17:
Experimental version released on February 14th, 2013.
* Added the atf_utils_cat_file, atf_utils_compare_file,
atf_utils_copy_file, atf_utils_create_file, atf_utils_file_exists,
atf_utils_fork, atf_utils_grep_file, atf_utils_grep_string,
atf_utils_readline, atf_utils_redirect and atf_utils_wait utility
functions to atf-c-api. Documented the already-public
atf_utils_free_charpp function.
* Added the cat_file, compare_file, copy_file, create_file, file_exists,
fork, grep_collection, grep_file, grep_string, redirect and wait
functions to the atf::utils namespace of atf-c++-api. These are
wrappers around the same functions added to the atf-c-api library.
* Added the ATF_CHECK_MATCH, ATF_CHECK_MATCH_MSG, ATF_REQUIRE_MATCH and
ATF_REQUIRE_MATCH_MSG macros to atf-c to simplify the validation of a
string against a regular expression.
* Miscellaneous fixes for manpage typos and compilation problems with
clang.
* Added caching of the results of those configure tests that rely on
executing a test program. This should help crossbuild systems by
providing a mechanism to pre-specify what the results should be.
* X-NetBSD-PR bin/45690: Make atf-report convert any non-printable
characters to a plain-text representation (matching their
corresponding hexadecimal entities) in XML output files. This is to
prevent the output of test cases from breaking xsltproc later.
Note that this import, compared to the one for 0.16, brings in all the
files that are part of the release. This is to follow the Subversion
Primer guidelines, which mention that all files should be imported first
and only dropped when merging into contrib/atf/.
Approved by: rpaulo (mentor)
2013-11-15 21:28:06 +00:00
|
|
|
.Em cleanup
|
2012-09-04 23:07:32 +00:00
|
|
|
routine is a piece of code always executed after the body, regardless of
|
|
|
|
|
the exit status of the test case.
|
|
|
|
|
It can be used to undo side-effects of the test case.
|
|
|
|
|
Note that almost all side-effects of a test case are automatically cleaned
|
|
|
|
|
up by the library; this is explained in more detail in the rest of this
|
|
|
|
|
document.
|
|
|
|
|
.Pp
|
|
|
|
|
It is extremely important to keep the separation between a test case's
|
|
|
|
|
header and body well-defined, because the header is
|
|
|
|
|
.Em always
|
|
|
|
|
parsed, whereas the body is only executed when the conditions defined in
|
|
|
|
|
the header are met and when the user specifies that test case.
|
|
|
|
|
.Pp
|
|
|
|
|
At last, test cases are always contained into test programs.
|
|
|
|
|
The test programs act as a front-end to them, providing a consistent
|
|
|
|
|
interface to the user and several APIs to ease their implementation.
|
|
|
|
|
.Ss Results
|
|
|
|
|
Upon termination, a test case reports a status and, optionally, a textual
|
|
|
|
|
reason describing why the test reported such status.
|
|
|
|
|
The caller must ensure that the test case really performed the task that its
|
|
|
|
|
status describes, as the test program may be bogus and therefore providing a
|
|
|
|
|
misleading result (e.g. providing a result that indicates success but the
|
|
|
|
|
error code of the program says otherwise).
|
|
|
|
|
.Pp
|
|
|
|
|
The possible exit status of a test case are one of the following:
|
|
|
|
|
.Bl -tag -width expectedXfailureXX
|
|
|
|
|
.It expected_death
|
|
|
|
|
The test case expects to terminate abruptly.
|
|
|
|
|
.It expected_exit
|
|
|
|
|
The test case expects to exit cleanly.
|
|
|
|
|
.It expected_failure
|
|
|
|
|
The test case expects to exit with a controller fatal/non-fatal failure.
|
|
|
|
|
If this happens, the test program exits with a success error code.
|
|
|
|
|
.It expected_signal
|
|
|
|
|
The test case expects to receive a signal that makes it terminate.
|
|
|
|
|
.It expected_timeout
|
|
|
|
|
The test case expects to execute for longer than its timeout.
|
|
|
|
|
.It passed
|
|
|
|
|
The test case was executed successfully.
|
|
|
|
|
The test program exits with a success error code.
|
|
|
|
|
.It skipped
|
|
|
|
|
The test case could not be executed because some preconditions were not
|
|
|
|
|
met.
|
|
|
|
|
This is not a failure because it can typically be resolved by adjusting
|
|
|
|
|
the system to meet the necessary conditions.
|
|
|
|
|
This is always accompanied by a
|
|
|
|
|
.Em reason ,
|
|
|
|
|
a message describing why the test was skipped.
|
|
|
|
|
The test program exits with a success error code.
|
|
|
|
|
.It failed
|
|
|
|
|
An error appeared during the execution of the test case.
|
|
|
|
|
This is always accompanied by a
|
|
|
|
|
.Em reason ,
|
|
|
|
|
a message describing why the test failed.
|
|
|
|
|
The test program exits with a failure error code.
|
|
|
|
|
.El
|
|
|
|
|
.Pp
|
|
|
|
|
The usefulness of the
|
|
|
|
|
.Sq expected_*
|
|
|
|
|
results comes when writing test cases that verify known failures caused,
|
|
|
|
|
in general, due to programming errors (aka bugs).
|
2014-02-14 14:41:25 +00:00
|
|
|
Whenever the faulty condition that the
|
|
|
|
|
.Sq expected_*
|
|
|
|
|
result is trying to cover is fixed, then the test case will be reported as
|
2012-09-04 23:07:32 +00:00
|
|
|
.Sq failed
|
|
|
|
|
and the developer will have to adjust it to match its new condition.
|
|
|
|
|
.Pp
|
|
|
|
|
It is important to note that all
|
|
|
|
|
.Sq expected_*
|
|
|
|
|
results are only provided as a
|
|
|
|
|
.Em hint
|
|
|
|
|
to the caller; the caller must verify that the test case did actually terminate
|
|
|
|
|
as the expected condition says.
|
|
|
|
|
.Ss Input/output
|
|
|
|
|
Test cases are free to print whatever they want to their
|
|
|
|
|
.Xr stdout 4
|
|
|
|
|
and
|
|
|
|
|
.Xr stderr 4
|
|
|
|
|
file descriptors.
|
|
|
|
|
They are, in fact, encouraged to print status information as they execute
|
|
|
|
|
to keep the user informed of their actions.
|
|
|
|
|
This is specially important for long test cases.
|
|
|
|
|
.Pp
|
|
|
|
|
Test cases will log their results to an auxiliary file, which is then
|
|
|
|
|
collected by the test program they are contained in.
|
|
|
|
|
The developer need not care about this as long as he uses the correct
|
|
|
|
|
APIs to implement the test cases.
|
|
|
|
|
.Pp
|
|
|
|
|
The standard input of the test cases is unconditionally connected to
|
|
|
|
|
.Sq /dev/zero .
|
|
|
|
|
.Ss Meta-data
|
|
|
|
|
The following list describes all meta-data properties interpreted
|
|
|
|
|
internally by ATF.
|
|
|
|
|
You are free to define new properties in your test cases and use them as
|
|
|
|
|
you wish, but non-standard properties must be prefixed by
|
|
|
|
|
.Sq X- .
|
|
|
|
|
.Bl -tag -width requireXmachineXX
|
|
|
|
|
.It descr
|
|
|
|
|
Type: textual.
|
|
|
|
|
Required.
|
|
|
|
|
.Pp
|
|
|
|
|
A brief textual description of the test case's purpose.
|
|
|
|
|
Will be shown to the user in reports.
|
|
|
|
|
Also good for documentation purposes.
|
|
|
|
|
.It has.cleanup
|
|
|
|
|
Type: boolean.
|
|
|
|
|
Optional.
|
|
|
|
|
.Pp
|
|
|
|
|
If set to true, specifies that the test case has a cleanup routine that has
|
Import atf-0.21:
Released on October 23rd, 2014.
* Restored the atf(7) manual page to serve as a reference to all the other
manual pages shipped by ATF.
* Added the -s flag to atf-sh to support specifying the shell interpreter
to be used.
* Removed ATF_WORKDIR. The only remaining consumers have been converted to
use the standard TMPDIR environment variable. As a benefit, and because
Kyua forces the TMPDIR to live within the test case's work directory,
any stale files left behind by ATF will be automatically cleaned up.
* Documented the environment variables recognized by each component in the
relevant manual pages. This information was lost with the atf-config(1)
removal.
* Added a new "require.diskspace" metadata property to test cases so that
they can specify the minimum amount of disk space required for the test
to run.
* Renamed the atf-{c,c++,sh}-api(3) manual pages to atf-{c,c++,sh}(3) for
discoverability purposes. Symbolic links are provided for the time
being to still make the old names visible.
* Issue #5: Recommend the (expected, actual) idiom for calls to the test
macros in the manual pages.
* Issue #7: Stopped catching unhandled exceptions in atf-c++ tests. This
propagates the crash to the caller, which in turn allows it to obtain
proper debugging information. In particular, Kyua should now be able to
extract a stacktrace pinpointing the problem.
* Issue #8: Fixed atf-c/macros_test:use test failures spotted by the clang
that ships with FreeBSD 11.0-CURRENT.
* Issue #12: Improved documentation of atf-sh(3) and atf-check(1) by better
explaining how they relate to each other.
* Issue #14: Stopped setting 'set -e' in atf-sh. This setting was
initially added as a way to enable a "strict" mode in the library and to
make test cases fail fast when they run unprotected commands. However,
doing so in the library is surprising as the responsibility of enabling
'set -e' should be on the user's code. Also, 'set -e' introduces
inconsistent behavior on subshells and users do not expect that.
* Issue #15: Fixed atf_utils_{fork,wait} to support nested calls.
* Issue #16: Fixed test failures (by removing a long-standing hack) on
systems that lack \e support in printf(1).
* Issue #19: Removed stale references to atf-config and atf-run.
2014-10-30 17:14:07 +00:00
|
|
|
to be executed by the runtime engine during the cleanup phase of the execution.
|
2012-09-04 23:07:32 +00:00
|
|
|
This property is automatically set by the framework when defining a test case
|
|
|
|
|
with a cleanup routine, so it should never be set by hand.
|
|
|
|
|
.It ident
|
|
|
|
|
Type: textual.
|
|
|
|
|
Required.
|
|
|
|
|
.Pp
|
|
|
|
|
The test case's identifier.
|
|
|
|
|
Must be unique inside the test program and should be short but descriptive.
|
|
|
|
|
.It require.arch
|
|
|
|
|
Type: textual.
|
|
|
|
|
Optional.
|
|
|
|
|
.Pp
|
|
|
|
|
A whitespace separated list of architectures that the test case can be run
|
|
|
|
|
under without causing errors due to an architecture mismatch.
|
|
|
|
|
.It require.config
|
|
|
|
|
Type: textual.
|
|
|
|
|
Optional.
|
|
|
|
|
.Pp
|
|
|
|
|
A whitespace separated list of configuration variables that must be defined
|
|
|
|
|
to execute the test case.
|
|
|
|
|
If any of the required variables is not defined, the test case is
|
|
|
|
|
.Em skipped .
|
Import atf-0.21:
Released on October 23rd, 2014.
* Restored the atf(7) manual page to serve as a reference to all the other
manual pages shipped by ATF.
* Added the -s flag to atf-sh to support specifying the shell interpreter
to be used.
* Removed ATF_WORKDIR. The only remaining consumers have been converted to
use the standard TMPDIR environment variable. As a benefit, and because
Kyua forces the TMPDIR to live within the test case's work directory,
any stale files left behind by ATF will be automatically cleaned up.
* Documented the environment variables recognized by each component in the
relevant manual pages. This information was lost with the atf-config(1)
removal.
* Added a new "require.diskspace" metadata property to test cases so that
they can specify the minimum amount of disk space required for the test
to run.
* Renamed the atf-{c,c++,sh}-api(3) manual pages to atf-{c,c++,sh}(3) for
discoverability purposes. Symbolic links are provided for the time
being to still make the old names visible.
* Issue #5: Recommend the (expected, actual) idiom for calls to the test
macros in the manual pages.
* Issue #7: Stopped catching unhandled exceptions in atf-c++ tests. This
propagates the crash to the caller, which in turn allows it to obtain
proper debugging information. In particular, Kyua should now be able to
extract a stacktrace pinpointing the problem.
* Issue #8: Fixed atf-c/macros_test:use test failures spotted by the clang
that ships with FreeBSD 11.0-CURRENT.
* Issue #12: Improved documentation of atf-sh(3) and atf-check(1) by better
explaining how they relate to each other.
* Issue #14: Stopped setting 'set -e' in atf-sh. This setting was
initially added as a way to enable a "strict" mode in the library and to
make test cases fail fast when they run unprotected commands. However,
doing so in the library is surprising as the responsibility of enabling
'set -e' should be on the user's code. Also, 'set -e' introduces
inconsistent behavior on subshells and users do not expect that.
* Issue #15: Fixed atf_utils_{fork,wait} to support nested calls.
* Issue #16: Fixed test failures (by removing a long-standing hack) on
systems that lack \e support in printf(1).
* Issue #19: Removed stale references to atf-config and atf-run.
2014-10-30 17:14:07 +00:00
|
|
|
.It require.diskspace
|
|
|
|
|
Type: integer.
|
|
|
|
|
Optional.
|
|
|
|
|
Specifies the minimum amount of available disk space needed by the test.
|
|
|
|
|
The value can have a size suffix such as
|
|
|
|
|
.Sq K ,
|
|
|
|
|
.Sq M ,
|
|
|
|
|
.Sq G
|
|
|
|
|
or
|
|
|
|
|
.Sq T
|
|
|
|
|
to make the amount of bytes easier to type and read.
|
2012-09-04 23:07:32 +00:00
|
|
|
.It require.files
|
|
|
|
|
Type: textual.
|
|
|
|
|
Optional.
|
|
|
|
|
.Pp
|
|
|
|
|
A whitespace separated list of files that must be present to execute the
|
|
|
|
|
test case.
|
|
|
|
|
The names of these files must be absolute paths.
|
|
|
|
|
If any of the required files is not found, the test case is
|
|
|
|
|
.Em skipped .
|
|
|
|
|
.It require.machine
|
|
|
|
|
Type: textual.
|
|
|
|
|
Optional.
|
|
|
|
|
.Pp
|
|
|
|
|
A whitespace separated list of machine types that the test case can be run
|
|
|
|
|
under without causing errors due to a machine type mismatch.
|
|
|
|
|
.It require.memory
|
|
|
|
|
Type: integer.
|
|
|
|
|
Optional.
|
|
|
|
|
Specifies the minimum amount of physical memory needed by the test.
|
|
|
|
|
The value can have a size suffix such as
|
|
|
|
|
.Sq K ,
|
|
|
|
|
.Sq M ,
|
|
|
|
|
.Sq G
|
|
|
|
|
or
|
|
|
|
|
.Sq T
|
|
|
|
|
to make the amount of bytes easier to type and read.
|
|
|
|
|
.It require.progs
|
|
|
|
|
Type: textual.
|
|
|
|
|
Optional.
|
|
|
|
|
.Pp
|
|
|
|
|
A whitespace separated list of programs that must be present to execute
|
|
|
|
|
the test case.
|
|
|
|
|
These can be given as plain names, in which case they are looked in the
|
|
|
|
|
user's
|
|
|
|
|
.Ev PATH ,
|
|
|
|
|
or as absolute paths.
|
|
|
|
|
If any of the required programs is not found, the test case is
|
|
|
|
|
.Em skipped .
|
|
|
|
|
.It require.user
|
|
|
|
|
Type: textual.
|
|
|
|
|
Optional.
|
|
|
|
|
.Pp
|
|
|
|
|
The required privileges to execute the test case.
|
|
|
|
|
Can be one of
|
|
|
|
|
.Sq root
|
|
|
|
|
or
|
|
|
|
|
.Sq unprivileged .
|
|
|
|
|
.Pp
|
|
|
|
|
If the test case is running as a regular user and this property is
|
|
|
|
|
.Sq root ,
|
|
|
|
|
the test case is
|
|
|
|
|
.Em skipped .
|
|
|
|
|
.Pp
|
|
|
|
|
If the test case is running as root and this property is
|
|
|
|
|
.Sq unprivileged ,
|
Import atf-0.21:
Released on October 23rd, 2014.
* Restored the atf(7) manual page to serve as a reference to all the other
manual pages shipped by ATF.
* Added the -s flag to atf-sh to support specifying the shell interpreter
to be used.
* Removed ATF_WORKDIR. The only remaining consumers have been converted to
use the standard TMPDIR environment variable. As a benefit, and because
Kyua forces the TMPDIR to live within the test case's work directory,
any stale files left behind by ATF will be automatically cleaned up.
* Documented the environment variables recognized by each component in the
relevant manual pages. This information was lost with the atf-config(1)
removal.
* Added a new "require.diskspace" metadata property to test cases so that
they can specify the minimum amount of disk space required for the test
to run.
* Renamed the atf-{c,c++,sh}-api(3) manual pages to atf-{c,c++,sh}(3) for
discoverability purposes. Symbolic links are provided for the time
being to still make the old names visible.
* Issue #5: Recommend the (expected, actual) idiom for calls to the test
macros in the manual pages.
* Issue #7: Stopped catching unhandled exceptions in atf-c++ tests. This
propagates the crash to the caller, which in turn allows it to obtain
proper debugging information. In particular, Kyua should now be able to
extract a stacktrace pinpointing the problem.
* Issue #8: Fixed atf-c/macros_test:use test failures spotted by the clang
that ships with FreeBSD 11.0-CURRENT.
* Issue #12: Improved documentation of atf-sh(3) and atf-check(1) by better
explaining how they relate to each other.
* Issue #14: Stopped setting 'set -e' in atf-sh. This setting was
initially added as a way to enable a "strict" mode in the library and to
make test cases fail fast when they run unprotected commands. However,
doing so in the library is surprising as the responsibility of enabling
'set -e' should be on the user's code. Also, 'set -e' introduces
inconsistent behavior on subshells and users do not expect that.
* Issue #15: Fixed atf_utils_{fork,wait} to support nested calls.
* Issue #16: Fixed test failures (by removing a long-standing hack) on
systems that lack \e support in printf(1).
* Issue #19: Removed stale references to atf-config and atf-run.
2014-10-30 17:14:07 +00:00
|
|
|
the runtime engine will automatically drop the privileges if the
|
2012-09-04 23:07:32 +00:00
|
|
|
.Sq unprivileged-user
|
|
|
|
|
configuration property is set; otherwise the test case is
|
|
|
|
|
.Em skipped .
|
|
|
|
|
.It timeout
|
|
|
|
|
Type: integral.
|
|
|
|
|
Optional; defaults to
|
|
|
|
|
.Sq 300 .
|
|
|
|
|
.Pp
|
|
|
|
|
Specifies the maximum amount of time the test case can run.
|
|
|
|
|
This is particularly useful because some tests can stall either because they
|
|
|
|
|
are incorrectly coded or because they trigger an anomalous behavior of the
|
|
|
|
|
program.
|
|
|
|
|
It is not acceptable for these tests to stall the whole execution of the
|
|
|
|
|
test program.
|
|
|
|
|
.Pp
|
|
|
|
|
Can optionally be set to zero, in which case the test case has no run-time
|
|
|
|
|
limit.
|
|
|
|
|
This is discouraged.
|
|
|
|
|
.El
|
|
|
|
|
.Ss Environment
|
|
|
|
|
Every time a test case is executed, several environment variables are
|
|
|
|
|
cleared or reseted to sane values to ensure they do not make the test fail
|
|
|
|
|
due to unexpected conditions.
|
|
|
|
|
These variables are:
|
|
|
|
|
.Bl -tag -width LCXMESSAGESXX
|
|
|
|
|
.It Ev HOME
|
|
|
|
|
Set to the work directory's path.
|
|
|
|
|
.It Ev LANG
|
|
|
|
|
Undefined.
|
|
|
|
|
.It Ev LC_ALL
|
|
|
|
|
Undefined.
|
|
|
|
|
.It Ev LC_COLLATE
|
|
|
|
|
Undefined.
|
|
|
|
|
.It Ev LC_CTYPE
|
|
|
|
|
Undefined.
|
|
|
|
|
.It Ev LC_MESSAGES
|
|
|
|
|
Undefined.
|
|
|
|
|
.It Ev LC_MONETARY
|
|
|
|
|
Undefined.
|
|
|
|
|
.It Ev LC_NUMERIC
|
|
|
|
|
Undefined.
|
|
|
|
|
.It Ev LC_TIME
|
|
|
|
|
Undefined.
|
|
|
|
|
.It Ev TZ
|
|
|
|
|
Hardcoded to
|
|
|
|
|
.Sq UTC .
|
|
|
|
|
.El
|
|
|
|
|
.Ss Work directories
|
|
|
|
|
The test program always creates a temporary directory
|
|
|
|
|
and switches to it before running the test case's body.
|
|
|
|
|
This way the test case is free to modify its current directory as it
|
|
|
|
|
wishes, and the runtime engine will be able to clean it up later on in a
|
|
|
|
|
safe way, removing any traces of its execution from the system.
|
|
|
|
|
To do so, the runtime engine will perform a recursive removal of the work
|
|
|
|
|
directory without crossing mount points; if a mount point is found, the
|
|
|
|
|
file system will be unmounted (if possible).
|
|
|
|
|
.Ss File creation mode mask (umask)
|
|
|
|
|
Test cases are always executed with a file creation mode mask (umask) of
|
|
|
|
|
.Sq 0022 .
|
|
|
|
|
The test case's code is free to change this during execution.
|
|
|
|
|
.Sh SEE ALSO
|
Import atf-0.21:
Released on October 23rd, 2014.
* Restored the atf(7) manual page to serve as a reference to all the other
manual pages shipped by ATF.
* Added the -s flag to atf-sh to support specifying the shell interpreter
to be used.
* Removed ATF_WORKDIR. The only remaining consumers have been converted to
use the standard TMPDIR environment variable. As a benefit, and because
Kyua forces the TMPDIR to live within the test case's work directory,
any stale files left behind by ATF will be automatically cleaned up.
* Documented the environment variables recognized by each component in the
relevant manual pages. This information was lost with the atf-config(1)
removal.
* Added a new "require.diskspace" metadata property to test cases so that
they can specify the minimum amount of disk space required for the test
to run.
* Renamed the atf-{c,c++,sh}-api(3) manual pages to atf-{c,c++,sh}(3) for
discoverability purposes. Symbolic links are provided for the time
being to still make the old names visible.
* Issue #5: Recommend the (expected, actual) idiom for calls to the test
macros in the manual pages.
* Issue #7: Stopped catching unhandled exceptions in atf-c++ tests. This
propagates the crash to the caller, which in turn allows it to obtain
proper debugging information. In particular, Kyua should now be able to
extract a stacktrace pinpointing the problem.
* Issue #8: Fixed atf-c/macros_test:use test failures spotted by the clang
that ships with FreeBSD 11.0-CURRENT.
* Issue #12: Improved documentation of atf-sh(3) and atf-check(1) by better
explaining how they relate to each other.
* Issue #14: Stopped setting 'set -e' in atf-sh. This setting was
initially added as a way to enable a "strict" mode in the library and to
make test cases fail fast when they run unprotected commands. However,
doing so in the library is surprising as the responsibility of enabling
'set -e' should be on the user's code. Also, 'set -e' introduces
inconsistent behavior on subshells and users do not expect that.
* Issue #15: Fixed atf_utils_{fork,wait} to support nested calls.
* Issue #16: Fixed test failures (by removing a long-standing hack) on
systems that lack \e support in printf(1).
* Issue #19: Removed stale references to atf-config and atf-run.
2014-10-30 17:14:07 +00:00
|
|
|
.Xr atf-test-program 1
|
