Restructuring how the test suite is driven

src/spectator/config.cr

@@ -0,0 +1,5 @@
+module Spectator
+  # Provides customization and describes specifics for how Spectator will run and report tests.
+  class Config
+  end
+end

src/spectator/formatters/default_formatter.cr

@@ -16,7 +16,7 @@ module Spectator::Formatters
     def start_suite
     end
 
-    def end_suite(results : TestResults)
+    def end_suite(results : TestSuiteResults)
       puts
       puts
       display_failures(results)

src/spectator/formatters/formatter.cr

@@ -1,8 +1,26 @@
 module Spectator::Formatters
+  # Interface for reporting test progress and results.
+  #
+  # The methods should be called in this order:
+  # 1. `#start_suite`
+  # 2. `#start_example`
+  # 3. `#end_example`
+  # 4. `#end_suite`
+  #
+  # Steps 2 and 3 are called for each example in the suite.
   abstract class Formatter
+    # Called when a test suite is starting to execute.
     abstract def start_suite
-    abstract def end_suite(results : TestResults)
+
+    # Called when a test suite finishes.
+    # The results from the entire suite are provided.
+    abstract def end_suite(results : TestSuiteResults)
+
+    # Called before a test starts.
     abstract def start_example(example : Example)
+
+    # Called when a test finishes.
+    # The result of the test is provided.
     abstract def end_example(result : Result)
   end
 end

src/spectator/includes.cr

@@ -25,7 +25,9 @@ require "./root_example_group"
 
 require "./example_failed"
 require "./expectation_failed"
-require "./test_results"
+require "./config"
+require "./test_suite"
+require "./test_suite_results"
 require "./runner"
 
 require "./result"

src/spectator/runner.cr

@@ -1,4 +1,5 @@
 module Spectator
+  # Main driver for executing tests and feeding results to formatters.
   class Runner
     def initialize(@group : ExampleGroup,
                    @formatter : Formatters::Formatter = Formatters::DefaultFormatter.new)
@@ -16,7 +17,7 @@ module Spectator
           end.as(Result)
         end.to_a
       end
-      @formatter.end_suite(TestResults.new(results, elapsed))
+      @formatter.end_suite(TestSuiteResults.new(results, elapsed))
     end
   end
 end

src/spectator/test_suite.cr

@@ -0,0 +1,5 @@
+module Spectator
+  # Encapsulates the tests to run and additional properties about them.
+  class TestSuite
+  end
+end

src/spectator/test_suite_results.cr

@@ -1,5 +1,6 @@
 module Spectator
-  class TestResults
+  # Outcome of all tests in a suite.
+  class TestSuiteResults
     getter runtime : Time::Span
 
     @results : Array(Result)