test_probe v0.0.2 TestProbe

TestProbe is a tiny wrapper around GenServer, that puts testing of actor interactions under control.

The probe, once started, will accept any message (call, cast, info) and put it into the queue, where it can be accessed using Probe API. After retrieving a message you can tell the probe to respond (in case of call). You can also send messages or execute arbitrary code on behalf of the probe.

In the docs and examples we’ll use MonEx macros, you can easily choose not to use it. ok(x) and error(e) stand for {:ok, x} and {:error, e} respectively. Optional some(x) and none() would be {:some, x} and {:none}. Check monex docs for details.

Examples

import MonEx.{Result, Option} # to support ok() some() etc...
ok(probe) = Probe.start()
task = Task.async(fn -> GenServer.call(probe, :hey) end)

# Here we wait for the message matching the pattern:
assert some(msg) = Probe.receive(probe, %Message{data: :hey})

IO.inspect(msg)
# %TestProbe.Message{
#   data: :hey,
#   from: {#PID<0.193.0>, #Reference<0.2208989138.2906914819.164457>},
#   type: :call
# }

# Now you can use msg to respond:
Probe.reply(msg, :sup)
response = Task.await(task)

assert response == :sup

Link to this section Summary

Functions

Pulls all messages from the probe

Sends call on behalf of the probe and returns the result

Sends cast on behalf of the probe

Returns last message received by the probe

Polls the probe to check if there is a message matching pattern provided

Sends a response to provided message

Runs arbitrary lambda in the context of probe

Sends info on behalf of the probe

Starts the probe with optionals parameters

Stops the probe

Returns how many times the message matching the pattern was received

Link to this section Functions

Link to this function all_received(probe)
all_received(pid) :: [TestProbe.Message.t]

Pulls all messages from the probe.

Be careful, if you call this right after sending a message from some other process, there’s no guarantee that this message will be there. To provide that guarantee, confirm reception with receive first.

Returns: [message, ...]

Link to this function call(probe, pid, message)
call(pid, pid, term) :: term

Sends call on behalf of the probe and returns the result.

Link to this function cast(probe, pid, message)
cast(pid, pid, term) :: term

Sends cast on behalf of the probe.

Link to this function last_received(probe)
last_received(pid) :: MonEx.Option.t

Returns last message received by the probe.

Just like with all_received, the very last message can not be there yet at the time of calling. Consider using receive.

Returns: some(message) or none()

Link to this function receive(probe, message, timeout \\ 1000)
receive(pid, TestProbe.Message.t, integer) :: MonEx.Option.t

Polls the probe to check if there is a message matching pattern provided.

If message is not in a queue yet, will wait for a timeout time. When timeout has passed, a none() will be returned.

Returns: some(message) or none()

Link to this function reply(probe, message, response)
reply(pid, TestProbe.Message.t, term) :: term

Sends a response to provided message.

Returns: ok(message) or error(message) if operation failed

Link to this function run(probe, fun)
run(pid, (() -> term)) :: term

Runs arbitrary lambda in the context of probe.

This in particular is used to implement sending messages on behalf of the probe.

run probe, fn ->
  GenServer.cast(pid, message)
end

Returns: ok(message) or error(message) if operation failed

Link to this function send(probe, pid, message)
send(pid, pid, term) :: term

Sends info on behalf of the probe.

Starts the probe with optionals parameters.

Parameters passed directly to GenServer. name can be useful, if you’re testing some code accessing another process by name.

Returns: ok(pid)

Link to this function stop(probe)
stop(pid) :: atom

Stops the probe.

Link to this function times_received(probe, message)
times_received(pid, TestProbe.Message.t) :: integer

Returns how many times the message matching the pattern was received.

Returns: amount