runTestSuite          package:RUnit          R Documentation(latin1)

_D_e_f_i_n_i_t_i_o_n _a_n_d _e_x_e_c_u_t_i_o_n _o_f _R_U_n_i_t _t_e_s_t _s_u_i_t_e_s.

_D_e_s_c_r_i_p_t_i_o_n:

     'runTestSuite' is the central function of the RUnit package. Given
     one or more test suites it identifies and sources specified test
     code files one after another and executes all specified test
     functions defined therein. This is done sequentially for suites,
     test code files and test functions. During the execution
     information about the test function calls including the possible
     occurrence of failures or errors is recorded and returned at the
     end of the test run. The return object 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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

    name: The name of the test suite.

    dirs: Vector of absolute directory names where to look for test
          files.

testFileRegexp: Regular expression for test files.

testFuncRegexp: Regular expression for test functions.

 rngKind: name of a valid RNG version (see 'RNGkind').

rngNormalKind: name of a valid rnorm RNG version (see 'RNGkind').

testSuite: A single object of class test suite.

testSuites: A single object of class test suite or a list of test suite
          objects.

useOwnErrorHandler: If 'TRUE' the RUnit framework installs its own
          error handler during test case execution (but reinstalls the
          original handler before it returns). If 'FALSE' the error
          handler is not touched by RUnit but then the test protocol
          does not contain any call stacks in the case of errors.

absFileName: Absolute file name of a test function.

_D_e_t_a_i_l_s:

     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.

     _n_a_m_e A simple character string. The name of a test suite is mainly
          used to create a well structure test protocol.

     _d_i_r_s A character vector containing the absolute names of all
          directories where to look for test files.

     _t_e_s_t_F_i_l_e_R_e_g_e_x_p 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.

     _t_e_s_t_F_u_n_c_R_e_g_e_x_p 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:

     _n_T_e_s_t_F_u_n_c The number of test functions executed in the test suite.

     _n_E_r_r The number of errors that occurred during the execution.

     _n_F_a_i_l The number of failures that occurred during the execution.

     _d_i_r_s The test directories of the test suite.

     _t_e_s_t_F_i_l_e_R_e_g_e_x_p The regular expression for identifying the test
          files of the test suite.

     _t_e_s_t_F_u_n_c_R_e_g_e_x_p The regular expression for identifying the test
          functions of the test suite.

     _s_o_u_r_c_e_F_i_l_e_R_e_s_u_l_t_s 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:

     _k_i_n_d Character string with one of 'success', 'error' or 'failure'
          describing the outcome of the test function.

     _m_s_g the error message in case of an error or failure and 'NULL'
          for a successfully executed test function.

     _t_i_m_e The duration (measured in seconds) of the successful
          execution of a test function and 'NULL' in the case of an
          error or failure.

     _t_r_a_c_e_B_a_c_k 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.

_V_a_l_u_e:

     'runTestSuite' and 'runTestFile' both return an object of class
     RUnitTestData.

     'defineTestSuite' returns an object of class  'RUnitTestSuite'.

_A_u_t_h_o_r(_s):

     Thomas Koenig, Klaus Juenemann & Matthias Burger

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

     ## run some test suite
     myTestSuite <- defineTestSuite("RUnit Example",
                                    system.file("examples", package = "RUnit"),
                                    testFileRegexp = "correctTestCase.r")
     testResult <- runTestSuite(myTestSuite)

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

     ##  for single test files, e.g. outside a package context
     testResult2 <- runTestFile(file.path(system.file("examples", package = "RUnit"),
                                          "correctTestCase.r"))
     printTextProtocol(testResult2, showDetails = TRUE)

