R: Test whether expected stop() or warning() messages are...

expectStop {splus2R} | R Documentation

## Test whether expected stop() or warning() messages are produced.

### Description

These functions are for use in automated testing using `do.test`, to test whether function give specified `stop` and `warning` messages.

### Usage

    expectStop(expr, expected = NULL)
    expectWarnings(expr, expected)

### Arguments

`expr` | An expression, that should result in a call to `stop()` or `warning()`.
`expected` | `NULL`, or a character string containing (part of) the message expected from `stop`. For `expectWarnings` a vector of character strings containing (parts of) all expected warnings.

### Details

`expectStop` is useful for checking error checking; that a function stops when it should, and gives the right message. For example, this may be in a file called by do.test:

    {
      expectStop(var(1:5, 1:4),
                 if(is.R()) "incompatible"
                 else "x and y must have the same number of")
    }

The function returns `TRUE` if

- a stop() occurs, and

- the error message is expected.

Otherwise it returns appropriate messages.

`expectStop` intercepts the error. Execution continues, and assignments made earlier are committed.

Similarly, `expectWarnings` is useful to check that a function gives appropriate warnings. For example, this may be in a file called by do.test:

    expectWarnings(
      {
        object1 <- (code generating warning messages);
        object2 <- (code generating possibly other warning messages);
        all.equal(object1, object2)
      },
      c("expected warning 1",
        "expected warning 2"))

The function returns `TRUE` if

- expr evaluates to `TRUE`; and

- each warning message produced by evaluating expr contains as a substring an element of expected, and each element of expected is a substring of at least one of the produced warning messages.

Otherwise it returns a list with components describing the test failures. Normal printing of warning messages is suppressed.

It is possible to test for warnings and a stop in a single expression, by nesting calls to the two functions.

### Value

If all tests pass, then `TRUE`. Otherwise `expectStop` returns character strings describing the failure, while `expectWarnings` returns a list with one or more of the following components:

`'Test result'` | the value (if not `TRUE`) returned by evaluating `expr`.
`'Unexpected warnings'` | character vector of actual warning messages that were not listed in `expected`.
`'Warnings expected but not found'` | character vector of messages in `expected` that were not produced.

### Author(s)

Tim Hesterberg

### See Also

`do.test`

### Examples

    # Expressions like the following would typically be included in a file
    # that is called by do.test

    expectStop(lm(5), expected = "invalid formula")

    expectStop(cov2cor( matrix(2:1) ),
               expected = "'V' is not a square numeric matrix")

    expectWarnings( # Test subscript replacement; should discard extra
                    # column and give a warning
      {
        x <- data.frame(a=1:3,b=2:4)
        x[,3] <- x
        all.equal(ncol(x), 3)
      },
      expected = "provided 2 variables to replace 1 var")

    # Test for a warning and stop together:
    {
      f <- function(x){
        warning("a warning")
        stop("a stop")
      }
      expectStop( expectWarnings( f(3), expected = "a warning"),
                  expected = "a stop")
    }
    # The definition of f and the call to expectStop are included here
    # within {} because that is how they would typically be grouped in
    # a file that is called by do.test.  Also note that f has been saved
    # (the assignment of f is committed, rather than aborted).

[Package splus2R version 1.2-2 Index]