Add docs for IEx test framework

Author: alco

lib/iex/test/iex/interaction_test.exs

@@ -14,8 +14,9 @@ defmodule IEx.InteractionTest do
   end
 
   test "exception" do
-    assert capture_iex("1 + :atom\n:this_is_still_working") =~ %r/^#{iex_format_exception(ArithmeticError,
-      "bad argument in arithmetic expression")}.+\n:this_is_still_working$/s
+    exception = Regex.escape("** (ArithmeticError) bad argument in arithmetic expression")
+    assert capture_iex("1 + :atom\n:this_is_still_working")
+           =~ %r/^#{exception}.+\n:this_is_still_working$/s
   end
 
   test "empty history at the start" do

lib/iex/test/test_helper.exs

@@ -2,6 +2,28 @@
 ExUnit.start []
 
 defmodule IEx.Case do
+  @moduledoc false
+
+  #
+  # Provides convenience functions for testing IEx-related functionality.
+  # Use this module inside your test module like this:
+  #
+  #   defmodule IEx.InteractionTest do
+  #     use IEx.Case
+  #
+  #     test :input do
+  #       assert capture_iex("1+2") == "3"
+  #     end
+  #   end
+  #
+  # The environment provided by capture_iex is mostly similar to the normal IEx
+  # session, except colors are disabled by default and .iex files are not
+  # loaded.
+  #
+  # You can provide your own IEx.Options and a path to a .iex file as
+  # additional arguments to the capture_iex function.
+  #
+
   defmacro __using__(_) do
     quote do
       use ExUnit.Case, async: false
@@ -21,28 +43,26 @@ defmodule IEx.Case do
     end
   end
 
+  @doc """
+  Starts an IEx eval loop, feeds it the provided input and returns produced
+  output. The output is stripped of the first intro line and of any trailing
+  whitespace.
+
+  Options, if provided, will be set before the eval loop is started.
+
+  If you provide the dot_iex_path argument, it will be passed to
+  IEx.Server.start to be used in the normal .iex loading process.
+  """
   def capture_iex(input, options // [], dot_iex_path // "") do
     Enum.each options, fn { opt, value } ->
       IEx.Options.set(opt, value)
     end
 
     ExUnit.CaptureIO.capture_io(input, fn ->
-      IEx.Server.start(iex_config(dot_iex_path: dot_iex_path))
+      IEx.Server.start(IEx.boot_config(dot_iex_path: dot_iex_path))
     end) |> strip_iex
   end
 
-  def iex_exception(name, message // "") do
-    %r/#{iex_format_exception(name, message)}/
-  end
-
-  def iex_format_exception(name, message // "") do
-    "\\*\\* \\(#{Module.to_binary name}\\) (.*?)#{message}"
-  end
-
-  defp iex_config(opts) do
-    IEx.boot_config(opts)
-  end
-
   defp strip_iex(string) do
     string
     |> strip_line   # strip the greeting