textProtocol          package:RUnit          R Documentation(latin1)

_P_r_i_n_t_i_n_g _a _p_l_a_i_n _t_e_x_t _o_r _H_T_M_L _v_e_r_s_i_o_n _o_f _a_n _R_U_n_i_t _t_e_s_t _r_u_n _p_r_o_t_o_c_o_l.

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

     'printTextProtocol' prints a plain text protocol of a test run.
     The resulting test protocol can be configured through the function
     arguments.

     'printHTMLProtocol' prints an HTML protocol of a test run. For
     long outputs this version of the test protocol is slightly more
     readable than the plain text version due to links in the document.
     The resulting test protocol can be configured through the function
     arguments.

     'print' prints the number of executed test functions and the
     number of failures and errors.

     'summary' directly delegates the work to 'printTextProtocol'.

     'getErrors' returns a list containing the number of test
     functions, the number of deactivated functions (if there are any),
     the number of errors and the number of failures.

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

       printTextProtocol(testData, fileName = "",
                         separateFailureList = TRUE,
                         showDetails = TRUE, traceBackCutOff = 9)
       printHTMLProtocol(testData, fileName = "",
                         separateFailureList = TRUE,
                         traceBackCutOff = 9,
                         testFileToLinkMap = function(x) x )
       print.RUnitTestData(x, ...)
       summary.RUnitTestData(object, ...)
       getErrors(testData)

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

testData, x, object: objects of class 'RUnitTestData', typically
          obtained  as return value of a test run.

fileName: Connection where to print the text protocol (printing is done
          by the 'cat' command).

separateFailureList: If 'TRUE' a separate list of failures and errors
          is produced at the top of the protocol. Otherwise, the
          failures and errors are only listed in the details section.

showDetails: If 'TRUE' the protocol contains a detailed listing of all
          executed test functions.

traceBackCutOff: The details section of the test protocol contains the
          call stack for all errors. The first few entries of the
          complete stack typically contain the internal 'RUnit'
          function calls that execute the test cases and are irrelevant
          for debugging. This argument specifies how many calls are
          removed from the stack before it is written to the protocol.
          The default value is chosen such that all uninteresting
          'RUnit' calls are removed from the stack if 'runTestSuite'
          has been called from the console. This argument takes effect
          only if 'showDetails=TRUE'.

testFileToLinkMap: This function can be used to map the full name of
          the test file to a corresponding html link to be used in the
          html protocol. By default, this is the identity map.

     ...: additional arguments to summary are passed on to the
          printTextProtocol() call.

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

     The text protocol can roughly be divided into three sections with
     an increasing amount of information. The first section as an
     overview just reports the number of executed test functions and
     the number of failures and errors. The second section describes
     all test suites. Optionally, all errors and failures that occurred
     in some test suite are listed. In the optional third section
     details are given about all executed test functions in the order
     they were processed. For each test file all test functions
     executed are listed in the order they were executed. After the
     test function name the number of 'check*' function calls inside
     the test case and the execution time in seconds are stated. In the
     case of an error or failure as much debug information as possible
     is provided.

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

     Thomas Koenig, Klaus Juenemann & Matthias Burger

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

     'runTestSuite'

_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)
     ## prints detailed html protocol
     ## to standard out
     printHTMLProtocol(testResult)

     ## Not run: 
     ##  example function to add links to URL of the code files in a code
     ##  repository, here the SourceForge repository
     testFileToSFLinkMap <- function(testFileName, testDir = "tests") {
         ##  get unit test file name
         bname <- basename(testFileName)
         
         ## figure out package name
         regExp <- paste("^.*/([\.a-zA-Z0-9]*)/", testDir,"/.*$", sep = "")
         pack <- sub(regExp, "\1", testFileName)
         return(paste("http://runit.cvs.sourceforge.net/runit/",
                      pack, testDir, bname, sep = "/"))
       }

     ##  example call for a test suite run on the RUnit package
     testSuite <- defineTestSuite("RUnit", "<path-to-source-folder>/RUnit/tests",
                                  testFileRegexp = "^test.+")
     testResult <- runTestSuite(testSuite)
     printHTMLProtocol(testResult, fileName = "RUnit-unit-test-log.html",
                       testFileToLinkMap = testFileToSFLinkMap )
     ## End(Not run)

