Add metadata support to ExUnit

Defining setup/teardown/test explicitly is now deprecated.
They should now be defined via their respective macros:

    def setup do
      ...
    end

Now becomes:

    setup do
      ...
    end

When defined using the new format, setup callbacks can
return metadata:

    setup do
      [do_this: :do_that]
    end

And now the test macro can access this metadata:

    test "check metadata", data do
      assert data[:do_this] == :do_that
    end

Author: José Valim

CHANGELOG.md

@@ -1,4 +1,5 @@
 * enhancements
+  * [ExUnit] Tests can now receive metadata set on setup/teardown callbacks
   * [IO] Add `IO.ANSI` to make it easy to write ANSI escape codes
   * [Kernel] Better support for Unicode lists
   * [Kernel] Reduce variables footprint in `case`/`receive` clauses
@@ -16,6 +17,7 @@
   * [Kernel] `before_compile` and `after_compile` callbacks now receive the environment as first argument instead of the module
 
 * deprecations
+  * [ExUnit] Explicitly defined test/setup/teardown functions are deprecated
   * [Kernel] Tidy up and clean `quote` API
   * [Kernel] Old `:local.(args)` syntax is deprecated
   * [Process] `Process.self` is deprecated in favor `Kernel.self`

lib/elixir/test/elixir/file_test.exs

@@ -10,14 +10,16 @@ defmodule FileTest do
 
     # cp_r/c is managed in setup/teardown because if it is stored in
     # the repository, reltool can't build a release
-    def setup do
+    setup do
       src = fixture_path("cp_r")
       :file.make_symlink 'certainly/invalid', Path.join([src, "c"])
+      []
     end
 
-    def teardown do
+    teardown do
       src = fixture_path("cp_r")
       File.rm Path.join([src, "c"])
+      []
     end
 
     test :cp_with_src_file_and_dest_file do
@@ -677,14 +679,16 @@ defmodule FileTest do
 
     # cp_r/c is managed in setup/teardown because if it is stored in
     # the repository, reltool can't build a release
-    def setup do
+    setup do
       src = fixture_path("cp_r")
       :file.make_symlink 'certainly/invalid', Path.join([src, "c"])
+      []
     end
 
-    def teardown do
+    teardown do
       src = fixture_path("cp_r")
       File.rm Path.join([src, "c"])
+      []
     end
 
     test :rm_file do

lib/elixir/test/elixir/kernel_test.exs

@@ -58,7 +58,7 @@ defmodule KernelTest do
   end
 
   test :function_from___ENV__ do
-    assert __ENV__.function == { :test_function_from___ENV__, 0 }
+    assert __ENV__.function == { :test_function_from___ENV__, 1 }
   end
 
   defp x(value) when value in [1,2,3], do: true

lib/elixir/test/elixir/macro_test.exs

@@ -296,7 +296,7 @@ defmodule MacroTest do
 
   test :env_stacktrace do
     env = __ENV__.file("foo").line(12)
-    assert env.stacktrace == [{ __MODULE__, :test_env_stacktrace, 0, [file: "foo", line: 12] }]
+    assert env.stacktrace == [{ __MODULE__, :test_env_stacktrace, 1, [file: "foo", line: 12] }]
     env = env.function(nil)
     assert env.stacktrace == [{ __MODULE__, :__MODULE__, 0, [file: "foo", line: 12] }]
     env = env.module(nil)

lib/ex_unit/lib/ex_unit.ex

@@ -13,11 +13,13 @@ defmodule ExUnit do
 
       # 2) Next we create a new TestCase and use ExUnit.Case
       defmodule AssertionTest do
-        # 3) Notice we pass async: true, this runs the test case in parallel
+        # 3) Notice we pass async: true, this runs the test case
+        #    concurrently with other test cases
         use ExUnit.Case, async: true
 
-        # 4) A test is a method which name finishes with _test
-        def test_always_pass do
+        # 4) A test is a function whose name starts with
+        #    test and receives a context
+        def test_always_pass(_) do
           assert true
         end
 

lib/ex_unit/lib/ex_unit/callbacks.ex

@@ -0,0 +1,190 @@
+defmodule ExUnit.Callbacks do
+  @moduledoc %B"""
+  This module defines four callbacks: `setup_all`, `teardown_all`,
+  `setup` and `teardown`. Those callbacks are defined via macros
+  and receives a keyword list of metadata. The callback may
+  optionally define extra data which will be available in the test
+  cases.
+
+  ## Examples
+
+      defmodule AssertionTest do
+        use ExUnit.Case, async: true
+
+        setup do
+          IO.puts "This is a setup callback"
+
+          # Return no extra meta data
+          [hello: "world"]
+        end
+
+        setup context do
+          # We can access the test name in the context
+          IO.puts "Setting up: #{context[:test]}"
+
+          # The metadata returned by the previous setup as well
+          assert context[:hello] == "world"
+        end
+
+        test "always pass" do
+          assert true
+        end
+      end
+
+  """
+
+  @doc false
+  defmacro __using__(_) do
+    quote do
+      @exunit_setup []
+      @exunit_teardown []
+      @exunit_setup_all []
+      @exunit_teardown_all []
+
+      @before_compile unquote(__MODULE__)
+      @after_compile unquote(__MODULE__)
+      import unquote(__MODULE__)
+
+      def __exunit__(:setup, context) do
+        context = __exunit_setup__(context)
+        ExUnit.Callbacks.__setup__(__MODULE__, context)
+      end
+
+      def __exunit__(:teardown, context) do
+        context = __exunit_teardown__(context)
+        ExUnit.Callbacks.__teardown__(__MODULE__, context)
+      end
+
+      def __exunit__(:setup_all, context) do
+        context = __exunit_setup_all__(context)
+        ExUnit.Callbacks.__setup_all__(__MODULE__, context)
+      end
+
+      def __exunit__(:teardown_all, context) do
+        context = __exunit_teardown_all__(context)
+        ExUnit.Callbacks.__teardown_all__(__MODULE__, context)
+      end
+    end
+  end
+
+  @doc false
+  defmacro __before_compile__(env) do
+    [ compile_callbacks(env, :exunit_setup),
+      compile_callbacks(env, :exunit_teardown),
+      compile_callbacks(env, :exunit_setup_all),
+      compile_callbacks(env, :exunit_teardown_all) ]
+  end
+
+  defmacro setup(var // quote(do: _), block) do
+    quote do
+      name = :"__exunit_setup_#{length(@exunit_setup)}"
+      defp name, [unquote(Macro.escape var)], [], unquote(Macro.escape block)
+      @exunit_setup [name|@exunit_setup]
+    end
+  end
+
+  defmacro teardown(var // quote(do: _), block) do
+    quote do
+      name = :"__exunit_teardown_#{length(@exunit_teardown)}"
+      defp name, [unquote(Macro.escape var)], [], unquote(Macro.escape block)
+      @exunit_teardown [name|@exunit_teardown]
+    end
+  end
+
+  defmacro setup_all(var // quote(do: _), block) do
+    quote do
+      name = :"__exunit_setup_all_#{length(@exunit_setup_all)}"
+      defp name, [unquote(Macro.escape var)], [], unquote(Macro.escape block)
+      @exunit_setup_all [name|@exunit_setup_all]
+    end
+  end
+
+  defmacro teardown_all(var // quote(do: _), block) do
+    quote do
+      name = :"__exunit_teardown_all_#{length(@exunit_teardown_all)}"
+      defp name, [unquote(Macro.escape var)], [], unquote(Macro.escape block)
+      @exunit_teardown_all [name|@exunit_teardown_all]
+    end
+  end
+
+  ## Helpers
+
+  defp compile_callbacks(env, kind) do
+    callbacks = Module.get_attribute(env.module, kind) |> Enum.reverse
+
+    acc =
+      Enum.reduce callbacks, quote(do: context), fn(callback, acc) ->
+        quote do
+          context = unquote(acc)
+          Keyword.merge(context, unquote(callback)(context))
+        end
+      end
+
+    quote do
+      defp unquote(:"__#{kind}__")(context), do: unquote(acc)
+    end
+  end
+
+  ## Deprecated handling
+
+  @doc false
+  def __after_compile__(env, _binary) do
+    test_case = env.module
+
+    Enum.each [:setup, :teardown, :setup_all, :teardown_all], fn(kind) ->
+      if Enum.any? 0..2, function_exported?(test_case, kind, &1) do
+        IO.puts "[Warning] #{kind} callback in #{inspect test_case} is deprecated. Please use the #{kind} macro instead."
+      end
+    end
+  end
+
+  @doc false
+  def __setup__(test_case, context) do
+    cond do
+      function_exported?(test_case, :setup, 2) ->
+        test_case.setup(context, context[:test])
+      function_exported?(test_case, :setup, 1) ->
+        test_case.setup(context)
+      function_exported?(test_case, :setup, 0) ->
+        test_case.setup
+      true ->
+        context
+    end
+  end
+
+  @doc false
+  def __teardown__(test_case, context) do
+    cond do
+      function_exported?(test_case, :teardown, 2) ->
+        test_case.teardown(context, context[:test])
+      function_exported?(test_case, :teardown, 1) ->
+        test_case.teardown(context)
+      function_exported?(test_case, :teardown, 0) ->
+        test_case.teardown
+      true ->
+        context
+    end
+  end
+
+  @doc false
+  def __teardown_all__(test_case, context) do
+    cond do
+      function_exported?(test_case, :teardown_all, 1) ->
+        test_case.teardown_all(context)
+      function_exported?(test_case, :teardown_all, 0) ->
+        test_case.teardown_all
+      true ->
+        context
+    end
+  end
+
+  @doc false
+  def __setup_all__(test_case, context) do
+    cond do
+      function_exported?(test_case, :setup_all, 0) ->
+        test_case.setup_all
+      true ->
+        context
+    end
+  end
+end

lib/ex_unit/lib/ex_unit/case.ex

@@ -9,46 +9,35 @@ defmodule ExUnit.Case do
              in parallel with others. Must be used for performance
              when your test cases do not change any global state;
 
-  ## Callbacks
+  This module automatically includes all callbacks defined
+  in `ExUnit.Callbacks`. Read it for more information.
 
-  `ExUnit.Case` defines four callbacks:
+ ## Examples
 
-  * `setup_all()` and `teardown_all(context)` which are executed
-     before and after all tests respectively;
-  * `setup(context, test)` and `teardown(context, test)` which are
-     executed before and after each test, receiving the test name
-     as argument;
+     defmodule AssertionTest do
+       use ExUnit.Case, async: true
 
-  Such callbacks are useful to clean up any side-effect a test may cause,
-  as for example, state in genservers, data on filesystem, or entries in
-  a database. Data can be passed in between such callbacks as context,
-  the context value returned by `setup_all` is passed down to all other
-  callbacks. The value can then be updated in `setup` which is passed
-  down to `teardown`.
-
-  ## Examples
-
-      defmodule AssertionTest do
-        use ExUnit.Case, async: true
-
-        def test_always_pass
-          assert true
-        end
-      end
+       def test_always_pass
+         assert true
+       end
+     end
 
   """
 
   @doc false
   defmacro __using__(opts // []) do
-    if Keyword.get(opts, :async, false) do
-      ExUnit.Server.add_async_case(__CALLER__.module)
-    else
-      ExUnit.Server.add_sync_case(__CALLER__.module)
-    end
+    async = Keyword.get(opts, :async, false)
 
     quote do
+      if unquote(async) do
+        ExUnit.Server.add_async_case(__MODULE__)
+      else
+        ExUnit.Server.add_sync_case(__MODULE__)
+      end
+
       import ExUnit.Assertions
       import ExUnit.Case
+      use ExUnit.Callbacks
     end
   end
 
@@ -67,7 +56,7 @@ defmodule ExUnit.Case do
       end
 
   """
-  defmacro test(message, contents) do
+  defmacro test(message, var // quote(do: _), contents) do
     contents =
       case contents do
         [do: _] ->
@@ -84,12 +73,15 @@ defmodule ExUnit.Case do
 
     quote do
       message = unquote(message)
+
       message = if is_binary(message) do
         :"test #{message}"
       else
         :"test_#{message}"
       end
-      def message, [], [], do: unquote(Macro.escape contents)
+
+      def message, [unquote(Macro.escape var)], [], do:
+        unquote(Macro.escape contents)
     end
   end
 end