File: mocks-and-testthat.Rmd

package info (click to toggle)
r-cran-mockery 0.4.2+dfsg-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 172 kB
  • sloc: sh: 13; makefile: 2
file content (252 lines) | stat: -rw-r--r-- 6,157 bytes parent folder | download | duplicates (2)
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
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
---
title: 'Mocks: Integrating with `testthat`'
author: "Lukasz A. Bartnik"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Mocks: Integrating with testthat}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r include=FALSE}
library(mockery)

library(knitr)
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```


Mock object, which is a part of the `mockery` package, started as an
extension to [testthat](https://github.com/r-lib/testthat)'s `with_mock()`
facility. Its main purpose was to simplify the replacement (mocking)
of a given function by means of `with_mock` and the later
verification of actual calls invoked on the replacing function.

The `mockery` package which provides its own stubbing facility, the
`stub()` function. Here, however, we will look only at how `mock()`
can be used together with `with_mock()`.


## Mocks

### Creating a `mock` function

Mocking is a well-known technique when it comes to unit-testing and in
most languages there is some notion of a mock object. In R, however, the
natural equivalent of a mock object is a mock _function_ - and this is
exactly what a call to `mock()` will produce.

```{r create_mock}
m <- mock()
```


### Return values

Let's look at arguments accepted by the `mock()` _factory_ function. The
main is a list of values which will be returned upon subsequent calls to
`m`.

```{r return_values}
m <- mock(1, 2, 3)
m()
m()
m()
```

`mock()` can take also an expression which will be evaluated upon a call.

```{r return_expression}
x <- 1
y <- 2
m <- mock(x + y)
m()
```


### Cycling through return values

By default, if the total number of calls exceeds the number of defined
return values, the _mock_ function will throw an exception. However, one
can also choose to cycle through the list of retun values by setting the
`cycle` argument of `mock()` to `TRUE`.

```{r cycle_no, eval=FALSE}
m <- mock(1, 2)
m()
#> [1] 1
m()
#> [1] 2
m()
#> Error: too many calls to mock object and cycle set to FALSE
```

```{r cycle_true}
m <- mock(1, 2, cycle = TRUE)
m()
m()
m()
m()
```


If a return value is defined by an expression, this expression will be
evaluated each time a cycle reaches its position.

```{r cycle_expression}
x <- 1
y <- 2
m <- mock(1, x + y, cycle = TRUE)

m()
m()
```
```{r cycle_expression_2nd}
y <- 10
m()
m()
```


### Evaluating expression in an environment of choice

Finally, one can specify the environment where the return expression is
evaluated.

```{r return_expression_env}
x <- 1
y <- 2
e <- new.env()
m <- mock(x + y, envir = e, cycle = TRUE)

m()
e$x <- 10
m()
```


## Integration with `with_mock()`

### Simple integration

Using mock functions with `testthat`'s `with_mock()` is pretty
straightforward.

```{r with_mock, message=FALSE}
library(testthat)

m <- mock(1)
f <- function (x) summary(x)
with_mock(f = m, {
  expect_equal(f(iris), 1)
})
```


### Verifying the number of calls

The `mockery` package comes with a few additional expectations which
might turn out to be a very useful extension to `testthat`'s API. One
can for example verify the number and signature of calls invoked on a
mock function, as well as the values of arguments passed in those calls.

First, let's make sure the mocked function is called exactly as many
times as we expect. This can be done with `expect_called()`.

```{r expect_called}
m <- mock(1, 2)

m()
expect_called(m, 1)

m()
expect_called(m, 2)
```

And here is what happens when we get the number of calls wrong.

```{r expect_called_error, eval=FALSE}
expect_called(m, 1)
#> Error: mock object has not been called 1 time.
expect_called(m, 3)
#> Error: mock object has not been called 3 times.
```

### Verify the call signature

Another new expectation is `expect_call()` which compares the signature
of the actual call as invoked on the mock function with the expected one.
It takes as arguments: the mock function, the call number, expected call.

```{r expect_call}
m <- mock(1)
with_mock(summary = m, {
  summary(iris)
})

expect_call(m, 1, summary(iris))
```

And here is what happens if the call doesn't match.

```{r call_doesnt_match, eval=FALSE}
expect_call(m, 1, summary(x))
#> Error: expected call summary(x) does not mach actual call summary(iris).
```

### Verify values of argument

Finally, one can verify whether the actual values of arguments passed
to the mock function match the expectation. Following the previous
example of `summary(iris)` we can make sure that the `object` parameter
passed to `m()` was actually the `iris` dataset.

```{r expect_args}
expect_args(m, 1, iris)
```

Here is what happens if the value turns out to be different.

```{r expect_args_different, eval=FALSE}
expect_args(m, 1, iris[-1, ])
#> Error: arguments to call #1 not equal to expected arguments.
#> Component 1: Attributes: < Component "row.names": Numeric: lengths (150, 149) differ >
#> Component 1: Component 1: Numeric: lengths (150, 149) differ
#> Component 1: Component 2: Numeric: lengths (150, 149) differ
#> Component 1: Component 3: Numeric: lengths (150, 149) differ
#> Component 1: Component 4: Numeric: lengths (150, 149) differ
#> Component 1: Component 5: Lengths: 150, 149
#> Component 1: Component 5: Lengths (150, 149) differ (string compare on first 149)
#> Component 1: Component 5: 2 string mismatches
#> expected argument list does not mach actual one.
```

If the call has been made with an explicit argument name the same has
to appear in `expect_args()`.

```{r expect_args_named}
m <- mock(1)
with_mock(summary = m, {
  summary(object = iris)
})

expect_args(m, 1, object = iris)
```

Omitting the name results in an error.

```{r expect_args_unnamed, eval=FALSE}
expect_args(m, 1, iris)
#> Error: arguments to call #1 not equal to expected arguments.
#> names for target but not for current
#> expected argument list does not mach actual one.
```


## Further reading

More information can be found in examples presented in manual pages
for `?mock` and `?expect_call`. Extensive information about testing
in R can be found in the documentation for the
[testthat](https://github.com/r-lib/testthat) package.