# Mocks: Integrating with testthat

#### 2019-09-03

Mock object, which is a part of the mockery package, started as an extension to 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.

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.

m <- mock(1, 2, 3)
m()
#> [1] 1
m()
#> [1] 2
m()
#> [1] 3

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

x <- 1
y <- 2
m <- mock(x + y)
m()
#> [1] 3

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

m <- mock(1, 2)
m()
#> [1] 1
m()
#> [1] 2
m()
#> Error: too many calls to mock object and cycle set to FALSE
m <- mock(1, 2, cycle = TRUE)
m()
#> [1] 1
m()
#> [1] 2
m()
#> [1] 1
m()
#> [1] 2

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

x <- 1
y <- 2
m <- mock(1, x + y, cycle = TRUE)

m()
#> [1] 1
m()
#> [1] 3
y <- 10
m()
#> [1] 1
m()
#> [1] 11

### Evaluating expression in an environment of choice

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

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

m()
#> [1] 3
e\$x <- 10
m()
#> [1] 12

## Integration with with_mock()

### Simple integration

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

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().

m <- mock(1, 2)

m()
#> [1] 1
expect_called(m, 1)

m()
#> [1] 2
expect_called(m, 2)

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

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.

m <- mock(1)
with_mock(summary = m, {
summary(iris)
})
#> [1] 1

expect_call(m, 1, summary(iris))

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

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.

expect_args(m, 1, iris)

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

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().

m <- mock(1)
with_mock(summary = m, {
summary(object = iris)
})
#> [1] 1

expect_args(m, 1, object = iris)

Omitting the name results in an error.

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.

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