checkFuncs: RUnit check functions
In romanzenka/RUnit: R Unit Test Framework

checkFuncs

R Documentation

RUnit check functions

Description

A set of functions used to check the results of some test calculation. If these functions are called within the RUnit framework, the results of the checks are stored and reported in the test protocol.

checkEquals compares two R objects by invoking all.equal on the two objects. If the objects are not equal an error is generated and the failure is reported to the test logger such that it appears in the test protocol.

checkEqualsNumeric works just like checkEquals except that it invokes all.equal.numeric instead of all.equal

checkIdentical is a convenience wrapper around identical using the error logging mechanism of RUnit.

checkTrue uses the function identical to check if the expression provided as first argument evaluates to TRUE. If not, an error is generated and the failure is reported to the test logger such that it appears in the test protocol.

checkException evaluates the passed expression and uses the try mechanism to check if the evaluation generates an error. If it does the test is OK. Otherwise an error is generated and the failure is reported to the test logger such that it appears in the test protocol.

DEACTIVATED interrupts the test function and reports the test case as deactivated. In the test protocol deactivated test functions are listed separately. Test case deactivation can be useful in the case of major refactoring. Alternatively, test cases can be commented out completely but then it is easy to forget the test case altogether.

Usage

checkEquals(target, current, msg,
            tolerance = .Machine$double.eps^0.5, 
            checkNames = TRUE, ...)
checkEqualsNumeric(target, current, msg,
                   tolerance = .Machine$double.eps^0.5, ...)
checkIdentical(target, current, msg)
checkTrue(expr, msg)
checkException(expr, msg, silent = getOption("RUnit")$silent)
DEACTIVATED(msg)

Arguments

`current, target`	objects to be compared (`checkEqualsNumeric` cannot handle S4 class objects).
`msg`	an optional message to document a check and to facilitate the identification of a possible failure. The message only appears as text in the test protocol, it is not further used in any of the check functions.
`tolerance`	numeric >= 0. A numeric check does not fail if differences are smaller than ‘tolerance’.
`checkNames`	flag, if `FALSE` the names attributes are set to `NULL` for both current and target before performing the check.
`expr`	syntactically valid R expression which can be evaluated and must return a logical scalar (`TRUE`\|`FALSE`). A named expression is also allowed but the name is disregarded.
`silent`	flag passed on to `try`, which determines if the error message generated by the checked function is displayed. Queried from global options set for RUnit at package load.
`...`	optional arguments passed to `all.equal` or `all.equal.numeric`

Details

The check functions are direct equivalents of the various methods of the class junit.framework.Assert of Javas JUnit framework which served as basis for the RUnit package.

For functions defined inside a package equipped with a namespace only exported functions can be accessed inside test cases directly. For functions not exported the only way to test them is to use the ':::' operator combined with the package name as a prefix.

Special care is required if test cases are written for S4 classes and methods. If a new class is defined inside a test case via a setClass call the class is added to the global class cache and thus available outside the test case. It will persist until explicitly removed via a removeClass call. Same applies for new method and generic definitions. Be sure to remove methods and classes in each test case they are defined after the checks have been performed. This is an advise gained from the cumbersome experience: not doing so leads to difficult to pin down error causes incurred from previously executed test cases. For a simple example see the provided test cases in \Sexpr{file.path(system.file("examples", package="RUnit"), "runitVirtualClassTest.r")}.

Author(s)

Thomas König, Klaus Jünemann & Matthias Burger

Examples


checkTrue(1 < 2, "check1")     ## passes fine
## checkTrue(1 > 2, "check2")  ## appears as failure in the test protocol

v <- 1:3
w <- 1:3
checkEquals(v, w)               ## passes fine
names(v) <- c("A", "B", "C")
## checkEquals(v, w)            ## fails because v and w have different names
checkEqualsNumeric(v, w)        ## passes fine because names are ignored


x <- rep(1:12, 2)
y <- rep(0:1, 12)
res <- list(a=1:3, b=letters, LM=lm(y ~ x))
res2 <- list(a=seq(1,3,by=1), b=letters, LM=lm(y ~ x))
checkEquals( res, res2)        ## passes fine
checkIdentical( res, res)
checkIdentical( res2, res2)
## checkIdentical( res, res2)  ## fails because element 'a' differs in type


fun <- function(x) {
  if(x)
  {
   stop("stop conditions signaled")
  }
  return()
}

checkException(fun(TRUE))      ## passes fine
## checkException(fun(FALSE))  ## failure, because fun raises no error
checkException(fun(TRUE), silent=TRUE)

##  special constants
##  same behaviour as for underlying base functions
checkEquals(NA, NA)
checkEquals(NaN, NaN)
checkEquals(Inf, Inf)

checkIdentical(NA, NA)
checkIdentical(NaN, NaN)
checkIdentical(-Inf, -Inf)

## DEACTIVATED("here one can document on the reason for deactivation")

romanzenka/RUnit documentation built on Feb. 23, 2024, 1:26 p.m.