minitest 5.0.3 → 5.0.4

data/History.txt

@@ -1,3 +1,13 @@
+=== 5.0.4 / 2013-06-07
+
+* 5 minor enhancements:
+
+  * Added AbstractReporter, defining required Reporter API to quack properly.
+  * Added doco for writing reporters.
+  * Refactored Reporter into ProgressReporter and SummaryReporter. (idea: phiggins, code:me+scotch)
+  * Refactored SummaryReporter pushing up to StatisticsReporter. (phiggins)
+  * Removed Reporter#run_and_report... cleaner, but doesn't "fit" in the API.
+
 === 5.0.3 / 2013-05-29
 
 * 4 minor enhancements:

data/README.txt

@@ -245,12 +245,52 @@ bogus example:
       def self.plugin_bogus_options(opts, options)
         opts.on "--myci", "Report results to my CI" do
           options[:myci] = true
+          options[:myci_addr] = get_myci_addr
+          options[:myci_port] = get_myci_port
         end
       end
 
       def self.plugin_bogus_init(options)
-        ARGV << "-p" # all pride, all the time
-        self.reporter << MyCI.new if options[:myci]
+        self.reporter << MyCI.new(options) if options[:myci]
+      end
+    end
+
+=== Adding custom reporters
+
+Minitest uses composite reporter to output test results using multiple
+reporter instances. You can add new reporters to the composite during
+the init_plugins phase. As we saw in +plugin_bonus_init+ above, you
+simply add your reporter instance to the composite via +<<+.
+
++AbstractReporter+ defines the API for reporters. You may subclass it
+and override any method you want to achieve your desired behavior.
+
+start   :: Called when the run has started.
+record  :: Called for each result, passed or otherwise.
+report  :: Called at the end of the run.
+passed? :: Called to see if you detected any problems.
+
+Using our example above, here is how we might implement MyCI:
+
+    # minitest/bogus_plugin.rb
+
+    module Minitest
+      class MyCI < AbstractReporter
+        attr_accessor :results, :addr, :port
+
+        def initialize options
+          self.results = []
+          self.addr = options[:myci_addr]
+          self.port = options[:myci_port]
+        end
+
+        def record result
+          self.results << result
+        end
+
+        def report
+          CI.connect(addr, port).send_results self.results
+        end
       end
     end
 
@@ -356,6 +396,7 @@ minitest-instrument         :: Instrument ActiveSupport::Notifications when
 minitest-instrument-db      :: Store information about speed of test
                                execution provided by minitest-instrument in database
 minitest-libnotify          :: Test notifier for minitest via libnotify.
+minitest-line               :: Run test at line number
 minitest-macruby            :: Provides extensions to minitest for macruby UI testing.
 minitest-matchers           :: Adds support for RSpec-style matchers to minitest.
 minitest-metadata           :: Annotate tests with metadata (key-value).

data/lib/minitest.rb

@@ -4,7 +4,7 @@ require "optparse"
 # :include: README.txt
 
 module Minitest
-  VERSION = "5.0.3" # :nodoc:
+  VERSION = "5.0.4" # :nodoc:
 
   @@installed_at_exit ||= false
   @@after_run = []
@@ -94,7 +94,7 @@ module Minitest
   #         Runnable.runnables.each
   #           runnable.run(reporter, options)
   #             self.runnable_methods.each
-  #               self.new.run runnable_method
+  #               self.new(runnable_method).run
 
   def self.run args = []
     self.load_plugins
@@ -102,15 +102,16 @@ module Minitest
     options = process_args args
 
     reporter = CompositeReporter.new
-    reporter << Reporter.new(options[:io], options)
+    reporter << ProgressReporter.new(options[:io], options)
+    reporter << SummaryReporter.new(options[:io], options)
 
     self.reporter = reporter # this makes it available to plugins
     self.init_plugins options
     self.reporter = nil # runnables shouldn't depend on the reporter, ever
 
-    reporter.run_and_report do
-      __run reporter, options
-    end
+    reporter.start
+    __run reporter, options
+    reporter.report
 
     reporter.passed?
   end
@@ -362,19 +363,38 @@ module Minitest
   end
 
   ##
-  # Collects and reports the result of all runs.
+  # Defines the API for Reporters. Subclass this and override whatever
+  # you want. Go nuts.
 
-  class Reporter
+  class AbstractReporter
     ##
-    # The count of assertions run.
+    # Starts reporting on the run.
 
-    attr_accessor :assertions
+    def start
+    end
 
     ##
-    # The count of runnable methods ran.
+    # Record a result and output the Runnable#result_code. Stores the
+    # result of the run if the run did not pass.
 
-    attr_accessor :count
+    def record result
+    end
 
+    ##
+    # Outputs the summary of the run.
+
+    def report
+    end
+
+    ##
+    # Did this run pass?
+
+    def passed?
+      true
+    end
+  end
+
+  class Reporter < AbstractReporter # :nodoc:
     ##
     # The IO used to report.
 
@@ -385,118 +405,151 @@ module Minitest
 
     attr_accessor :options
 
-    ##
-    # The results of all the runs. (Non-passing only to cut down on memory)
+    def initialize io = $stdout, options = {} # :nodoc:
+      self.io      = io
+      self.options = options
+    end
+  end
 
-    attr_accessor :results
+  ##
+  # A very simple reporter that prints the "dots" during the run.
+  #
+  # This is added to the top-level CompositeReporter at the start of
+  # the run. If you want to change the output of minitest via a
+  # plugin, pull this out of the composite and replace it with your
+  # own.
 
-    ##
-    # The start time of the run.
+  class ProgressReporter < Reporter
+    def record result # :nodoc:
+      io.print "%s#%s = %.2f s = " % [result.class, result.name, result.time] if
+        options[:verbose]
+      io.print result.result_code
+      io.puts if options[:verbose]
+    end
+  end
 
-    attr_accessor :start_time
+  ##
+  # A reporter that gathers statistics about a test run. Does not do
+  # any IO because meant to be used as a parent class for a reporter
+  # that does.
+  #
+  # If you want to create an entirely different type of output (eg,
+  # CI, HTML, etc), this is the place to start.
 
-    attr_accessor :sync, :old_sync # :nodoc:
+  class StatisticsReporter < Reporter
+    # :stopdoc:
+    attr_accessor :assertions
+    attr_accessor :count
+    attr_accessor :results
+    attr_accessor :start_time
+    attr_accessor :total_time
+    attr_accessor :failures
+    attr_accessor :errors
+    attr_accessor :skips
+    # :startdoc:
 
     def initialize io = $stdout, options = {} # :nodoc:
-      self.io      = io
-      self.options = options
+      super
 
       self.assertions = 0
       self.count      = 0
       self.results    = []
       self.start_time = nil
+      self.total_time = nil
+      self.failures   = nil
+      self.errors     = nil
+      self.skips      = nil
     end
 
-    ##
-    # Did this run pass?
-
-    def passed?
+    def passed? # :nodoc:
       results.all?(&:skipped?)
     end
 
-    ##
-    # Top-level method to ensure that start and report are called.
-    # Yields to the caller.
+    def start # :nodoc:
+      self.start_time = Time.now
+    end
 
-    def run_and_report
-      start
+    def record result # :nodoc:
+      self.count += 1
+      self.assertions += result.assertions
 
-      yield
+      results << result if not result.passed? or result.skipped?
+    end
 
-      io.sync = self.old_sync if self.sync
-      report
+    def report # :nodoc:
+      aggregate = results.group_by { |r| r.failure.class }
+      aggregate.default = [] # dumb. group_by should provide this
+
+      self.total_time = Time.now - start_time
+      self.failures   = aggregate[Assertion].size
+      self.errors     = aggregate[UnexpectedError].size
+      self.skips      = aggregate[Skip].size
     end
+  end
 
-    ##
-    # Starts reporting on the run.
+  ##
+  # A reporter that prints the header, summary, and failure details at
+  # the end of the run.
+  #
+  # This is added to the top-level CompositeReporter at the start of
+  # the run. If you want to change the output of minitest via a
+  # plugin, pull this out of the composite and replace it with your
+  # own.
 
-    def start
-      self.sync = io.respond_to? :"sync=" # stupid emacs
-      self.old_sync, io.sync = io.sync, true if self.sync
+  class SummaryReporter < StatisticsReporter
+    # :stopdoc:
+    attr_accessor :sync
+    attr_accessor :old_sync
+    # :startdoc:
 
-      self.start_time = Time.now
+    def start # :nodoc:
+      super
 
       io.puts "Run options: #{options[:args]}"
       io.puts
       io.puts "# Running:"
       io.puts
-    end
-
-    ##
-    # Record a result and output the Runnable#result_code. Stores the
-    # result of the run if the run did not pass.
 
-    def record result
-      self.count += 1
-      self.assertions += result.assertions
-
-      io.print "%s#%s = %.2f s = " % [result.class, result.name, result.time] if
-        options[:verbose]
-      io.print result.result_code
-      io.puts if options[:verbose]
-
-      results << result if not result.passed? or result.skipped?
+      self.sync = io.respond_to? :"sync=" # stupid emacs
+      self.old_sync, io.sync = io.sync, true if self.sync
     end
 
-    ##
-    # Outputs the summary of the run.
-
-    def report
-      aggregate = results.group_by { |r| r.failure.class }
-      aggregate.default = [] # dumb. group_by should provide this
+    def report # :nodoc:
+      super
 
-      f = aggregate[Assertion].size
-      e = aggregate[UnexpectedError].size
-      s = aggregate[Skip].size
-      t = Time.now - start_time
+      io.sync = self.old_sync
 
       io.puts # finish the dots
       io.puts
-      io.puts "Finished in %.6fs, %.4f runs/s, %.4f assertions/s." %
-        [t, count / t, self.assertions / t]
-
-      format = "%d runs, %d assertions, %d failures, %d errors, %d skips"
-      summary = format % [count, self.assertions, f, e, s]
-
-      io.print self
-      io.puts
+      io.puts statistics
+      io.puts aggregated_results
       io.puts summary
     end
 
-    def to_s # :nodoc:
+    def statistics # :nodoc:
+      "Finished in %.6fs, %.4f runs/s, %.4f assertions/s." %
+        [total_time, count / total_time, assertions / total_time]
+    end
+
+    def aggregated_results # :nodoc:
       filtered_results = results.dup
       filtered_results.reject!(&:skipped?) unless options[:verbose]
 
       filtered_results.each_with_index.map do |result, i|
         "\n%3d) %s" % [i+1, result]
-      end.join "\n"
+      end.join("\n") + "\n"
+    end
+
+    def summary # :nodoc:
+      "%d runs, %d assertions, %d failures, %d errors, %d skips" %
+        [count, assertions, failures, errors, skips]
     end
   end
 
   ##
   # Dispatch to multiple reporters as one.
 
-  class CompositeReporter < Reporter
+  class CompositeReporter < AbstractReporter
     ##
     # The list of reporters to dispatch to.
 
@@ -602,7 +655,7 @@ module Minitest
   ##
   # Provides a simple set of guards that you can use in your tests
   # to skip execution if it is not applicable. These methods are
-  # mixed into TestCase as both instance and class methods so you
+  # mixed into Test as both instance and class methods so you
   # can use them inside or outside of the test methods.
   #
   #   def test_something_for_mri
@@ -624,7 +677,7 @@ module Minitest
     end
 
     ##
-    # Is this running on mri?
+    # Is this running on maglev?
 
     def maglev? platform = defined?(RUBY_ENGINE) && RUBY_ENGINE
       "maglev" == platform

data/lib/minitest/spec.rb

@@ -197,7 +197,7 @@ class Minitest::Spec < Minitest::Test
     #
     # This is also aliased to #specify and doesn't require a +desc+ arg.
     #
-    # Hint: If you _do_ want inheritence, use minitest/unit. You can mix
+    # Hint: If you _do_ want inheritence, use minitest/test. You can mix
     # and match between assertions and expectations as much as you want.
 
     def it desc = "anonymous", &block

data/lib/minitest/test.rb

@@ -25,8 +25,8 @@ module Minitest
     end
 
     ##
-    # Make diffs for this TestCase use #pretty_inspect so that diff
-    # in assert_equal can be more details. NOTE: this is much slower
+    # Make diffs for this Test use #pretty_inspect so that diff
+    # in assert_equal can have more details. NOTE: this is much slower
     # than the regular inspect but much more usable for complex
     # objects.
 

data/test/minitest/metametameta.rb

@@ -15,7 +15,11 @@ class MetaMetaMetaTestCase < Minitest::Test
     options = Minitest.process_args flags
 
     @output = StringIO.new("")
-    self.reporter = Minitest::Reporter.new @output, options
+
+    self.reporter = Minitest::CompositeReporter.new
+    reporter << Minitest::SummaryReporter.new(@output, options)
+    reporter << Minitest::ProgressReporter.new(@output, options)
+
     reporter.start
 
     @tus ||= [@tu]
@@ -28,6 +32,10 @@ class MetaMetaMetaTestCase < Minitest::Test
     reporter.report
   end
 
+  def first_reporter
+    reporter.reporters.first
+  end
+
   def assert_report expected, flags = %w[--seed 42]
     header = clean <<-EOM
       Run options: #{flags.map { |s| s =~ /\|/ ? s.inspect : s }.join " "}

data/test/minitest/test_minitest_reporter.rb

@@ -5,9 +5,33 @@ class TestMinitestReporter < Minitest::Test
 
   attr_accessor :r, :io
 
+  def new_composite_reporter
+    reporter = Minitest::CompositeReporter.new
+    reporter << Minitest::SummaryReporter.new(self.io)
+    reporter << Minitest::ProgressReporter.new(self.io)
+
+    def reporter.first
+      reporters.first
+    end
+
+    def reporter.results
+      first.results
+    end
+
+    def reporter.count
+      first.count
+    end
+
+    def reporter.assertions
+      first.assertions
+    end
+
+    reporter
+  end
+
   def setup
     self.io = StringIO.new("")
-    self.r  = Minitest::Reporter.new io
+    self.r  = new_composite_reporter
   end
 
   def error_test

data/test/minitest/test_minitest_unit.rb

@@ -432,7 +432,7 @@ class TestMinitestRunner < MetaMetaMetaTestCase
       def self.name; "wacky!" end
 
       def self.before_my_suite
-        @reporter.io.puts "Running #{self.name} tests"
+        @reporter.reporters.first.io.puts "Running #{self.name} tests"
         @@foo = 1
       end
 
@@ -1750,7 +1750,7 @@ class TestMinitestUnitRecording < MetaMetaMetaTestCase
 
     run_tu_with_fresh_reporter
 
-    recorded = reporter.results.map(&:failures).flatten.map { |f| f.error.class }
+    recorded = first_reporter.results.map(&:failures).flatten.map { |f| f.error.class }
 
     assert_equal expected, recorded
   end
@@ -1828,7 +1828,7 @@ class TestMinitestUnitRecording < MetaMetaMetaTestCase
           FILE:LINE:in `teardown'
     "
 
-    assert_equal exp.strip, normalize_output(reporter.results.first.to_s).strip
+    assert_equal exp.strip, normalize_output(first_reporter.results.first.to_s).strip
   end
 
   def test_record_skip

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: minitest
 version: !ruby/object:Gem::Version 
-  hash: 49
+  hash: 63
   prerelease: 
   segments: 
   - 5
   - 0
-  - 3
-  version: 5.0.3
+  - 4
+  version: 5.0.4
 platform: ruby
 authors: 
 - Ryan Davis
@@ -36,7 +36,7 @@ cert_chain:
   FBHgymkyj/AOSqKRIpXPhjC6
   -----END CERTIFICATE-----
 
-date: 2013-05-30 00:00:00 Z
+date: 2013-06-07 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rdoc