R: Expectation: does code throw error or other condition?

expect_error {testthat} | R Documentation

## Expectation: does code throw error or other condition?

### Description

`expect_error()` and `expect_condition()` check that code throws an error or condition with a message that matches `regexp`, or a class that inherits from `class`. See below for more details.

### Usage

    expect_error(
      object,
      regexp = NULL,
      class = NULL,
      ...,
      info = NULL,
      label = NULL
    )

    expect_condition(
      object,
      regexp = NULL,
      class = NULL,
      ...,
      info = NULL,
      label = NULL
    )

### Arguments

`object` | Object to test. Supports limited unquoting to make it easier to generate readable failures within a function or for loop. See quasi_label for more details.
`regexp` | Regular expression to test against. A character vector giving a regular expression that must match the error message. If `NULL`, the default, asserts that there should be a error, but doesn't test for a specific value. If `NA`, asserts that there should be no errors.
`class` | Instead of supplying a regular expression, you can also supply a class name. This is useful for "classed" conditions.
`...` | Arguments passed on to `expect_match` `all` Should all elements of actual value match `regexp` (TRUE), or does only one need to match (FALSE) `perl` logical. Should Perl-compatible regexps be used? `fixed` logical. If `TRUE`, `pattern` is a string to be matched as is. Overrides all conflicting arguments.
`info` | Extra information to be included in the message. This argument is soft-deprecated and should not be used in new code. Instead see alternatives in quasi_label.
`label` | Used to customise failure messages. For expert use only.

### Value

If `regexp = NA`, the value of the first argument; otherwise the captured condition.

### Testing `message` vs `class`

When checking that code generates an error, it's important to check that the error is the one you expect. There are two ways to do this. The first way is the simplest: you just provide a `regexp` that match some fragment of the error message. This is easy, but fragile, because the test will fail if the error message changes (even if its the same error).

A more robust way is to test for the class of the error, if it has one. You can learn more about custom conditions at https://adv-r.hadley.nz/conditions.html#custom-conditions, but in short, errors are S3 classes and you can generate a custom class and check for it using `class` instead of `regexp`. Because this is a more reliable check, you `expect_error()` will warn if the error has a custom class but you are testing the message. Eliminate the warning by using `class` instead of `regexp`. Alternatively, if you think the warning is a false positive, use `class = "error"` to suppress it for any input.

If you are using `expect_error()` to check that an error message is formatted in such a way that it makes sense to a human, we now recommend using `verify_output()` instead.

### See Also

Other expectations: `comparison-expectations`, `equality-expectations`, `expect_length()`, `expect_match()`, `expect_message()`, `expect_named()`, `expect_null()`, `expect_output()`, `expect_silent()`, `inheritance-expectations`, `logical-expectations`

### Examples

    f <- function() stop("My error!")
    expect_error(f())
    expect_error(f(), "My error!")

    # You can use the arguments of grepl to control the matching
    expect_error(f(), "my error!", ignore.case = TRUE)

    # If you are working with classed conditions, it's better to test for
    # the class name, rather than the error message (which may change over time)
    custom_err <- function(var) {
      rlang::abort("A special error", var = var, .subclass = "testthat_special")
    }
    expect_error(custom_err("a"), class = "testthat_special")

    # Note that `expect_error()` returns the error object so you can test
    # its components if needed
    err <- expect_error(custom_err("a"), class = "testthat_special")
    expect_equal(err$var, "a")

[Package testthat version 2.3.2 Index]