R Graphical Manual

Browse All

Last data update: 2014.03.03

R: Printing a plain text, HTML or JUnit-like XML version of an...

textProtocol

R Documentation

Printing a plain text, HTML or JUnit-like XML version of an RUnit test run protocol.

Description

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.

printJUnitProtocol prints a JUnit-style XML protocol of a test run. This feature is especially useful when running your RUnit tests through a continuous integration server that understands JUnit (like Jenkins). This machine-parseable output allows you to track errors over time, sort by execution time and similar useful tricks. To take advantage of this function, you have to have the XML package installed.

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.

Usage

  printTextProtocol(testData, fileName = "",
                    separateFailureList = TRUE,
                    showDetails = TRUE, traceBackCutOff = 9)
  printHTMLProtocol(testData, fileName = "",
                    separateFailureList = TRUE,
                    traceBackCutOff = 9,
                    testFileToLinkMap = function(x) x )
  printJUnitProtocol(testData, fileName = "")
  ## S3 method for class 'RUnitTestData'
print(x, ...)
  ## S3 method for class 'RUnitTestData'
summary(object, ...)
  getErrors(testData)

Arguments

`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. See example below.
`...`	additional arguments to summary are passed on to the printTextProtocol() call.

Details

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.

Author(s)

Thomas KÃ¶nig, Klaus JÃ¼nemann, Matthias Burger & Roman Zenka

Examples


## 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)
## prints JUnit-style XML protocol
## to standard out. 
## You need to have XML package installed for this
if(require("XML")) {
  printJUnitProtocol(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)

Results


R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(RUnit)
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/RUnit/textProtocol.Rd_%03d_medium.png", width=480, height=480)
> ### Name: textProtocol
> ### Title: Printing a plain text, HTML or JUnit-like XML version of an
> ###   RUnit test run protocol.
> ### Aliases: printTextProtocol printHTMLProtocol printJUnitProtocol
> ###   print.RUnitTestData summary.RUnitTestData getErrors
> ### Keywords: programming
> 
> ### ** Examples
> 
> 
> ## run some test suite
> myTestSuite <- defineTestSuite("RUnit Example",
+                                system.file("examples", package = "RUnit"),
+                                testFileRegexp = "correctTestCase.r")
> testResult <- runTestSuite(myTestSuite)


Executing test function test.correctTestCase  ...  done successfully.

> 
> 
> ## prints detailed text protocol
> ## to standard out:
> printTextProtocol(testResult, showDetails = TRUE)
RUNIT TEST PROTOCOL -- Mon Jul  4 23:56:46 2016 
*********************************************** 
Number of test functions: 1 
Number of errors: 0 
Number of failures: 0 

 
1 Test Suite : 
RUnit Example - 1 test function, 0 errors, 0 failures



Details 
*************************** 
Test Suite: RUnit Example 
Test function regexp: ^test.+ 
Test file regexp: correctTestCase.r 
Involved directory: 
/home/ddbj/local/lib64/R/library/RUnit/examples 
--------------------------- 
Test file: /home/ddbj/local/lib64/R/library/RUnit/examples/correctTestCase.r 
test.correctTestCase: (2 checks) ... OK (0 seconds)
> ## prints detailed html protocol
> ## to standard out
> printHTMLProtocol(testResult)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/transitional.dtd">
<html><head><title>RUNIT TEST PROTOCOL--Mon Jul  4 23:56:46 2016</title>
</head>
<body><h1 TRUE>RUNIT TEST PROTOCOL--Mon Jul  4 23:56:46 2016</h1>
<p>Number of test functions: 1</p>
<p>Number of errors: 0</p>
<p>Number of failures: 0</p>
<hr>
<h3 TRUE>1 Test suite</h3>
<table border="1" width="60%" >
<tr><th width="30%">Name</th>
<th width="30%">Test functions</th>
<th width="20%">Errors</th>
<th width="20%">Failures</th>
</tr>
<tr><td><a href="#RUnit Example">RUnit Example</a></td>
<td>1</td>
<td>0</td>
<td>0</td>
</tr>
</table>
<hr>
<h3 TRUE>Details</h3>
<p><a name="RUnit Example"><h5 TRUE>Test Suite: RUnit Example</h5>
</a>Test function regexp: ^test.+<br/>Test file regexp: correctTestCase.r<br/>Involved directory:<br/>/home/ddbj/local/lib64/R/library/RUnit/examples<br/><ul><li><a href="/home/ddbj/local/lib64/R/library/RUnit/examples/correctTestCase.r">Test file: correctTestCase.r</a><ul><li><a name="RUnit Example__home_ddbj_local_lib64_R_library_RUnit_examples_correctTestCase.r_test.correctTestCase">test.correctTestCase: (2 checks) ... OK (0 seconds)<br/></a></li></ul></li></ul><hr>
<table border="0" width="80%" >
<tr><th>Name</th>
<th>Value</th>
</tr>
<tr><td>platform</td>
<td>x86_64-pc-linux-gnu</td>
</tr>
<tr><td>arch</td>
<td>x86_64</td>
</tr>
<tr><td>os</td>
<td>linux-gnu</td>
</tr>
<tr><td>system</td>
<td>x86_64, linux-gnu</td>
</tr>
<tr><td>status</td>
<td></td>
</tr>
<tr><td>major</td>
<td>3</td>
</tr>
<tr><td>minor</td>
<td>3.1</td>
</tr>
<tr><td>year</td>
<td>2016</td>
</tr>
<tr><td>month</td>
<td>06</td>
</tr>
<tr><td>day</td>
<td>21</td>
</tr>
<tr><td>svn rev</td>
<td>70800</td>
</tr>
<tr><td>language</td>
<td>R</td>
</tr>
<tr><td>version.string</td>
<td>R version 3.3.1 (2016-06-21)</td>
</tr>
<tr><td>nickname</td>
<td>Bug in Your Hair</td>
</tr>
<tr><td>host</td>
<td>rgm-mini</td>
</tr>
<tr><td>compiler</td>
<td>g++</td>
</tr>
</table>
</body>
</html>
> ## prints JUnit-style XML protocol
> ## to standard out. 
> ## You need to have XML package installed for this
> if(require("XML")) {
+   printJUnitProtocol(testResult)
+ }
Loading required package: XML
<testsuites errors="0" failures="0" tests="1">
  <testsuite errors="0" failures="0" name="RUnit Example" tests="1">
    <testcase name="test.correctTestCase" time="0"/>
  </testsuite>
</testsuites>
> 
> ## Not run: 
> ##D ##  example function to add links to URL of the code files in a code
> ##D ##  repository, here the SourceForge repository
> ##D testFileToSFLinkMap <- function(testFileName, testDir = "tests") {
> ##D     ##  get unit test file name
> ##D     bname <- basename(testFileName)
> ##D     
> ##D     ## figure out package name
> ##D     regExp <- paste("^.*/([.a-zA-Z0-9]*)/", testDir,"/.*$", sep = "")
> ##D     pack <- sub(regExp, "1", testFileName)
> ##D     return(paste("http://runit.cvs.sourceforge.net/runit/",
> ##D                  pack, testDir, bname, sep = "/"))
> ##D   }
> ##D 
> ##D 
> ##D ##  example call for a test suite run on the RUnit package
> ##D testSuite <- defineTestSuite("RUnit", "<path-to-source-folder>/RUnit/tests",
> ##D                              testFileRegexp = "^test.+")
> ##D testResult <- runTestSuite(testSuite)
> ##D printHTMLProtocol(testResult, fileName = "RUnit-unit-test-log.html",
> ##D                   testFileToLinkMap = testFileToSFLinkMap )
> ## End(Not run)
> 
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>