The basic idea of the RUnit test framework is to declare a certain set
of functions to be test functions and report the results of their
execution. The test functions must not take any parameter nor return
anything such that their execution can be automatised.
The specification which functions are taken as test functions is
contained in an object of class RUnitTestSuite which is a list
with the following elements.
- name
A simple character string. The name of a test suite is mainly used
to create a well structure test protocol.
- dirs
A character vector containing the absolute names of all
directories where to look for test files.
- testFileRegexp
A regular expression specifying the test
files. All files in the test directories whose names match this
regular expression are taken as test files. Order of file names will
be alphabetical but depending on the used locale.
- testFuncRegexp
A regular expression specifying the test
functions. All functions defined in the test files whose names match
this regular expression are used as test functions. Order of test
functions will be alphabetical.
After the RUnit framework has sequentially executed all test suites it returns all
data collected during the test run as an object of class
RUnitTestData. This is a (deeply nested)
list with one list element for each executed test suite. Each of these
executed test suite lists contains the following elements:
- nTestFunc
The number of test functions executed in the test
suite.
- nErr
The number of errors that occurred during the execution.
- nFail
The number of failures that occurred during the execution.
- dirs
The test directories of the test suite.
- testFileRegexp
The regular expression for identifying the test
files of the test suite.
- testFuncRegexp
The regular expression for identifying the test
functions of the test suite.
- sourceFileResults
A list containing the results for each
separate test file of the test suite.
The sourceFileResults list just mentioned contains one element
for each specified test function in the source file. This element is a list with
the following entries:
- kind
Character string with one of success, error or
failure describing the outcome of the test function.
- msg
the error message in case of an error or failure and
NULL for a successfully executed test function.
- time
The duration (measured in seconds) of the successful
execution of a test function and NULL in the case of an error
or failure. When running with gcBeforeTest option
set to FALSE (default since 0.4.32), the timing of the tests might
be misleading when garbage collector has to reclaim memory allocated by
a previous test.
- traceBack
The full trace back as a character vector in the case of an
error and NULL otherwise.
To further control test case execution it is possible to define two
parameterless function .setUp and .tearDown in each
test file. .setUp() is executed directly before and
.tearDown() directly after each test function execution.
Quite often, it is useful to base test cases on random numbers. To
make this procedure reproducible, the function runTestSuite
sets the random number generator to the default setting
RNGkind(kind="Marsaglia-Multicarry",
normal.kind="Kinderman-Ramage") before sourcing each test file
(note that this default has been chosen due to historical reasons and
differs from the current R default). This default can be overwritten
by configuring the random number generator at the beginning of a test
file. This setting, however, is valid only inside its own source file
and gets overwritten when the next test file is sourced.