minitest 1.3.0 → 6.0.6

data/lib/minitest/test.rb

@@ -0,0 +1,232 @@
+require_relative "../minitest" unless defined? Minitest::Runnable
+
+module Minitest
+  ##
+  # Subclass Test to create your own tests. Typically you'll want a
+  # Test subclass per implementation class.
+  #
+  # See Minitest::Assertions
+
+  class Test < Runnable
+    require_relative "assertions"
+    include Minitest::Reportable
+    include Minitest::Assertions
+
+    PASSTHROUGH_EXCEPTIONS = [NoMemoryError, SignalException, SystemExit] # :nodoc:
+
+    SETUP_METHODS = %w[ before_setup setup after_setup ] # :nodoc:
+
+    TEARDOWN_METHODS = %w[ before_teardown teardown after_teardown ] # :nodoc:
+
+    # :stopdoc:
+    class << self; attr_accessor :io_lock; end
+    self.io_lock = Mutex.new
+    # :startdoc:
+
+    ##
+    # Call this at the top of your tests when you absolutely
+    # positively need to have ordered tests. In doing so, you're
+    # admitting that you suck and your tests are weak.
+
+    def self.i_suck_and_my_tests_are_order_dependent!
+      class << self
+        undef_method :run_order if method_defined? :run_order
+        define_method :run_order do :alpha end
+      end
+    end
+
+    ##
+    # 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.
+
+    def self.make_my_diffs_pretty!
+      require "pp"
+
+      define_method :mu_pp, &:pretty_inspect
+    end
+
+    ##
+    # Call this at the top of your tests (inside the +Minitest::Test+
+    # subclass or +describe+ block) when you want to run your tests in
+    # parallel. In doing so, you're admitting that you rule and your
+    # tests are awesome.
+
+    def self.parallelize_me!
+      return unless Minitest.parallel_executor
+      include Minitest::Parallel::Test
+      extend Minitest::Parallel::Test::ClassMethods
+    end
+
+    ##
+    # Returns all instance methods starting with "test_". Based on
+    # #run_order, the methods are either sorted, randomized
+    # (default), or run in parallel.
+
+    def self.runnable_methods
+      methods = methods_matching(/^test_/)
+
+      case self.run_order
+      when :random, :parallel then
+        srand Minitest.seed
+        methods.sort.shuffle
+      when :alpha, :sorted then
+        methods.sort
+      else
+        raise "Unknown_order: %p" % [self.run_order]
+      end
+    end
+
+    ##
+    # Runs a single test with setup/teardown hooks.
+
+    def run
+      time_it do
+        capture_exceptions do
+          SETUP_METHODS.each do |hook|
+            self.send hook
+          end
+
+          self.send self.name
+        end
+
+        TEARDOWN_METHODS.each do |hook|
+          capture_exceptions do
+            self.send hook
+          end
+        end
+      end
+
+      Result.from self # per contract
+    end
+
+    ##
+    # Provides before/after hooks for setup and teardown. These are
+    # meant for library writers, NOT for regular test authors. See
+    # #before_setup for an example.
+
+    module LifecycleHooks
+
+      ##
+      # Runs before every test, before setup. This hook is meant for
+      # libraries to extend minitest. It is not meant to be used by
+      # test developers.
+      #
+      # As a simplistic example:
+      #
+      #   module MyMinitestPlugin
+      #     def before_setup
+      #       super
+      #       # ... stuff to do before setup is run
+      #     end
+      #
+      #     def after_setup
+      #       # ... stuff to do after setup is run
+      #       super
+      #     end
+      #
+      #     def before_teardown
+      #       super
+      #       # ... stuff to do before teardown is run
+      #     end
+      #
+      #     def after_teardown
+      #       # ... stuff to do after teardown is run
+      #       super
+      #     end
+      #   end
+      #
+      #   class Minitest::Test
+      #     include MyMinitestPlugin
+      #   end
+
+      def before_setup; end
+
+      ##
+      # Runs before every test. Use this to set up before each test
+      # run.
+
+      def setup; end
+
+      ##
+      # Runs before every test, after setup. This hook is meant for
+      # libraries to extend minitest. It is not meant to be used by
+      # test developers.
+      #
+      # See #before_setup for an example.
+
+      def after_setup; end
+
+      ##
+      # Runs after every test, before teardown. This hook is meant for
+      # libraries to extend minitest. It is not meant to be used by
+      # test developers.
+      #
+      # See #before_setup for an example.
+
+      def before_teardown; end
+
+      ##
+      # Runs after every test. Use this to clean up after each test
+      # run.
+
+      def teardown; end
+
+      ##
+      # Runs after every test, after teardown. This hook is meant for
+      # libraries to extend minitest. It is not meant to be used by
+      # test developers.
+      #
+      # See #before_setup for an example.
+
+      def after_teardown; end
+    end # LifecycleHooks
+
+    def capture_exceptions # :nodoc:
+      yield
+    rescue *PASSTHROUGH_EXCEPTIONS
+      raise
+    rescue Assertion => e
+      self.failures << e
+    rescue Exception => e
+      self.failures << UnexpectedError.new(sanitize_exception e)
+    end
+
+    def sanitize_exception e # :nodoc:
+      Marshal.dump e
+      e                                         # good: use as-is
+    rescue
+      neuter_exception e
+    end
+
+    def neuter_exception e # :nodoc:
+      bt = e.backtrace
+      msg = e.message.dup
+
+      new_exception e.class, msg, bt            # e.class can be a problem...
+    rescue
+      msg.prepend "Neutered Exception #{e.class}: "
+
+      new_exception RuntimeError, msg, bt, true # but if this raises, we die
+    end
+
+    def new_exception klass, msg, bt, kill = false # :nodoc:
+      ne = klass.new msg
+      ne.set_backtrace bt
+
+      if kill then
+        ne.instance_variables.each do |v|
+          ne.remove_instance_variable v
+        end
+      end
+
+      Marshal.dump ne                           # can raise TypeError
+      ne
+    end
+
+    include LifecycleHooks
+    include Guard
+    extend Guard
+  end # Test
+end

data/lib/minitest/test_task.rb

@@ -0,0 +1,331 @@
+require "shellwords"
+require "rbconfig"
+
+begin
+  require "rake/tasklib"
+rescue LoadError => e
+  warn e.message
+  return
+end
+
+module Minitest # :nodoc:
+
+  ##
+  # Minitest::TestTask is a rake helper that generates several rake
+  # tasks under the main test task's name-space.
+  #
+  #   task <name>      :: the main test task
+  #   task <name>:cmd  :: prints the command to use
+  #   task <name>:deps :: runs each test file by itself to find dependency errors
+  #   task <name>:slow :: runs the tests and reports the slowest 25 tests.
+  #
+  # Examples:
+  #
+  #   Minitest::TestTask.create
+  #
+  # The most basic and default setup.
+  #
+  #   Minitest::TestTask.create :my_tests
+  #
+  # The most basic/default setup, but with a custom name
+  #
+  #   Minitest::TestTask.create :unit do |t|
+  #     t.test_globs = ["test/unit/**/*_test.rb"]
+  #     t.warning = false
+  #   end
+  #
+  # Customize the name and only run unit tests.
+  #
+  # NOTE: To hook this task up to the default, make it a dependency:
+  #
+  #   task default: :unit
+
+  class TestTask < Rake::TaskLib
+    WINDOWS = RbConfig::CONFIG["host_os"] =~ /mswin|mingw/ # :nodoc:
+
+    ##
+    # Create several test-oriented tasks under +name+ (default:
+    # "test"). Takes an optional block to customize variables.
+    # Examples:
+    #
+    #   Minitest::TestTask.create # named "test", all defaults
+    #
+    #   Minitest::TestTask.create do |t|
+    #     t.warning = false # my tests are noisy
+    #     t.framework = %(require_relative "./test/helper.rb")
+    #   end
+
+    def self.create name = :test, &block
+      task = new name
+      task.instance_eval(&block) if block
+      task.process_env
+      task.define
+      task
+    end
+
+    ##
+    # Extra arguments to pass to the tests. Defaults empty but gets
+    # populated by a number of enviroment variables:
+    #
+    # N (-n flag) :: a string or regexp of tests to run.
+    # X (-e flag) :: a string or regexp of tests to exclude.
+    # A (arg)     :: quick way to inject an arbitrary argument (eg A=--help).
+    #
+    # See #process_env
+
+    attr_accessor :extra_args
+
+    ##
+    # The code to load the framework. Defaults to requiring
+    # minitest/autorun.
+    #
+    # If you have a test helper file that requires minitest/autorun
+    # and anything else your project standardizes on, then you'll
+    # probably want to change this to:
+    #
+    #   Minitest::TestTask.create do |t|
+    #     t.framework = %(require_relative "./test/helper.rb")
+    #   end
+    #
+    # or something similar. NOTE: if you do this, then helper must
+    # require "minitest/autorun" at the top to start the tests.
+
+    attr_accessor :framework
+
+    ##
+    # Extra library directories to include. Defaults to %w[lib test
+    # .]. Also uses $MT_LIB_EXTRAS allowing you to dynamically
+    # override/inject directories for custom runs.
+
+    attr_accessor :libs
+
+    ##
+    # The name of the task and base name for the other tasks generated.
+
+    attr_accessor :name
+
+    ##
+    # File globs to find test files. Defaults to something sensible to
+    # find test files under the test directory.
+
+    attr_accessor :test_globs
+
+    ##
+    # Turn on ruby warnings (-w flag). Defaults to true.
+
+    attr_accessor :warning
+
+    ##
+    # Optional: Additional ruby to run before the test framework is loaded.
+    # Example:
+    #
+    #   Minitest::TestTask.create "test:cov" do |t|
+    #     t.test_prelude = %(require "simplecov")
+    #   end
+
+    attr_accessor :test_prelude
+
+    ##
+    # Print out commands as they run. Defaults to Rake's +trace+ (-t
+    # flag) option.
+
+    attr_accessor :verbose
+
+    ##
+    # Use TestTask.create instead.
+
+    def initialize name = :test # :nodoc:
+      self.extra_args   = []
+      self.framework    = %(require "minitest/autorun")
+      self.libs         = %w[lib test .]
+      self.name         = name
+      self.test_globs   = ["test/**/test_*.rb",
+                           "test/**/*_test.rb"]
+      self.test_prelude = nil
+      self.verbose      = Rake.application.options.trace || Rake.verbose == true
+      self.warning      = true
+    end
+
+    ##
+    # Extract variables from the environment and convert them to
+    # command line arguments. See #extra_args.
+    #
+    # Environment Variables:
+    #
+    # MT_LIB_EXTRAS :: Extra libs to dynamically override/inject for custom runs.
+    # N             :: Tests to run (string or /regexp/).
+    # X             :: Tests to exclude (string or /regexp/).
+    # A             :: Any extra arguments. Honors shell quoting.
+    #
+    # Deprecated:
+    #
+    # TESTOPTS      :: For argument passing, use +A+.
+    # N             :: For parallel testing, use +MT_CPU+.
+    # FILTER        :: Same as +TESTOPTS+.
+
+    def process_env
+      warn "TESTOPTS is deprecated in Minitest::TestTask. Use A instead" if
+        ENV["TESTOPTS"]
+      warn "FILTER is deprecated in Minitest::TestTask. Use A instead" if
+        ENV["FILTER"]
+
+      lib_extras = (ENV["MT_LIB_EXTRAS"] || "").split File::PATH_SEPARATOR
+      self.libs[0, 0] = lib_extras
+
+      extra_args << "-i" << ENV["N"]                      if ENV["N"]
+      extra_args << "-i" << ENV["I"]                      if ENV["I"]
+      extra_args << "-x" << ENV["X"]                      if ENV["X"]
+      extra_args << "-x" << ENV["E"]                      if ENV["E"]
+      extra_args.concat Shellwords.split(ENV["TESTOPTS"]) if ENV["TESTOPTS"]
+      extra_args.concat Shellwords.split(ENV["FILTER"])   if ENV["FILTER"]
+      extra_args.concat Shellwords.split(ENV["A"])        if ENV["A"]
+
+      # TODO? RUBY_DEBUG = ENV["RUBY_DEBUG"]
+      # TODO? ENV["RUBY_FLAGS"]
+
+      extra_args.compact!
+    end
+
+    def define # :nodoc:
+      desc "Run the test suite. Use I, X, and A to add flags/args."
+      task name do
+        ruby make_test_cmd, verbose: verbose
+      end
+
+      desc "Run the test suite, filtering for 'FU' in name (focused units?)."
+      task "#{name}:fu" do
+        ruby make_test_cmd(include:"/FU/"), verbose: verbose
+      end
+
+      desc "Print out the test command. Good for profiling and other tools."
+      task "#{name}:cmd" do
+        puts "ruby #{make_test_cmd}"
+      end
+
+      desc "Show which test files fail when run in isolation."
+      task "#{name}:isolated" do
+        tests = Dir[*self.test_globs].uniq
+
+        # 3 seems to be the magic number... (tho not by that much)
+        bad, good, n = {}, [], (ENV.delete("K") || 3).to_i
+        file = ENV.delete "F"
+        times = {}
+
+        tt0 = Time.now
+
+        n.threads_do tests.sort do |path|
+          t0 = Time.now
+          output = `#{Gem.ruby} #{make_test_cmd path:path} 2>&1`
+          t1 = Time.now - t0
+
+          times[path] = t1
+
+          if $?.success?
+            $stderr.print "."
+            good << path
+          else
+            $stderr.print "x"
+            bad[path] = output
+          end
+        end
+
+        puts "done"
+        puts "Ran in %.2f seconds" % [ Time.now - tt0 ]
+
+        if file then
+          require "json"
+          File.open file, "w" do |io|
+            io.puts JSON.pretty_generate times
+          end
+        end
+
+        unless good.empty?
+          puts
+          puts "# Good tests:"
+          puts
+          good.sort.each do |path|
+            puts "%.2fs: %s" % [times[path], path]
+          end
+        end
+
+        unless bad.empty?
+          puts
+          puts "# Bad tests:"
+          puts
+          bad.keys.sort.each do |path|
+            puts "%.2fs: %s" % [times[path], path]
+          end
+          puts
+          puts "# Bad Test Output:"
+          puts
+          bad.sort.each do |path, output|
+            puts
+            puts "# #{path}:"
+            puts output
+          end
+          exit 1
+        end
+      end
+
+      task "#{name}:deps" => "#{name}:isolated" # now just an alias
+
+      desc "Run the test suite and report the slowest 25 tests."
+      task "#{name}:slow" do
+        sh ["rake #{name} A=-v",
+            "egrep '#test_.* s = .'",
+            "sort -n -k2 -t=",
+            "tail -25"].join " | "
+      end
+    end
+
+    ##
+    # Generate the test command-line.
+
+    def make_test_cmd **option
+      globs = option[:path] || test_globs
+
+      tests = []
+      tests.concat Dir[*globs].sort.shuffle # TODO: SEED -> srand first?
+      tests.map! { |f| %(require "#{f}") }
+
+      runner = []
+      runner << test_prelude if test_prelude
+      runner << framework
+      runner.concat tests
+      runner = runner.join "; "
+
+      extra_args << "-i" << option[:include] if option[:include]
+
+      args  = []
+      args << "-I#{libs.join File::PATH_SEPARATOR}" unless libs.empty?
+      args << "-w" if warning
+      args << "-e"
+      args << "'#{runner}'"
+      args << "--"
+      args << extra_args.map(&:shellescape)
+
+      args.join " "
+    end
+  end
+end
+
+class Work < Queue # :nodoc:
+  def initialize jobs # :nodoc:
+    super
+    close
+  end
+end
+
+class Integer # :nodoc:
+  def threads_do jobs # :nodoc:
+    q = Work.new jobs
+
+    Array.new(self) {
+      Thread.new do
+        while job = q.pop # go until quit value
+          yield job
+        end
+      end
+    }.each(&:join)
+  end
+end