Text of patch.hexdocs.pm › 05-processes.html as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Chapter 5: Processes — patch v0.16.1

View Source Chapter 5: Processes Elixir code frequently runs many processes and a test author often wants to assert about the flow of messages between processes. Patch provides some utilities that make listening to the messages between processes easy. Listeners Listeners are processes that sit between the sender process and the target process. The listener process will send a copy of every message to the test process so it can use ExUnit's built in assert_receive , assert_received , refute_receive , and refute_received functions.

Listeners are especially useful when working with named processes since they will automatically unregister the named process and take its place. For anonymous processes the inject/3 function is provided to assist in injecting listeners into other processes or the listener can be used in place of the target process when starting consumer processes. Listeners are started with the listen/3 function and each have a tag so that the test process can differentiate which listener has delivered which message. defmodule PatchExample do use ExUnit.Case use Patch test "sharded read replication" do listen ( :shard_a_leader , ShardALeader ) listen ( :shard_a_replica_1 , ShardAReplica1 ) listen ( :shard_a_replica_2 , ShardAReplica2 ) listen ( :shard_b_leader , ShardBLeader ) listen ( :shard_b_replica_1 , ShardBReplica1 ) listen ( :shard_b_replica_2 , ShardBReplica2 ) send ( ShardALeader , { :write , :some_value } ) # Assert the leader gets the message assert_receive { :shard_a_leader , { :write , :some_value } } # Assert that the replicas for Shard A get the message too assert_receive { :shard_a_replica_1 , { :write , :some_value } } assert_receive { :shard_a_replica_2 , { :write , :some_value } } # Assert that Shard A does not try to replicate to Shard B refute_receive { :shard_b_leader , { :write , :some_value } } refute_receive { :shard_b_replica_1 , { :write , :some_value } } refute_receive { :shard_b_replica_2 , { :write , :some_value } } end end GenServer Support Listeners have special support for GenServers.

By default a listener will provide the test process with all calls, replies, casts, and messages. Given a listener with the tag :tag the messages from a GenServer are formatted as follows. Client Code Message to Test Process GenServer.call(pid, :message) {:tag, {GenServer, :call, :message, from}} # if capture_replies = true {:tag, {GenServer, :reply, result, from}} GenServer.cast(pid, :message) {:tag, {GenServer, :cast, :message}} During a GenServer.call/3 the listener sits between the client and the server and reports back information to the test process. .------------. .------. .--------. .------. |Test Process| |client| |listener| |server| '------------' '------' '--------' '------' | | GenServer.call(message)| | | | -----------------------> | | | | | | {GenServer, :call, message, from} | | | <- - - - - - - - - - - - - - - - - - - - - - | | | | | | | | GenServer.call(message)| | | | -----------------------> | | | | | | | reply | | | | <----------------------- | | | | | {GenServer, :reply, reply, from} | | | <- - - - - - - - - - - - - - - - - - - - - - | | | | | | | reply | | | | <----------------------- | .------------. .------. .--------. .------. |Test Process| |client| |listener| |server| '------------' '------' '--------' '------'` GenServer.call/3 allows the client to set a timeout, an amount of time to wait for the server to response.

The listener does not know how long the original client will wait for a timeout, the test author can provide a :timeout option when spawning the listener to control how long the listener will wait for its GenServer.call/3 . By default the listener will wait 5000ms for each call, the default for GenServer.call/2 . Since assert_receive/3 supports binding, we can use the from to match a call and a reply. defmodule PatchExample do use ExUnit.Case use Patch test "matching calls and replies" do Counter . start_link ( 0 , name : Counter ) listen ( :counter , Counter ) assert Counter . increment ( ) == 1 assert_receive { :counter , { GenServer , :call , :increment , from } } # Bind `from` assert_receive { :counter , { GenServer , :reply , 1 , ^ from } } # Match the pinned `from` end end If the test doesn't require the listener to capture replies to GenServer.call then the :capture_replies option can be set to false.

When this option is false the listener will simply forward the call onto the server. Refer to the following diagram for details on how this works. .------------. .------. .--------. .------. |Test Process| |client| |listener| |server| '------------' '------' '--------' '------' | | GenServer.call(message)| | | | -----------------------> | | | | | | {GenServer, :call, message, from} | | | <- - - - - - - - - - - - - - - - - - - - - - | | | | | | | | send(:"$gen_call", from, message)| | | | ---------------------------------> | | | | | | | reply | | | <---------------------------------------------------------- .------------. .------. .--------. .------. |Test Process| |client| |listener| |server| '------------' '------' '--------' '------' Target Monitoring Listeners will automatically monitor the target process they are listening to.

If the target process goes :DOWN the listener will deliver a tagged {:DOWN, reason} message to the test process and then exit. Injecting Listeners listen/3 works well for named processes when callers are using the name to send messages to the target process. What should we do when callers are sending to a pid instead of a name? This is where the inject/4 function can be used. inject/4 will extract a pid out of a GenServer's state, wrap it with a listener and then replace the pid in the GenServer's state with the listener pid. inject/4 will also work with keys in the GenServer's state that are nil , it will generate a targetless listener and replace the nil with that listner's pid.

This latter behavior is nice when working with a process that will spawn another process and keep track of its pid in state if the spawning behavior is outside the scope of your test. Here's a simple example, we will have 2 modules, Target and Caller . defmodule Target do use GenServer ## Client def start_link ( multiplier ) do GenServer . start_link ( __MODULE__ , multiplier ) end def work ( pid , argument ) do GenServer . call ( pid , { :work , argument } ) end ## Server def init ( multiplier ) do { :ok , multiplier } end def handle_call ( { :work , argument } , _from , multiplier ) do { :reply , argument * multiplier , multiplier } end end Our Target module isn't very interesting, it can do some work/1 where the caller sends it a number and it multiplies it by the multiplier it was started with and returns it.

Next let's look at our Caller defmodule Caller do use GenServer defstruct [ :bonus , :target_pid ] ## Client def start_link ( bonus , multiplier ) do GenServer . start_link ( __MODULE__ , { bonus , multiplier } ) end def calculate ( pid , argument ) do GenServer . call ( pid , { :calculate , argument } ) end ## Server def init ( { bonus , multiplier } ) do { :ok , target_pid } = Target . start_link ( multiplier ) { :ok , % __MODULE__ { bonus : bonus , target_pid : target_pid } } end def handle_call ( { :calculate , argument } , _from , % __MODULE__ { } = state ) do multiplied = Target . work ( state . target_pid , argument ) { :reply , multiplied + state . bonus , state } end end Our Caller takes two values, a bonus and a multiplier .

It spawns a new Target process with the multiplier and stores the target_pid in its state. The Caller process will send a message to the target_pid it has stored in its state. Here's how we can use inject/4 to listen to the messages between the Caller process and the Target process. defmodule PatchExample do use ExUnit.Case use Patch test "listen to messages to Target Process" do bonus = 5 multiplier = 10 { :ok , caller_pid } = Caller . start_link ( bonus , multiplier ) inject ( :target , caller_pid , [ :target_pid ] ) assert Caller . calcul

The rest of this page is on the live site.