@spec accept_connect(client()) :: :ok

Emulates a server telling the client it has connected

This sets the current process as the current server connected to the client. It also adds an ExUnit.callbacks.on_exit/2 function that disconnects the client on exit with reason :closed_by_test. To handle this disconnect, clients should match on this pattern in Slipstream.handle_disconnect/2 and either shutdown (in the case that the test controls the spawning of the client, or reconnect, as with Slipstream.reconnect/1. The default implementation of Slipstream.handle_disconnect/2 reconnects in this case.

See Timing Assumptions.

Examples

test "the server connects", c do
  :ok = accept_connect(MyApp.MyClient)
end

@spec assert_disconnect(timeout()) :: term()

Asserts that a client will attempt to disconnect from the server

Examples

accept_connect(MyClient)
# client will disconnect after 15s of inactivity
assert_disconnect 15_000

@spec assert_join(
  topic_expr :: Macro.t(),
  params_expr :: Macro.t(),
  reply ::
    :ok
    | :error
    | {:ok, Slipstream.json_serializable()}
    | {:error, Slipstream.json_serializable()},
  timeout()
) :: term()

Asserts that a client will request to join a topic

topic_expr and params_expr are interpreted as match expressions, so they may be literal values, pinned (^) bindings, or partial values such as "msg:" <> _ or %{} (which matches any map).

reply is meant to simulate the return value of the Phoenix.Channel.join/3 callback.

Examples

accept_connect(MyClient)
assert_join "rooms:lobby", %{}, :ok

@spec assert_leave(topic_expr :: Macro.t(), timeout()) :: term()

Asserts that a client will request to leave a topic

topic_expr is a pattern, so literal values like "room:lobby" are valid as well as match patterns such as "room:" <> _. Existing bindings must be pinned with the ^ pin operator.

Examples

topic = "rooms:lobby"
accept_connect(MyClient)
assert_join ^topic, %{}, :ok
push(MyClient, topic, "leave", %{})
assert_leave ^topic

@spec assert_push(
  topic_expr :: Macro.t(),
  event_expr :: Macro.t(),
  params_expr :: Macro.t(),
  ref_expr :: Macro.t(),
  timeout()
) :: term()

Asserts that the client will request to push a message to the server

Note that topic_expr, event_expr, params_expr, and ref_expr are all pattern expressions. Prior bindings may be used with the ^ pin operator, values may be underscored to ignore, and partial values may be matched (e.g. %{} will match any map).

ref_expr can be provided to bind a reference for later use in reply/3.

Examples

assert_push "rooms:lobby", "msg:new", params, ref
reply(MyClient, ref, {:ok, %{status: "ok", received: params}})

@spec connect_and_assert_join(
  client :: pid() | GenServer.name(),
  topic_expr :: Macro.t(),
  params_expr :: Macro.t(),
  reply :: Slipstream.reply(),
  timeout()
) :: term()

A convenience macro wrapping connection and a join response

This macro is written for clients that join immediately after a connection has been established, which is a common case.

Clients written like so:

@impl Slipstream
def handle_connect(socket) do
  {:ok, join(socket, "rooms:lobby", %{user_id: socket.assigns.user_id})}
end

May be tested with connect_and_assert_join/5 as opposed to a separate connect/2 and then an assert_join/5.

Examples

socket = connect_and_assert_join MySocketClient, "rooms:lobby", %{}, :ok
push(socket, "rooms:lobby", "initial-hello", %{"hello" => "world"})

@spec disconnect(client :: client(), reason :: term()) :: :ok

Emulates a server closing a connection to the client

Examples

accept_connect(MyClient)
disconnect(MyClient, :heartbeat_timeout)

@spec push(
  client :: client(),
  topic :: String.t(),
  event :: String.t(),
  params :: Slipstream.json_serializable()
) :: :ok

Emulates a server pushing a message to the client

This emulates cases of Phoenix.Channel.push/3 by a Phoenix server.

Note that this function will not encode or decode the value of params, so conversion from maps of atom-keys to string-keys will not occur as it would when passing messages over-the-wire.

Examples

test "the server increments our counter with ping messages", c do
  assert Counter.count() == 0

  connect_and_assert_join MyClient, "counter-topic", %{}, :ok

  push(MyClient, "counter-topic", "ping", %{delta: 1})

  assert Counter.count() == 1
end

@spec refute_disconnect(timeout()) :: term()

Refutes that a client will attempt to disconnect from the server

The opposite of assert_disconnect/1.

Examples

accept_connect(MyClient)
refute_disconnect 10_000

@spec refute_join(
  topic_expr :: Macro.t(),
  params_expr :: Macro.t(),
  timeout()
) :: term()

Refutes that a client will request to join a topic

The opposite of assert_join/5.

Examples

accept_connect(MySocketClient)
refute_join "rooms:" <> _, %{user_id: 5}

@spec refute_leave(topic_expr :: Macro.t(), timeout()) :: term()

Refutes that a client will request to leave a topic

The opposite of assert_leave/3.

Examples

accept_connect(MyClient)
assert_join "rooms:lobby", %{}, :ok
push(MyClient, topic, "no-don't-go", %{})
refute_leave ^topic, 10_000

@spec refute_push(
  topic_expr :: Macro.t(),
  event_expr :: Macro.t(),
  params_expr :: Macro.t(),
  timeout()
) :: term()

Refutes that a client will push a message to the server

The opposite of assert_push/4

Examples

refute_push "rooms:lobby", "msg:" <> _, %{user_id: 5}

@spec reply(
  client :: client(),
  ref :: Slipstream.push_reference(),
  reply :: Slipstream.reply()
) :: :ok

Emulates a server replying to a push from the client

ref is a reference which can be matched upon in assert_push/6. reply follows the Slipstream.reply/0 type: it may be an :ok or :error atom or an {:ok, any()} or {:error, any()} tuple. This value will not be encoded or decoded by Slipstream, instead just directly passed to the client.

Examples

topic = "rooms:lobby"
connect_and_assert_join MySocketClient, ^topic, %{}, :ok
assert_push ^topic, "ping", %{}, ref
reply(MySocketClient, ref, {:ok, %{"ping" => "pong"}})