atf-test-case(4)
- NetBSD Manual Pages
ATF-TEST-CASE(8) NetBSD System Manager's Manual ATF-TEST-CASE(8)
NAME
atf-test-case -- generic description of test cases
DESCRIPTION
A 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.
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 header
is, basically, a declarative piece of code that defines several proper-
ties to describe what the test case does and how it behaves. In other
words: it defines the test case's meta-data, further described in the
Meta-data section. The 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 cleanup routine 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.
It is extremely important to keep the separation between a test case's
header and body well-defined, because the header is 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.
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.
Results
A test case always exits with one of the following results:
passed The test case was executed successfully.
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 con-
ditions. This is always accompanied by a reason, a message
describing why the test was skipped.
failed An error appeared during the execution of the test case. This
is always accompanied by a reason, a message describing why
the test failed.
Input/output
Test cases are free to print whatever they want to their stdout(4) and
stderr(4) file descriptors. They are, in fact, encouraged to print sta-
tus information as they execute to keep the user informed of their
actions. This is specially important for long test cases.
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.
Meta-data
The following list describes all meta-data properties interpreted inter-
nally by ATF. You are free to define new properties in your test cases
and use them as you wish.
descr Type: textual. Required.
A brief textual description of the test case's pur-
pose. Will be shown to the user in reports. Also
good for documentation purposes.
ident Type: textual. Required.
The test case's identifier. Must be unique inside the
test program and should be short but descriptive.
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.
require.config Type: textual. Optional.
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 skipped.
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.
require.progs Type: textual. Optional.
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 PATH, or as absolute paths. If any of the
required programs is not found, the test case is
skipped.
require.user Type: textual. Optional.
The required privileges to execute the test case. Can
be one of `root' or `unprivileged'. If the requested
privileges do not match the current user, the test
case is skipped.
NOTE: In the future, it is expected that the test case
will attempt to gain the necessary privileges on its
own before failing. At the very least, lowering the
privileges from the super-user to an unprivileged user
will be supported.
timeout Type: integral. Required; defaults to `300'. Speci-
fies 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 pro-
gram. It is not acceptable for these tests to stall
the whole execution of the test program.
Can optionally be set to zero, in which case the test
case has no run-time limit. This is discouraged.
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:
HOME Set to the work directory's path.
LANG Undefined.
LC_ALL Undefined.
LC_COLLATE Undefined.
LC_CTYPE Undefined.
LC_MESSAGES Undefined.
LC_MONETARY Undefined.
LC_NUMERIC Undefined.
LC_TIME Undefined.
TZ Undefined.
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 test program will be
able to clean it up later on in a safe way, removing any traces of its
execution from the system.
File creation mode mask (umask)
Test cases are always executed with a file creation mode mask (umask) of
`0022'. The test case's code is free to change this during execution.
SEE ALSO
atf-test-program(1), atf-formats(5), atf(7)
NetBSD 5.0 January 15, 2008 NetBSD 5.0
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.