Patch mocks out modules by generating mock modules and recompiling them for a target module.

Patch's approach to mocking a module provides some powerful affordances.

• Private functions can be mocked.
• Internal function calls are effected by mocks regardless of the function's visibility without having to change the way code is written.
• Private functions can be optionally exposed in the facade to make it possible to test a private function directly without changing its visibility in code.

Mocking Strategy

There are 4 logical modules and 1 GenServer that are involved when mocking a module.

The 4 logical modules:

• target - The module to be mocked.
• facade - The target module is replaced by a facade module that intercepts all external calls and redirects them to the delegate module.
• original - The target module is preserved as the original module, with the important transformation that all local calls are redirected to the delegate module.
• delegate - This module is responsible for checking with the server to see if a call is mocked and should be intercepted. If so, the mock value is returned, otherwise the original function is called.

Each target module has an associated GenServer, a Patch.Mock.Server that has keeps state about the history of function calls and holds the mock data to be returned on interception. See Patch.Mock.Server for more information.

example-target-module

Example Target Module

To better understand how Patch works, consider the following example module.

defmodule Example do
  def public_function(argument_1, argument_2) do
    {:public, private_function(argument_1, argument_2)}
  end

  defp private_function(argument_1, argument_2) do
    {:private, argument_1, argument_2}
  end
end

facade-module

facade module

The facade module is automatically generated based off the exports of the target module. It takes on the name of the provided module.

For each exported function, a function is generated in the facade module that calls the delegate module.

defmodule Example do
  def public_function(argument_1, argument_2) do
    Patch.Mock.Delegate.For.Example.public_function(argument_1, argument_2)
  end
end

delegate-module

delegate module

The delegate module is automatically generated based off all the functions of the target module. It takes on a name based off the target module, see Patch.Mock.Naming.delegate/1.

For each function, a function is generated in the delegate module that calls Patch.Mock.Server.delegate/3 delegating to the server named for the target module, see Patch.Mock.Naming.server/1.

defmodule Patch.Mock.Delegate.For.Example do
  def public_function(argument_1, argument_2) do
    Patch.Mock.Server.delegate(
      Patch.Mock.Server.For.Example,
      :public_function,
      [argument_1, argument_2]
    )
  end

  def private_function(argument_1, argument_2) do
    Patch.Mock.Server.delegate(
      Patch.Mock.Server.For.Example,
      :private_function,
      [argument_1, argument_2]
    )
  end
end

original-module

original module

The original module takes on a name based off the provided module, see Patch.Mock.Naming.original/1.

The code is transformed in the following ways.

• All local calls are converted into remote calls to the delegate module.
• All functions are exported

defmodule Patch.Mock.Original.For.Example do
  def public_function(argument_1, argument_2) do
    {:public, Patch.Mock.Delegate.For.Example.private_function(argument_1, argument_2)}
  end

  def private_function(argument_1, argument_2) do
    {:private, argument_1, argument_2}
  end
end

external-function-calls

External Function Calls

First, let's examine how calls from outside the module are treated.

public-function-calls

Public Function Calls

Code calling Example.public_function/2 has the following call flow.

[Caller] -> facade -> delegate -> server -> mocked? -> yes   (Intercepted)
         [Mock Value] <----------------------------|----'
                                                    -> no -> original   (Run Original Code)
         [Original Value] <--------------------------------------'

Calling a public function will either return the mocked value if it exists, or fall back to calling the original function.

private-function-calls

Private Function Calls

Code calling Example.private_function/2 has the following call flow.

[Caller] --------------------------> facade
         [UndefinedFunctionError] <-----'

Calling a private function continues to be an error from the external caller's point of view.

The expose option does allow the facade to expose private functions, in those cases the call flow just follows the public call flow.

internal-calls

Internal Calls

Next, let's examine how calls from outside the module are treated.

public-function-calls-1

Public Function Calls

Code in the original module calling public functions have their code transformed to call the delegate module.

original -> delegate -> server -> mocked? -> yes   (Intercepted)
         [Mock Value] <------------------|----'
                                          -> no -> original   (Run Original Code)
         [Original Value] <----------------------------'

Since the call is redirected to the delegate, calling a public function will either return the mocked value if it exists, or fall back to calling the original function.

private-function-call-flow

Private Function Call Flow

Code in the original module calling private functions have their code transformed to call the delegate module

original -> delegate -> server -> mocked? -> yes   (Intercepted)
         [Mock Value] <------------------|----'
                                          -> no -> original   (Run Original Code)
         [Original Value] <----------------------------'

Since the call is redirected to the delegate, calling a private function will either return the mocked value if it exists, or fall back to calling the original function.

code-generation

Code Generation

For additional details on how Code Generation works, see the Patch.Mock.Code.Generate module.