1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-condition.R
\name{expect_error}
\alias{expect_error}
\alias{expect_warning}
\alias{expect_message}
\alias{expect_condition}
\title{Does code throw an error, warning, message, or other condition?}
\usage{
expect_error(
object,
regexp = NULL,
class = NULL,
...,
info = NULL,
label = NULL
)
expect_warning(
object,
regexp = NULL,
class = NULL,
...,
all = FALSE,
info = NULL,
label = NULL
)
expect_message(
object,
regexp = NULL,
class = NULL,
...,
all = FALSE,
info = NULL,
label = NULL
)
expect_condition(
object,
regexp = NULL,
class = NULL,
...,
info = NULL,
label = NULL
)
}
\arguments{
\item{object}{Object to test.
Supports limited unquoting to make it easier to generate readable failures
within a function or for loop. See \link{quasi_label} for more details.}
\item{regexp}{Regular expression to test against.
\itemize{
\item A character vector giving a regular expression that must match the
error message.
\item If \code{NULL}, the default, asserts that there should be a error,
but doesn't test for a specific value.
\item If \code{NA}, asserts that there should be no errors.
}}
\item{class}{Instead of supplying a regular expression, you can also supply
a class name. This is useful for "classed" conditions.}
\item{...}{
Arguments passed on to \code{\link[=expect_match]{expect_match}}
\describe{
\item{\code{perl}}{logical. Should Perl-compatible regexps be used?}
\item{\code{fixed}}{logical. If \code{TRUE}, \code{pattern} is a string to be
matched as is. Overrides all conflicting arguments.}
}}
\item{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 \link{quasi_label}.}
\item{label}{Used to customise failure messages. For expert use only.}
\item{all}{\emph{DEPRECATED} If you need to test multiple warnings/messages
you now need to use multiple calls to \code{expect_message()}/
\code{expect_warning()}}
}
\value{
If \code{regexp = NA}, the value of the first argument; otherwise
the captured condition.
}
\description{
\code{expect_error()}, \code{expect_warning()}, \code{expect_message()}, and
\code{expect_condition()} check that code throws an error, warning, message,
or condition with a message that matches \code{regexp}, or a class that inherits
from \code{class}. See below for more details.
In the 3rd edition, these functions match a single condition. All
additional and non-matching (if \code{regexp} or \code{class} are used) conditions
will bubble up outside the expectation. If these additional conditions
are important you'll need to catch them with additional
\code{expect_message()}/\code{expect_warning()} calls; if they're unimportant you
can ignore with \code{\link[=suppressMessages]{suppressMessages()}}/\code{\link[=suppressWarnings]{suppressWarnings()}}.
}
\section{Testing \code{message} vs \code{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 \code{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
\url{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 \code{class} instead of \code{regexp}.
If you are using \code{expect_error()} to check that an error message is
formatted in such a way that it makes sense to a human, we recommend
using \code{\link[=expect_snapshot]{expect_snapshot()}} instead.
}
\examples{
# Errors ------------------------------------------------------------------
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)
# Note that `expect_error()` returns the error object so you can test
# its components if needed
err <- expect_error(rlang::abort("a", n = 10))
expect_equal(err$n, 10)
# Warnings ------------------------------------------------------------------
f <- function(x) {
if (x < 0) {
warning("*x* is already negative")
return(x)
}
-x
}
expect_warning(f(-1))
expect_warning(f(-1), "already negative")
expect_warning(f(1), NA)
# To test message and output, store results to a variable
expect_warning(out <- f(-1), "already negative")
expect_equal(out, -1)
# Messages ------------------------------------------------------------------
f <- function(x) {
if (x < 0) {
message("*x* is already negative")
return(x)
}
-x
}
expect_message(f(-1))
expect_message(f(-1), "already negative")
expect_message(f(1), NA)
}
\seealso{
Other expectations:
\code{\link{comparison-expectations}},
\code{\link{equality-expectations}},
\code{\link{expect_length}()},
\code{\link{expect_match}()},
\code{\link{expect_named}()},
\code{\link{expect_null}()},
\code{\link{expect_output}()},
\code{\link{expect_reference}()},
\code{\link{expect_silent}()},
\code{\link{inheritance-expectations}},
\code{\link{logical-expectations}}
}
\concept{expectations}
|
