checkFuncs           package:RUnit           R Documentation(latin1)

_R_U_n_i_t _c_h_e_c_k _f_u_n_c_t_i_o_n_s

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

     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.

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

     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=FALSE)
     DEACTIVATED(msg)

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

current, target: two objects to be compared (should not be 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.

     ...: optional arguments passed to 'all.equal' or
          'all.equal.numeric'

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

     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 packagename 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
     examples/runitVirtualClassTest.r.

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

     Thomas Koenig, Klaus Juenemann & Matthias Burger

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

     'all.equal', 'all.equal.numeric' and 'identical' are the
     underlying comparison functions. 'try' is used for error catching.

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

     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 f raises no error
     checkException(fun(TRUE), silent=TRUE)

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

