checkFuncs               package:RUnit               R Documentation

_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 loggin mechanism or 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 check does not fail if differences 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.

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

     Thomas K\"onig, Klaus J\"unemann & 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)          ## pasess 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

     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")

