✨ Add new TestRunner behaviour for custom runners (#115)

Use the behaviour for all internal implementations including for tests. Also, convert a second DummyRunner to use `start_supervised!`.

README.md

@@ -231,8 +231,8 @@ ignore files with any of these extensions, you can specify an `exclude` regexp
 By default `mix test.interactive` uses an internal module named
 `MixTestInteractive.PortRunner` to run the tests. If you want to run the tests
 in a different way, you can supply your own runner module instead. Your module
-must implement a `run/2` function that takes a `MixTestInteractive.Config`
-struct and a list of `String.t()` arguments.
+must implement the `MixTestInteractive.TestRunner` behaviour, either implicitly
+or explicitly.
 
 ```elixir
 # config/config.exs

lib/mix_test_interactive/command_line_parser.ex

@@ -262,7 +262,10 @@ defmodule MixTestInteractive.CommandLineParser do
     if function_exported?(module, :run, 2) do
       {:ok, module}
     else
-      {:error, UsageError.exception("--runner: '#{runner}' must name a module that implements a `run/2` function")}
+      {:error,
+       UsageError.exception(
+         "--runner: '#{runner}' must name a module that implements the `MixTestInteractive.TestRunner` behaviour"
+       )}
     end
   end
 

lib/mix_test_interactive/port_runner.ex

@@ -9,8 +9,10 @@ defmodule MixTestInteractive.PortRunner do
   On Windows, `mix` is run directly and ANSI mode is not enabled, as it is not always
   supported by Windows command processors.
   """
+  @behaviour MixTestInteractive.TestRunner
 
   alias MixTestInteractive.Config
+  alias MixTestInteractive.TestRunner
 
   @application :mix_test_interactive
 
@@ -22,7 +24,7 @@ defmodule MixTestInteractive.PortRunner do
   @doc """
   Run tests based on the current configuration.
   """
-  @spec run(Config.t(), [String.t()], os_type(), runner()) :: :ok
+  @impl TestRunner
   def run(%Config{} = config, task_args, os_type \\ :os.type(), runner \\ &System.cmd/3) do
     {command, command_args} = config.command
 

lib/mix_test_interactive/test_runner.ex

@@ -0,0 +1,11 @@
+defmodule MixTestInteractive.TestRunner do
+  @moduledoc """
+  Behaviour for custom test runners.
+
+  Any custom runner defined in the configuration or by command-line options must
+  implement this behaviour, either explicitly or implicitly.
+  """
+  alias MixTestInteractive.Config
+
+  @callback run(Config.t(), [String.t()]) :: :ok
+end

test/mix_test_interactive/command_line_parser_test.exs

@@ -7,7 +7,12 @@ defmodule MixTestInteractive.CommandLineParserTest do
 
   defmodule CustomRunner do
     @moduledoc false
-    def run(_config, _args), do: :noop
+    @behaviour MixTestInteractive.TestRunner
+
+    alias MixTestInteractive.TestRunner
+
+    @impl TestRunner
+    def run(_config, _args), do: :ok
   end
 
   defmodule NotARunner do

test/mix_test_interactive/end_to_end_test.exs

@@ -7,17 +7,24 @@ defmodule MixTestInteractive.EndToEndTest do
 
   defmodule DummyRunner do
     @moduledoc false
+    @behaviour MixTestInteractive.TestRunner
+
     use Agent
 
+    alias MixTestInteractive.TestRunner
+
     def start_link(test_pid) do
       Agent.start_link(fn -> test_pid end, name: __MODULE__)
     end
 
+    @impl TestRunner
     def run(config, args) do
       Agent.update(__MODULE__, fn test_pid ->
         send(test_pid, {config, args})
         test_pid
       end)
+
+      :ok
     end
   end
 

test/mix_test_interactive/runner_test.exs

@@ -8,13 +8,24 @@ defmodule MixTestInteractive.RunnerTest do
 
   defmodule DummyRunner do
     @moduledoc false
+    @behaviour MixTestInteractive.TestRunner
+
+    use Agent
+
+    alias MixTestInteractive.TestRunner
+
+    def start_link(initial_state) do
+      Agent.start_link(fn -> initial_state end, name: __MODULE__)
+    end
+
+    @impl TestRunner
     def run(config, args) do
       Agent.get_and_update(__MODULE__, fn data -> {:ok, [{config, args} | data]} end)
     end
   end
 
   setup do
-    {:ok, _} = Agent.start_link(fn -> [] end, name: DummyRunner)
+    _pid = start_supervised!({DummyRunner, []})
     :ok
   end