RUnit (version 0.4.12)

runTestSuite: Definition and execution of RUnit test suites.

Description

runTestSuite is the central function of the RUnit package. Given one or more test suites it sources all test files and then executes all test functions as defined by the test suites. During the execution information about the test function calls including the possible occurence of failures or errors is stored and returned at the end of the test run. The return value can then be used to create a test protocol of various formats.

runTestFile is just a convenience function for executing the tests in a single test file.

defineTestSuite is a helper function to define a test suite. See below for a precise definition of a test suite.

isValidTestSuite checks if an object defines a valid test suite.

Usage

defineTestSuite(name, dirs, testFileRegexp="^runit.+\.[rR]$", testFuncRegexp="^test.+")
isValidTestSuite(testSuite)
runTestSuite(testSuites, useOwnErrorHandler=TRUE)
runTestFile(absFileName, useOwnErrorHandler=TRUE, testFuncRegexp="^test.+")

Value

runTestSuite and runTestFile both return an object of class RUnitTestData.

defineTestSuite returns an object of class RUnitTestSuite.

concept

RUnit

Details

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 important 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 name match this regular expression are taken as test files.} 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}

After the RUnit framework has executed all test suites it returns all data collected during the test run as an object of class RUnitTestData. This is a (unfortunately rather 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 occured during the execution.} nFail{The number of failures that occured 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 test function ion the source file. This elemnt is a list with the following entries: kind{One of success, error or failure describing the outcome of the test function.} msg{the error message in the case of an error or failure and NULL for a successful 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.} 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 a test file. .setUp() is executed directly before and .tearDown() directly after each test function.

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.

See Also

checkTrue and friends for writing test cases. printTextProtocol and printHTMLProtocol for printing the test protocol.

Examples

## run some test suite
myTestSuite <- defineTestSuite("my test suite", "tests")
testData <- runTestSuite(myTestSuite)

## prints detailed text protocol
## to standard out:
printTextProtocol(testData, showDetails=TRUE)