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
properties 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 conditions.
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.
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 status 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.
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.
- descr
-
Type: textual.
Required.
A brief textual description of the test case's purpose.
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'.
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.
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)