---
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 = "#>")
summary <- NULL

# pretend we're testing a package
Sys.setenv(TESTTHAT = "true")
Sys.setenv(TESTTHAT_PKG = "mockery")
```

Mock object, which is a part of the `mockery` package, started as an
extension to [testthat](https://github.com/r-lib/testthat)'s `with_mocked_bindings()`
facility. Its main purpose was to simplify the replacement (mocking)
of a given function by means of `with_mocked_bindings` 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_mocked_bindings()`.


## 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}
#| error: true
m <- mock(1, 2)
m()
m()
m()
```

```{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_mocked_bindings()`

### Simple integration

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

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

m <- mock(1)
f <- function (x) summary(x)
with_mocked_bindings(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}
#| error: true
expect_called(m, 1)
expect_called(m, 3)
```

### 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_mocked_bindings(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}
#| error: true
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}
#| error: true
expect_args(m, 1, iris[-1, ])
```

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

```{r expect_args_named}
#| error: true
m <- mock(1)
with_mocked_bindings(summary = m, {
  summary(object = iris)
})

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

Omitting the name results in an error.

```{r expect_args_unnamed}
#| error: true
expect_args(m, 1, iris)
```


## 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.