Add start_supervised/2 and stop_supervised/1 to ExUnit (#6193)

Author: josevalim

lib/elixir/test/elixir/registry_test.exs

@@ -9,8 +9,8 @@ defmodule RegistryTest do
     partitions = config[:partitions] || 1
     listeners = List.wrap(config[:listener])
     opts = [keys: keys, name: config.test, partitions: partitions, listeners: listeners]
-    {:ok, sup} = Supervisor.start_link([{Registry, opts}], strategy: :one_for_one)
-    {:ok, %{registry: config.test, partitions: partitions, sup: sup}}
+    {:ok, _} = start_supervised({Registry, opts})
+    {:ok, %{registry: config.test, partitions: partitions}}
   end
 
   for {describe, partitions} <- ["with 1 partition": 1, "with 8 partitions": 8] do

lib/ex_unit/lib/ex_unit/callbacks.ex

@@ -3,29 +3,43 @@ defmodule ExUnit.Callbacks do
   Defines ExUnit callbacks.
 
   This module defines both `setup_all` and `setup` callbacks, as well as
-  the `on_exit/2` function.
+  the `on_exit/2`, `start_supervised/2` and `stop_supervised/1` functions.
 
   The setup callbacks are defined via macros and each one can optionally
   receive a map with metadata, usually referred to as `context`. The
   callback may optionally put extra data into the `context` to be used in
   the tests.
 
-  The `setup_all` callbacks are invoked only once to setup the test case before any
-  test is run and all `setup` callbacks are run before each test. No callback
+  The `setup_all` callbacks are invoked only once per module, before any
+  test runs. All `setup` callbacks are run before each test. No callback
   runs if the test case has no tests or all tests have been filtered out.
 
+  `start_supervised/2` is used to start processes under a supervisor. The
+  supervisor is linked to the current test process. The supervisor as well
+  as all child processes are guaranteed to terminate before any `on_exit/2`
+  callback runs.
+
   `on_exit/2` callbacks are registered on demand, usually to undo an action
   performed by a setup callback. `on_exit/2` may also take a reference,
   allowing callback to be overridden in the future. A registered `on_exit/2`
   callback always runs, while failures in `setup` and `setup_all` will stop
   all remaining setup callbacks from executing.
 
-  Finally, `setup_all` callbacks run in the test case process, while all
-  `setup` callbacks run in the same process as the test itself. `on_exit/2`
-  callbacks always run in a separate process than the test case or the
-  test itself. Since the test process exits with reason `:shutdown`, most
-  of times `on_exit/2` can be avoided as processes are going to clean
-  up on their own.
+  Finally, `setup_all` callbacks run in a separate process per module, while
+  all `setup` callbacks run in the same process as the test itself. `on_exit/2`
+  callbacks always run in a separate process, as implied by their name. The
+  test process always exits with reason `:shutdown`, which means any process
+  linked to the test process will also exit, although asynchronously. Therefore
+  it is preferred to use `start_supervised/2` to guarantee synchronous termination.
+
+  Here is a run down of the life-cycle of the test process:
+
+    1. the test process is spawned
+    2. it runs `setup/2` callbacks
+    3. it runs the test itself
+    4. it stops all supervised processes
+    5. the test process exits with reason `:shutdown`
+    6. `on_exit/2` callbacks are executed in a separate process
 
   ## Context
 
@@ -49,41 +63,40 @@ defmodule ExUnit.Callbacks do
       defmodule AssertionTest do
         use ExUnit.Case, async: true
 
-        # "setup_all" is called once to setup the case before any test is run
+        # "setup_all" is called once per module before any test runs
         setup_all do
           IO.puts "Starting AssertionTest"
 
           # No context is returned here
           :ok
         end
 
-        # "setup" is called before each test is run
+        # "setup" is called before each test
         setup do
-          IO.puts "This is a setup callback"
+          IO.puts "This is a setup callback for #{inspect self()}"
 
           on_exit fn ->
-            IO.puts "This is invoked once the test is done"
+            IO.puts "This is invoked once the test is done. Process: #{inspect self()}"
           end
 
           # Returns extra metadata to be merged into context
           [hello: "world"]
         end
 
-        # Same as "setup", but receives the context
-        # for the current test
+        # Same as above, but receives the context as argument
         setup context do
-          IO.puts "Setting up: #{context[:test]}"
+          IO.puts "Setting up: #{context.test}"
           :ok
         end
 
-        # Setups can also invoke a local or imported function that can return a context
+        # Setups can also invoke a local or imported function that returns a context
         setup :invoke_local_or_imported_function
 
         test "always pass" do
           assert true
         end
 
-        test "another one", context do
+        test "uses metadata from setup", context do
           assert context[:hello] == "world"
         end
 
@@ -198,15 +211,16 @@ defmodule ExUnit.Callbacks do
   end
 
   @doc """
-  Defines a callback that runs on the test (or test case) exit.
+  Defines a callback that runs once the test exits.
 
   `callback` is a function that receives no arguments and
   runs in a separate process than the caller.
 
-  `on_exit/2` is usually called from `setup` and `setup_all` callbacks,
-  often to undo the action performed during `setup`. However, `on_exit/2`
-  may also be called dynamically, where a reference can be used to
-  guarantee the callback will be invoked only once.
+  `on_exit/2` is usually called from `setup` and `setup_all`
+  callbacks, often to undo the action performed during `setup`.
+  However, `on_exit/2` may also be called dynamically, where a
+  reference can be used to guarantee the callback will be invoked
+  only once.
   """
   @spec on_exit(term, (() -> term)) :: :ok | no_return
   def on_exit(name_or_ref \\ make_ref(), callback) when is_function(callback, 0) do
@@ -217,6 +231,85 @@ defmodule ExUnit.Callbacks do
     end
   end
 
+  @supervisor_opts [strategy: :one_for_one, max_restarts: 1_000_000, max_seconds: 1]
+
+  @doc """
+  Starts a child process under the test supervisor.
+
+  It expects a child specification or a module, similar to the ones
+  given to `Supervisor.start_link/2`. For example, if your application
+  starts a supervision tree by running:
+
+      Supervisor.start_link([MyServer, {OtherSupervisor, ...}], ...)
+
+  You can start those processes under test in isolation by running:
+
+      start_supervised(MyServer)
+      start_supervised({OtherSupervisor, :initial_value})
+
+  A keyword list can also be given if there is a need to change
+  the child specification for the given child process:
+
+      start_supervised({MyServer, :initial_value}, restart: :temporary)
+
+  See the `Supervisor` module for a discussion on child specifications
+  and the available specification keys.
+
+  The advantage of starting a process under the test supervisor is that
+  it is guaranteed to exit before the next test starts. Furthermore,
+  because the child process is supervised, it will be restarted in case
+  of crashes according to the `:restart` strategy in the child
+  specification, even if stopped manually. Therefore, to guarantee a
+  process started with `start_supervised/2` terminates without restarts,
+  see `stop_supervised/1`.
+
+  This function returns `{:ok, pid}` in case of success, otherwise it
+  returns `{:error, reason}`.
+  """
+  @spec start_supervised(Supervisor.child_spec | module | {module, term}, keyword) ::
+        Supervisor.on_start_child
+  def start_supervised(child_spec_or_module, opts \\ []) do
+    sup =
+      case ExUnit.OnExitHandler.get_supervisor(self()) do
+        {:ok, nil} ->
+          {:ok, sup} = Supervisor.start_link([], @supervisor_opts)
+          ExUnit.OnExitHandler.put_supervisor(self(), sup)
+          sup
+        {:ok, sup} ->
+          sup
+        :error ->
+          raise ArgumentError, "start_supervised/2 can only be invoked from the test process"
+      end
+
+    Supervisor.start_child(sup, Supervisor.child_spec(child_spec_or_module, opts))
+  end
+
+  @doc """
+  Stops a child process started via `start_supervised/2`.
+
+  This function expects the `id` in the child specification.
+  For example:
+
+      {:ok, _} = start_supervised(MyServer)
+      :ok = stop_supervised(MyServer)
+
+  It returns `:ok` if there is a supervised process with such
+  `id`, `{:error, :not_found}` otherwise.
+  """
+  @spec stop_supervised(id :: term()) :: :ok | {:error, :not_found}
+  def stop_supervised(id) do
+    case ExUnit.OnExitHandler.get_supervisor(self()) do
+      {:ok, nil} ->
+        {:error, :not_found}
+      {:ok, sup} ->
+        with :ok <- Supervisor.terminate_child(sup, id),
+             :ok <- Supervisor.delete_child(sup, id),
+             do: :ok
+      :error ->
+        raise ArgumentError, "stop_supervised/1 can only be invoked from the test process"
+    end
+  end
+
   ## Helpers
 
   @reserved [:case, :file, :line, :test, :async, :registered, :describe]
@@ -238,7 +331,6 @@ defmodule ExUnit.Callbacks do
     merge(mod, context, value, value)
   end
 
-  @doc false
   defp merge(_mod, context, :ok, _original_value) do
     context
   end

lib/ex_unit/lib/ex_unit/case.ex

@@ -4,7 +4,7 @@ end
 
 defmodule ExUnit.Case do
   @moduledoc """
-  Sets up an ExUnit test case.
+  Helpers for defining test cases.
 
   This module must be used in other modules as a way to configure
   and prepare them for testing.
@@ -16,8 +16,10 @@ defmodule ExUnit.Case do
       does not change any global state. Defaults to `false`.
 
   This module automatically includes all callbacks defined in
-  `ExUnit.Callbacks`. See that module's documentation for more
-  information.
+  `ExUnit.Callbacks`. See that module for more information on `setup`,
+  `start_supervised`, `on_exit` and the test process lifecycle.
+
+  For grouping tests together, see `describe/2` in this module.
 
   ## Examples
 
@@ -41,7 +43,7 @@ defmodule ExUnit.Case do
 
         setup do
           {:ok, pid} = KV.start_link
-          {:ok, [pid: pid]}
+          {:ok, pid: pid}
         end
 
         test "stores key-value pairs", context do
@@ -183,20 +185,21 @@ defmodule ExUnit.Case do
 
   ## Log Capture
 
-  ExUnit can optionally suppress printing of log messages that are generated during a test. Log
-  messages generated while running a test are captured and only if the test fails are they printed
-  to aid with debugging.
+  ExUnit can optionally suppress printing of log messages that are generated
+  during a test. Log messages generated while running a test are captured and
+  only if the test fails are they printed to aid with debugging.
 
-  You can opt into this behaviour for individual tests by tagging them with `:capture_log` or enable
-  log capture for all tests in the ExUnit configuration:
+  You can opt into this behaviour for individual tests by tagging them with
+  `:capture_log` or enable log capture for all tests in the ExUnit configuration:
 
       ExUnit.start(capture_log: true)
 
-  This default can be overridden by `@tag capture_log: false` or `@moduletag capture_log: false`.
+  This default can be overridden by `@tag capture_log: false` or
+  `@moduletag capture_log: false`.
 
-  Since `setup_all` blocks don't belong to a specific test, log messages generated in them (or
-  between tests) are never captured. If you want to suppress these messages as well, remove the
-  console backend globally:
+  Since `setup_all` blocks don't belong to a specific test, log messages generated
+  in them (or between tests) are never captured. If you want to suppress these
+  messages as well, remove the console backend globally:
 
       config :logger, backends: []
   """