Merge pull request #1201 from alco/exunit-docs

Extend ExUnit docs

Author: José Valim

lib/ex_unit/lib/ex_unit.ex

@@ -16,18 +16,19 @@ defmodule ExUnit do
   end
 
   @moduledoc """
-  Basic unit test structure for Elixir.
+  Basic unit testing framework for Elixir.
 
   ## Example
 
   A basic setup for ExUnit is shown below:
 
       # File: assertion_test.exs
 
-      # 1) Start ExUnit. You can pass some options as argument (list below)
+      # 1) Start ExUnit. You could also pass some options to the start function
+      # (see `configure/1` for the list of options)
       ExUnit.start
 
-      # 2) Next we create a new TestCase and use ExUnit.Case
+      # 2) Create a new test module (or "case") and use ExUnit.Case
       defmodule AssertionTest do
         # 3) Notice we pass async: true, this runs the test case
         #    concurrently with other test cases
@@ -45,20 +46,42 @@ defmodule ExUnit do
         end
       end
 
-  To run the test above, all you need to to is to run the file
+  To run the test above, all you need to do is to run the file
   using elixir from command line. Assuming you named your file
   assertion_test.exs, you can run it as:
 
       bin/elixir assertion_test.exs
 
   ## Case, callbacks and assertions
 
-  Check `ExUnit.Case` and `ExUnit.Callbacks` for more information about
+  See `ExUnit.Case` and `ExUnit.Callbacks` for more information about
   defining test cases.
 
   The `ExUnit.Assertions` module contains a set of macros to easily
   generate assertions with appropriate error messages.
 
+  ## Integration with Mix
+
+  Mix is the project management and build tool for Elixir. Invoking `mix test`
+  from the command line will run tests in each file matching the pattern
+  "*_test.exs" found in the `test` directory of your project.
+
+  By convention, you could also create a test_helper.exs file inside the
+  `test` directory and put the code common to all tests there.
+
+  The minimum example of a test_helper.exs file would be:
+
+    # test/test_helper.exs
+    ExUnit.start
+
+  Then, in each test file, require test_helper.exs before defining test modules
+  (or cases):
+
+    # test/myproject_test.exs
+    Code.require_file "test_helper.exs", __DIR__
+
+    # ... test cases follow
+
   """
 
   use Application.Behaviour

lib/ex_unit/lib/ex_unit/callbacks.ex

@@ -1,34 +1,71 @@
 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.
+  `setup` and `teardown`.
+
+  Those callbacks are defined via macros and each one can optionally receive a
+  keyword list with metadata, usually referred to as `context`. The callback
+  may optionally put extra data into `context` to be used in the tests.
+
+  **Note**: `setup` and `teardown` callbacks share the same context, it
+  provides an ExUnit.Test record associated with the `:test` key. `setup_all`
+  and `teardown_all` share their own context in a similar way, but this one
+  provides an ExUnit.TestCase record associated with the `:case` key.
+
+  If you return { :ok, <keyword list> } from `setup` or `teardown`, the keyword
+  list will get merged into the context that will be available in all
+  subsequent `setup`, `test`, or `teardown` calls.
+
+  Similarly, returning { :ok, <keyword list> } from `setup_all` or
+  `teardown_all` will merge the keyword list into the context that will be
+  available in all subsequent `setup_all` or `teardown_all` calls.
+
+  Returning :ok leaves the context unchanged in both cases.
+
+  Returning anything else from `setup` or `teardown` will force the current
+  test to fail, and subsequent `setup`, `test`, and `teardown` callbacks won't
+  be called for it.
+
+  Returning anything else from `setup_all` or `teardown_all` will force the
+  whole case to fail, and no other callback will be called.
+
+  It is allowed to define multiple `setup` or `teardown` callbacks, they will
+  be called sequentially in the order of definition before each test. The
+  returned keyword list from the last `setup` will be merged into the context passed to
+  the `test` and `teardown` (if defined) callbacks.
+
+  In the case of `setup_all` and `teardown_all` callbacks, each `setup_all`
+  will be called only once before the first test's `setup` and each
+  `teardown_all` will be called once after the last test. The returned keyword
+  list from the last `setup_all` will get merged into the context passed to the
+  `teardown_all` callbacks.
 
   ## Examples
 
       defmodule AssertionTest do
         use ExUnit.Case, async: true
 
+        # `setup` is called before each test is run
         setup do
           IO.puts "This is a setup callback"
 
-          # Returns extra metadata
+          # Return extra metadata, it has to be a keyword list
           { :ok, [hello: "world"] }
         end
 
+        # Same as `setup`, but receives the context for the current test
         setup context do
-          # We can access the test name in the context
+          # We can access the test record in the context
           IO.puts "Setting up: #{context[:test]}"
 
-          # The metadata returned by the previous setup as well
+          # We can also access the data returned from `setup/0`
           assert context[:hello] == "world"
 
           # No metadata
           :ok
         end
 
+        # This is called after each test finishes
         teardown context do
           assert context[:hello] == "world"
           :ok
@@ -37,6 +74,10 @@ defmodule ExUnit.Callbacks do
         test "always pass" do
           assert true
         end
+
+        test "another one", context do
+          assert context[:hello] == "world"
+        end
       end
 
   """
@@ -96,8 +137,8 @@ defmodule ExUnit.Callbacks do
   end
 
   @doc """
-  Called after the finish of each test. Note that, if the test crasches with an exit
-  message `teardown` will not be run.
+  Called after the finish of each test. Note that if the test crashed with an :exit
+  message, `teardown` will not be run.
   """
   defmacro teardown(var // quote(do: _), block) do
     quote do
@@ -108,7 +149,8 @@ defmodule ExUnit.Callbacks do
   end
 
   @doc """
-  Called before the start of a case.
+  Called before the start of a case, i.e. called once before the first test in
+  the current module and before any `setup` callbacks.
   """
   defmacro setup_all(var // quote(do: _), block) do
     quote do
@@ -119,7 +161,7 @@ defmodule ExUnit.Callbacks do
   end
 
   @doc """
-  Called after the finish of each case.
+  Called once after the last test finishes without emitting an :exit message.
   """
   defmacro teardown_all(var // quote(do: _), block) do
     quote do
@@ -131,6 +173,7 @@ defmodule ExUnit.Callbacks do
 
   ## Helpers
 
+  @doc false
   def __merge__(_mod, other, :ok), do: other
   def __merge__(_mod, other, { :ok, data }) when is_list(data), do: Keyword.merge(other, data)
   def __merge__(mod, _, failure) do

lib/ex_unit/lib/ex_unit/case.ex

@@ -9,15 +9,18 @@ defmodule ExUnit.Case do
              in parallel with others. Must be used for performance
              when your test cases do not change any global state;
 
-  This module automatically includes all callbacks defined
-  in `ExUnit.Callbacks`. Read it for more information.
+  This module automatically includes all callbacks defined in
+  `ExUnit.Callbacks`. See that module's documentation for more
+  information.
 
- ## Examples
+  ## Examples
 
      defmodule AssertionTest do
+       # Use the module
        use ExUnit.Case, async: true
 
-       def test_always_pass
+       # The `test` macro is imported by ExUnit.Case
+       test "always pass" do
          assert true
        end
      end