hare v0.2.2 Hare.Adapter.Sandbox.Backdoor

This module provides the developer functions to use the sandbox adapter capabilities to inspect its history and modify its behaviour.

Summary

Types

Event returned by history checking functions. Like events/1

Possible result specifications for on_connect/1 and on_channel_open/1

Functions

Provokes a connection or a channel process to stop with the given reason, therefore triggering all monitors and links with that process

Returns all functions called on the adapter for the connection that was open with the given history on its configuration

Similar to events/1 but it only returns the most recent event

Similar to events/1 but it only returns the most recent count events

Starts a new agent process that specifies the messages to be given when messages are get from a queue using get/2

Starts a new agent process that specifies the behaviour of the adapter when it opens a new channel

Starts a new agent process that specifies the behaviour of the adapter when it opens a new connection

Starts a new history process and links it to the caller

Unlinks a connection or a channel from the caller

Types

event()
event() :: {function :: atom, args :: [term], result :: term}

Event returned by history checking functions. Like events/1.

result()
result() :: :ok | {:error, reason :: term}

Possible result specifications for on_connect/1 and on_channel_open/1

Functions

crash(resource, reason \\ :simulated_crash)
crash(Hare.Adapter.Sandbox.Conn.t | Hare.Adapter.Sandbox.Chan.t, reason :: term) :: :ok

Provokes a connection or a channel process to stop with the given reason, therefore triggering all monitors and links with that process.

events(history)
events(pid) :: [event]

Returns all functions called on the adapter for the connection that was open with the given history on its configuration.

Each event has the following format: {function_name, arguments, result}

alias Hare.Adapter.Sandbox, as: Adapter

{:ok, history} = Adapter.Backdoor.start_history()
{:ok, conn} = Adapter.open_connection(history: history)

{:ok, conn} = Adapter.open_connection(config)
{:ok, chan} = Adapter.open_channel(conn)

Adapter.get(chan, "my_queue", []) # => {:empty, %{}}

Adapter.Backdoor.events(history) # => [{:open_connection, [history: history],     {:ok, conn}},
                                 #     {:open_channel,    [conn],                 {:ok, chan}},
                                 #     {:get,             [chan, "my_queue", []], {:empty, %{}}]
last_event(history)
last_event(pid) :: event

Similar to events/1 but it only returns the most recent event.

last_events(history, count)
last_events(pid, count :: non_neg_integer) :: [event]

Similar to events/1 but it only returns the most recent count events.

messages(messages, opts \\ [])
messages(messages :: [term], GenServer.options) :: Agent.on_start

Starts a new agent process that specifies the messages to be given when messages are get from a queue using get/2.

Take into account that the sandbox adapter’s handle/2 function expects AMQP known messages to have the following format:

  • {:consume_ok, meta} - for the consume-ok message
  • {:deliver, payload, meta} - for an actual queue message
  • {:cancel_ok, meta} - for the cancel-ok message

Anything else will cause handle/2 to return :unknown.

The messages process can be given to the adapter as the connection configuration.

alias Hare.Adapter.Sandbox, as: Adapter

raw_messages = [{:deliver, "foo", %{}},
                {:deliver, "bar", %{}}]

{:ok, messages} = Adapter.Backdoor.messages(results)

{:ok, conn} = Adapter.open_connection(messages: messages)
{:ok, chan} = Adapter.open_channel(conn)

Adapter.get(chan, "one_queue")     # => {:ok, "foo", %{}}
Adapter.get(chan, "another_queue") # => {:ok, "bar", %{}}
Adapter.get(chan, "yet_another")   # => {:empty, %{}}
on_channel_open(results, opts \\ [])
on_channel_open([result], GenServer.options) :: Agent.on_start

Starts a new agent process that specifies the behaviour of the adapter when it opens a new channel.

The first argument is a list of expected results when a new channel is open.

The possible values of the results list are:

  • :ok - the channel opens successfully
  • {:error, reason} - the channel fails with the given reason

The on_channel_open process can be given to the adapter as the connection configuration.

alias Hare.Adapter.Sandbox, as: Adapter

results = [{:error, :foo}, :ok, {:error, {:foo, "bar"}}, :ok]

{:ok, on_channel_open} = Adapter.Backdoor.on_channel_open(results)
config = [on_channel_open: on_channel_open]

{:ok, conn} = Adapter.open_connection(config)

Adapter.open_channel(conn) # => {:error, :foo}
Adapter.open_channel(conn) # => {:ok, chan_1}
Adapter.open_channel(conn) # => {:error, {:foo, "bar"}}
Adapter.open_channel(conn) # => {:ok, chan_2}
Adapter.open_channel(conn) # => {:ok, chan_3}
on_connect(results, opts \\ [])

Starts a new agent process that specifies the behaviour of the adapter when it opens a new connection.

The first argument is a list of expected results when a new connection is open.

The possible values of the results list are:

  • :ok - the connection opens successfully
  • {:error, reason} - the connection fails with the given reason

The on_connect process can be given to the adapter as the connection configuration.

alias Hare.Adapter.Sandbox, as: Adapter

results = [{:error, :foo}, :ok, {:error, {:foo, "bar"}}, :ok]

{:ok, on_connect} = Adapter.Backdoor.on_connect(results)
config = [on_connect: on_connect]

Adapter.open_connection(config) # => {:error, :foo}
Adapter.open_connection(config) # => {:ok, conn_1}
Adapter.open_connection(config) # => {:error, {:foo, "bar"}}
Adapter.open_connection(config) # => {:ok, conn_2}
Adapter.open_connection(config) # => {:ok, conn_3}
start_history(opts \\ [])
start_history(GenServer.options) :: Agent.on_start

Starts a new history process and links it to the caller.

This history process can be given to the adapter as the connection configuration.

After that, functions like events/1, last_event/1 and last_events/2 can be used to retrieve information about how the adapter has been used.

alias Hare.Adapter.Sandbox, as: Adapter

{:ok, history} = Adapter.Backdoor.start_history()
{:ok, conn} = Adapter.open_connection(history: history)

# ... use the adapter

Adapter.Backdoor.events(history) # => a list of events
unlink(conn)
unlink(Hare.Adapter.Sandbox.Conn.t | Hare.Adapter.Sandbox.Chan.t) :: true

Unlinks a connection or a channel from the caller.

Mainly used to avoid the test crashing because of a simulated crash of a connection or a channel.