1 The Mock Guide🔗ℹ

This guide is intended for programmers who are familiar with Racket but new to working with mocks. It contains a description of the high level concepts associated with the mock library, as well as examples and use cases. For a complete description of the mock API, see The Mock Reference.

1.1 Introduction to Mocks🔗ℹ

The mock library defines mocks, procedures that record how they’re used and can have their response to calls dynamically altered. Mocks are most useful when testing imperative code or code with side effects, serving as "fake" implementations in tests for verifying real implementations are used correctly. For example, consider the following procedure:

How can a test verify that the secret value is passed correctly? It would be one thing if call/secret returned the result of the call, then we could simply pass in values and verify that the whole thing returns "secret". But because the result of the call is discarded, we somehow need to use a procedure that records a history of all calls made with it so we can check that history afterwards. This is precisely what mocks are for.

Mocks are constructed by the mock function. They’re procedures that behave exactly like whatever their current behavior is, but they also keep a record of all calls made with them. In the previous example, we construct the mock secret-mock that behaves like the void procedure. If the behavior is unspecified the mock will throw an error whenver its called, so we choose void as its behavior since call/secret doesn’t need a return value from the procedure it’s given. After evaluating (call/secret secret-mock), the secret-mock has a procedure call in its saved history that is accessible via mock-calls. Now we can query this history in tests. We can also clear a mock’s history of calls using mock-reset!, allowing us to clean up after a test.

1.2 Using Mocks in Place of Dependencies🔗ℹ

In the previous section we used mocks to test a higher order function call/secret. Mocks also help when dealing with code that performs operations with side effects. In tests, we simply replace the operation procedure with a mock. To do this, we can take a procedure that calls side effectful dependencies and convert it to a higher order procedure like call/secret, which accepts the side effectful dependencies as inputs. Consider a procedure that looks up a favorite color from a file, then prints a message based on that color.

Testing this procedure is definitely tricky. There’s input from the "color-preferences.txt" file to worry about along with output via displayln. To properly test this procedure, let’s alter it slightly. We’ll pass in the side effectful dependency procedures as arguments.

Much better. By passing in the procedures we use for reading and writing as arguments, we allow tests to specify that input and output should be performed with mocks. Using the real functions by default also means we don’t affect any existing code using print-favorite-color-message. Now let’s try using mocks.

By using const we’re able to easily setup tests that exercise a particular codepath. We can test side effectful code! There’s still more to discuss, the following sections discuss adjusting mock behavior and automatically mocking out dependencies.

1.3 Dynamically Changing Mock Behavior🔗ℹ

Mocks have a behavior, which defines what they return when called. This behavior is not fixed; mocks can have their behavior changed dynamically using with-mock-behavior. This allows the same mock to respond differently to different calls while retaining a history of all calls. Recall the favorite color procedure we defined in the previous section:

If we want to test more than one branch of this code, we need our file->string mock to return different results. We could use different mocks, but then each mock has a separate call history. In this particular case that’s not a problem, but for the sake of a good example we’ll assume we want a combined history. We can use with-mock-behavior to dynmaically control the behavior of a mock.

A mocks behavior is a parameter under the hood, so with-mock-behavior acts similarly to parameterize. While here we could have made a second mock, in the next section we’ll introduce automatic mocking which defines one mock per dependency for us.

1.4 Automatic Mocking with Syntax🔗ℹ

In the previous sections we transformed procedures we wanted to test into higher order functions that accepted their dependencies as input. This let us construct a mock for each dependency and pass it in to inspect how the procedure called its dependencies. This was a fairly mechanical translation. In this section we introduce define/mock, a syntactic form that automates mocking out dependencies in this fashion. Recall again our favorite color procedure.

We previously mocked out the file->string and displayln procedures. This was done in three steps:

• Add a parameter for each dependency procedure that defaults to the real one.

• Define a mock for each dependency procedure with appropriate behavior

• Call print-favorite-color-message with the mocks as its dependencies, adjusting mock behavior and resetting mocks as necessary.

The define/mock form automates the first two steps of this process.

The details of how this works are covered in The Mock Reference, but the gist is that each #:mock clause mocks out a single dependency procedure and defines a mock with the name given in the #:as clause. The #:with-behavior clause defines the default behavior for each mock. However, the mocks are not immediately available to client code - their definitions must be brought into scope using a with-mocks form.

The with-mocks form also takes care of calling mock-reset! on every mock associated with print-favorite-color-message.

This makes setting up mocked dependencies much simpler. The define/mock form has a few other options to control its behavior, see The Mock Reference for details.

1.5 Stubbing Undefined Dependencies🔗ℹ

When testing with mocks, we’re able to test how a procedure calls its dependencies without actually using real dependencies. In theory then, there’s no reason those dependencies need to be implemented before we write our test. Consider a procedure in a web application that checks whether the current user is authenticated. What are its dependencies? Clearly there must be some sort of user datatype and a user-admin? predicate. There must also be a way to determine the user associated with the current request, call that current-user. And if the user isn’t an admin, there must be some sort of raise-non-admin-access-error procedure to throw an exception indicating the lack of access. We can try and define a check-current-user-admin procedure in terms of these pieces before defining the pieces, but our code won’t compile.

If we’re testing check-current-user-admin with mocks, since all those dependencies will be mocked out anyway we could just define fake implementations for them.

Now we can test check-current-user-admin without properly defining real dependencies.

Nice as this approach could be, it’s still rather tedious to define each of those fake dependencies. And if they’re actually called, the error message is a terrible one about the evils of treating #f as a procedure. The mock library provides a stub form for automatically defining these sorts of fake implementations.

We can now better control the order in which we implement procedures, writing tests as we go and even writing code in a test-first fashion.

1.6 Mocking and Opaque Values🔗ℹ

Libraries often define "special" values that can’t be inspected and are only obtainable through the library, such as database connections or other "opaque" values. When mocking dependency functions from that library, we often end up in a situation where a mocked dependency produces one of these values and another mock consumes it. In this case, it doesn’t matter at all what the producer returns.

We could have returned any value at all from the db-connect! procedure, for unit testing purposes all we care about is that whatever db-connect! returns is passed in properly to db-list-ids. However, this could lead to problems if we accidentally passed the "connection" value somewhere else. If given to a procedure that prints out a string, instead of throwing an error we’ll get "some random value" printed out unexpectedly. What we’d really like is to create some value that can only be used as a mock connection. The define-opaque form lets us define opaque values, which are completely black-boxed values with no meaning that any procedure could extract from them.

In this example, we’ve defined an opaque test-connection value that our tests can look for. It’s impossible to misuse this value, and it helpfully identifies itself in error messages when passed around unexpectedly. The define-opaque form defines both an opaque value and a predicate that can be used to recognize that value. In tests, we can look for the opaque value in mock call history with the predicate or equal?.

In addition to define-opaque, the define/mock form provides a handy syntax for defining an opaque value that only that definition’s mocks and with-mocks enclosed code can reference. Simply add the identifier in an #:opaque clause.

The #:opaque clause can define multiple opaque values at once by surrounding them in parentheses. See define/mock’s documentation in The Mock Reference for details.