Improving Testability of Handlers v2

README.md

@@ -208,6 +208,33 @@ defmodule Alice.Handlers.GoogleImages do
 end
 ```
 
+### Testing Handlers
+
+Alice provides several helpers to make it easy to test your handlers.
+First you'll need to invoke to add `use Alice.HandlersCase, handlers:
+[YourHandler]` passing it the handler you're trying to test. Then you
+can use `message_received()` within your test, which will simulate a
+message coming in from the chat backend and route it through to the
+handlers appropriately.  If you're wanting to invoke a command, you'll
+need to make sure your message includes `<@alice>` within the string. From there you can use either `first_reply()`
+to get the first reply sent out or `all_replies()` which will return a List of replies that have been
+received during your test. You can use either to use normal assertions
+on to ensure your handler behaves in the manner you expect.
+
+In `test/alice/handlers/google_images_test.exs`:
+
+```elixir
+defmodule Alice.Handlers.GoogleImagesTest do
+  use Alice.HandlersCase, handlers: Alice.Handlers.GoogleImages
+
+  test "it fetches an image when asked" do
+    send_message("img me example image")
+
+    assert first_reply() == "http://example.com/image_from_google.jpg"
+  end
+end
+```
+
 ### Registering Handlers
 
 In the `mix.exs` file of your bot, add your handler to the list of handlers to

lib/alice/chat_backends/outbound_client.ex

@@ -0,0 +1,8 @@
+defmodule Alice.ChatBackends.OutboundClient do
+  @moduledoc """
+    Documentation for the OutboundClient behavior. This defines a behavior for modules that serve as an outbound connection to a backend.
+  """
+
+  @callback send_message(response :: String.t(), channel :: String.t(), backend :: map()) :: String.t()
+  @callback indicate_typing(channel :: String.t(), backend :: map()) :: String.t()
+end

lib/alice/chat_backends/slack_outbound.ex

@@ -0,0 +1,7 @@
+defmodule Alice.ChatBackends.SlackOutbound do
+  @behaviour Alice.ChatBackends.OutboundClient
+
+  def send_message(response, channel, slack), do: Slack.Sends.send_message(response, channel, slack)
+
+  def indicate_typing(channel, slack), do: Slack.Sends.indicate_typing(channel, slack)
+end

lib/alice/router.ex

@@ -89,7 +89,9 @@ defmodule Alice.Router do
 
   def match_pattern({pattern, name}, {mod, conn = %Conn{}}) do
     if Regex.match?(pattern, conn.message.text) do
-      Logger.info("#{mod}.#{name} responding to -> #{Conn.user(conn)}")
+      unless(Mix.env() == :test) do
+        Logger.info("#{mod}.#{name} responding to -> #{Conn.user(conn)}")
+      end
       {mod, apply(mod, name, [Conn.add_captures(conn, pattern)])}
     else
       {mod, conn}

lib/alice/router/helpers.ex

@@ -24,15 +24,15 @@ defmodule Alice.Router.Helpers do
   def reply(conn = %Conn{message: %{channel: channel}, slack: slack}, resp) do
     resp
     |> Alice.Images.uncache()
-    |> slack_api().send_message(channel, slack)
+    |> outbound_api().send_message(channel, slack)
 
     conn
   end
 
-  defp slack_api do
+  defp outbound_api do
     case Mix.env() do
-      :test -> FakeSlack
-      _else -> Slack.Sends
+      :test -> Alice.ChatBackends.OutboundSpy
+      _else -> Alice.ChatBackends.SlackOutbound
     end
   end
 
@@ -89,7 +89,6 @@ defmodule Alice.Router.Helpers do
   @spec delayed_reply(Conn.t(), String.t(), integer) :: Task.t()
   @spec delayed_reply(String.t(), integer, Conn.t()) :: Task.t()
   def delayed_reply(msg, ms, conn = %Conn{}), do: delayed_reply(conn, msg, ms)
-
   def delayed_reply(conn = %Conn{}, message, milliseconds) do
     Task.async(fn ->
       conn = indicate_typing(conn)
@@ -103,7 +102,7 @@ defmodule Alice.Router.Helpers do
   """
   @spec indicate_typing(Conn.t()) :: Conn.t()
   def indicate_typing(conn = %Conn{message: %{channel: chan}, slack: slack}) do
-    slack_api().indicate_typing(chan, slack)
+    outbound_api().indicate_typing(chan, slack)
     conn
   end
 end

mix.exs

@@ -6,6 +6,7 @@ defmodule Alice.Mixfile do
       app: :alice,
       version: "0.4.1",
       elixir: "~> 1.7",
+      elixirc_paths: elixirc_paths(Mix.env()),
       build_embedded: Mix.env() == :prod,
       start_permanent: Mix.env() == :prod,
       description: "A Slack bot",
@@ -43,4 +44,6 @@ defmodule Alice.Mixfile do
       }
     ]
   end
+
+  defp elixirc_paths(_), do: ["test/support", "lib"]
 end

test/alice/handlers/utils_test.exs

@@ -0,0 +1,16 @@
+defmodule Alice.Handlers.UtilsTest do
+  use Alice.HandlersCase, handlers: Alice.Handlers.Utils
+
+  test "it should respond to a ping" do
+    send_message("ping")
+
+    assert first_reply() in ["PONG!", "Can I help you?", "Yes...I'm still here.", "I'm alive!"]
+  end
+
+  test "it should respond with info about the running bot" do
+    send_message("<@alice> info")
+
+    {:ok, version} = :application.get_key(:alice, :vsn)
+    assert first_reply() == "Alice #{version} - https://github.com/alice-bot"
+  end
+end

test/alice/router/helpers_test.exs

@@ -1,55 +1,63 @@
-defmodule FakeSlack do
-  def send_message(text, :channel, :slack) do
-    send(self(), {:msg, text})
-  end
-end
-
 defmodule Alice.Router.HelpersTest do
-  use ExUnit.Case, async: true
+  use ExUnit.Case
+  import Alice.HandlersCase
   import Alice.Router.Helpers
 
-  def conn do
-    %Alice.Conn{message: %{channel: :channel}, slack: :slack}
-  end
-
   test "reply returns the conn" do
-    assert reply("yo", conn()) == conn()
+    assert reply("yo", fake_conn()) == fake_conn()
   end
 
   test "reply sends a message with Slack.send_message" do
-    reply("yo", conn())
-    assert_received {:msg, "yo"}
+    reply("yo", fake_conn())
+
+    assert first_reply() == "yo"
+  end
+
+  test "multiple replies can be sent in the same handler" do
+    reply("first", fake_conn())
+    reply("second", fake_conn())
+
+    assert ["first", "second"] == all_replies()
   end
 
   test "reply calls random_reply when given a list" do
-    ["element"] |> reply(conn())
-    assert_received {:msg, "element"}
+    reply(["element"], fake_conn())
+
+    assert first_reply() == "element"
   end
 
   test "random_reply sends a message from a given list" do
-    ~w[rabbit hole] |> random_reply(conn())
-    assert_received {:msg, resp}
-    assert resp in ~w[rabbit hole]
+    ~w[rabbit hole] |> random_reply(fake_conn())
+
+    assert first_reply() in ~w[rabbit hole]
   end
 
   test "chance_reply, when chance passes, \
                       replies with the given message" do
-    chance_reply(conn(), 1, "always")
-    assert_received {:msg, "always"}
+    chance_reply(fake_conn(), 1, "always")
+
+    assert first_reply() == "always"
   end
 
   test "chance_reply, when chance does not pass, \
                       when not given negative message, \
                       does not reply" do
-    chance_reply(conn(), 0, "never")
-    refute_received {:msg, _}
+    chance_reply(fake_conn(), 0, "never")
+
+    assert first_reply() == nil
   end
 
   test "chance_reply, when chance does not pass, \
                       when given negative message, \
                       replies with negative" do
-    chance_reply(conn(), 0, "positive", "negative")
-    refute_received {:msg, "positive"}
-    assert_received {:msg, "negative"}
+    chance_reply(fake_conn(), 0, "positive", "negative")
+
+    assert all_replies() == ["negative"]
+  end
+
+  test "it should indicate typing when asked" do
+    indicate_typing(fake_conn())
+
+    assert typing?()
   end
 end

test/support/handlers_case.ex

@@ -0,0 +1,68 @@
+defmodule Alice.HandlersCase do
+  def all_replies() do
+    message = receive do
+      {:send_message, %{response: message}} -> message
+    after
+      0 -> :no_message_received
+    end
+    case message do
+      :no_message_received -> []
+      message -> [message | all_replies()]
+    end
+  end
+
+  def first_reply() do
+    case all_replies() do
+      [first_message |  _] -> first_message
+      _                    -> nil
+    end
+  end
+
+  def fake_conn(), do: fake_conn("")
+  def fake_conn(text) do
+    %Alice.Conn{message: %{text: text, channel: :channel, user: :fake_user}, slack: %{users: [fake_user: %{name: "fake_user"}], me: %{id: :alice}}}
+  end
+  def fake_conn(message, capture: capture_regex) do
+    message
+    |> fake_conn()
+    |> Alice.Conn.add_captures(capture_regex)
+  end
+
+
+  def send_message(conn = %Alice.Conn{}) do
+    case Alice.Conn.command?(conn) do
+      true  -> Alice.Router.match_commands(conn)
+      false -> Alice.Router.match_routes(conn)
+    end
+  end
+  def send_message(message) do
+    message
+    |> fake_conn()
+    |> send_message()
+  end
+
+  def typing?() do
+    receive do
+      {:indicate_typing, _} -> true
+    after
+      0 -> false
+    end
+  end
+
+  defmacro __using__(opts \\ []) do
+    handlers = opts
+               |> Keyword.get(:handlers, [])
+               |> List.wrap()
+
+    quote do
+      use ExUnit.Case
+      import Alice.HandlersCase
+
+      setup do
+        Alice.Router.start_link(unquote(handlers))
+
+        :ok
+      end
+    end
+  end
+end

test/support/outbound_fake.ex

@@ -0,0 +1,11 @@
+defmodule Alice.ChatBackends.OutboundSpy do
+  @behaviour Alice.ChatBackends.OutboundClient
+
+  def send_message(response, channel, slack) do
+    send(self(), {:send_message, %{response: response, channel: channel, slack: slack}})
+  end
+
+  def indicate_typing(channel, slack) do
+    send(self(), {:indicate_typing, %{channel: channel, slack: slack}})
+  end
+end

test/test_helper.exs

@@ -1,19 +1 @@
-defmodule Mock do
-  def setup(name, params), do: setup(name, params, default_return: nil)
-
-  def setup(name, params, default_return: value) do
-    send(self(), {name, params})
-
-    receive do
-      {:return, {^name, value}} -> value
-    after
-      0 -> value
-    end
-  end
-
-  def setup_return(name, value) do
-    send(self(), {:return, {name, value}})
-  end
-end
-
 ExUnit.start()