Chapter 2: Patching — patch v0.16.1
View Source Chapter 2: Patching The most common operation a test author will perform with Patch is, unsurprisingly, patching things. When a module is patched, the patched function will return the mock value provided. Scalar Values The simplest kind of patch is one that just returns a static scalar value on every invocation. defmodule PatchExample do use ExUnit.Case use Patch test "functions can be patched to return a specified value" do # Assertion passes before patching assert "HELLO" == String . upcase ( "hello" ) # The function can be patched to return a static scalar value patch ( String , :upcase , :patched ) # Assertion passes after patching assert :patched == String . upcase ( "hello" ) end end No matter how many times we call String.upcase/1 from here on in and no matter what arguments we pass, we will always get back the value :patched .
Callable Values Modules can also be patched to run custom logic instead of returning a static value defmodule PatchExample do use ExUnit.Case use Patch test "functions can be patched with a replacement function" do # Assertion passes before patching assert "HELLO" == String . upcase ( "hello" ) # The function can be patched to run custom code patch ( String , :upcase , fn s -> String . length ( s ) end ) # Assertion passes after patching assert 5 == String . upcase ( "hello" ) end end Every time we call String.upcase/1 it will run our function and return the length of the input.
Passthrough vs Strict Evaluation By default Patch will evaluate the callable in :passthrough mode. In passthrough mode if the callable raises either BadArityError or FunctionClauseError then the original function will be called. In :strict mode these errors will be returned. One of the core design principles underlying Patch is that it tries to obey the intent of the test author. Consider the following example. defmodule Example do use GenServer # Snip all the GenServer boilerplate def handle_call ( { :a , argument } , _from , state ) do # Operation A Definition { :reply , result , state } end def handle_call ( { :b , argument } , _from , state ) do # Operation B Definition { :reply , result , state } end end When a test author writes the following test code, how should Patch interpret it? patch ( Example , :handle_call fn { :a , _argument } , _from , state -> { :reply , :ok , state } end ) There are two possible interpretations, either the test author wants to patch the callback responsible for handling messages shaped like {:a, argument} or the test author intends to replace all handle_call callback with one only capable of handling {:a, argument} .
Patch already has an opinion on which of these to prefer, we can see it in how Patch handles patching out one function in a module. The assumption is that the test author will apply the minimum patch possible, so patching a single function in a module leaves all the other functions in the module as they were. Applying a similar "default passthrough" behavior to this situation it leads us to one conclusion, the test author probably just wants to replace the functionality handling {:a, argument} and should leave the other callbacks alone.
There are always exceptions to the default rule, and Patch wants to make it possible to express the other idea. The test author can inform Patch of their intention by using the :strict evaluation mode. patch ( Example , :handle_call , callable ( fn { :a , _argument } , _from , state -> { :reply , :ok , state } end , evaluate : :strict ) ) Stacked Callables Callables stack as they are defined in the test. Every time a function is patched with a callable, that callable is pushed to the top of the stack.
When the patched function is called, the stack is walked from the top to bottom to find a callable that can handle it. There are two problems that are nicely solved by Stacked Callables. Patching functions with multiple arities and making pattern matching in patching composable. Stacking and Multiple Arities The first problem that Stacked Callables solves is patching functions with multiple arities. Consider this example module. defmodule Example do def example ( a ) do { :original , a } end def example ( a , b , c ) do { :original , a , b , c } end end This module defines two functions example/1 and example/3 .
How can we patch both functions? Our first attempt might look something like this: Note: this code is invalid and won't compile patch ( Example , :example , fn a -> { :patched , a } a , b , c -> { :patched , a , b , c } end ) This code is illegal in Elixir, the compiler will throw a CompileError and explain that you "cannot mix clauses with different arities in anonymous functions." The first solution for this was introduced in v0.6.0 and took the form of a "dispatch mode." By default Patch will use the :apply mode, which calls the function with the same arity as the patched function was called.
There is an alternative "dispatch mode" called :list which will pass all the arguments as a single argument, a list of the arguments. This code will work, but is unwieldy patch ( Example , :example , callable ( fn [ a ] -> { :patched , a } [ a , b , c ] -> { :patched , a , b , c } end , dispatch : :list ) This solution made it possible to handle multiple arities, but it is pretty clunky. With stacked callables we can actually just define two separate callables, one for arity 1, and one for arity 3.
This code works and is easy to read and write patch ( Example , :example , fn a -> { :patched , a } end ) patch ( Example , :example , fn a , b , c -> { :patched , a , b , c } end ) To understand how this works, let's look at how a call to example/1 and a call to example/3 work. The first thing we have to understand is what the Callable Stack looks like, so let's diagram it. # Top of Stack (latest defined callable) [ fn a , b , c -> { :patched , a , b , c } end , fn a -> { :patched , a } end ] # Bottom of Stack (earliest defined callable) Patch will run each function until one returns a valid value, the first function to respond with a return value will cause evaluation to complete.
When Example.example(1) is evaluated it will try the first function. This function has a different arity so it will raise BadArityError , this is one of the two errors that engages passthrough behavior. Since the first entry in the stack resulted in a logical passthrough Patch will try the next entry. The next entry has the right arity and results in {:patched, 1} being returned. When Example.example(1, 2, 3) is evaluated, it's a bit simpler.
The first function is tried and it matches in arity so it immediately returns {:patched, 1, 2, 3} and evaluation is completed. Stacking and Matching Another problem that Stacked Callables helps solve is composability when patching with pattern matching. Consider the following example module. defmodule Example do def handle ( :a ) do { :original , :a } end def handle ( :b ) do { :original , :b } end def handle ( :c ) do { :original , :c } end end If a test author wanted to provide patched behavior for :a and :b they can do so like this. patch ( Example , :handle , fn :a -> { :patched , :a } :b -> { :patched , :b } end ) Which is a very convenient use of built-in Elixir feature, namely that anonymous functions can have multiple clauses.
But what if we want to have a common behavior for patching out the handling of :a and the handling of :b . Perhaps in one test we want patch out :a , in another :a and :b , and in a third just :b . Is there any way that we can DRY up this code and make it composable? Stacked Callables make this quite nice because it makes it possible to patch multiple clauses at different times. defmodule ExampleTest do use ExUnit use Patch def patch_a do patch ( Example , :handle , fn :a -> { :patched , a } end ) end def patch_b do patch ( Example , :handle , fn :b -> { :patched , b } end ) end test "that cares about :a" do patch_a ( ) assert Example . handle ( :a ) == { :patched , :a } end test "that cares about :a and :b" do pat
The rest of this page is on the live site.