mutineer-mongoid 2.0.0

data/lib/mutineer/kill_matrix.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Mutineer
+  # Which tests kill which mutants, read from the {Kills} rows of a `--matrix`
+  # run. Pure: it reads results and runs nothing, and it never touches the score.
+  #
+  # A test is a `[file, name, id]` triple (see {Kills}); file and id identify it,
+  # and every row names a test the same way (see {Runner.share_tests}). The tests it knows are
+  # the ones that ran against at least one mutant of this run, so every answer
+  # is relative to the run's mutants: a test of code outside the run's sources
+  # kills nothing here.
+  #
+  # - A blind test ran in at least one complete row and killed no mutant. A
+  #   test seen only in incomplete rows is never called blind.
+  # - A redundant test killed at least one mutant, and each mutant it killed has
+  #   another killer. Each test is judged alone: two redundant tests can be the
+  #   only killers of one mutant, so delete them one at a time. Finding the
+  #   smallest set of tests that keeps every kill is a set-cover problem, out of
+  #   scope here.
+  #
+  # Kills in incomplete rows count, since they did happen. An incomplete row can
+  # miss kills, so when {#complete?} is false a blind test may have killed one
+  # of those mutants.
+  class KillMatrix
+    # The results that carry a {Kills} row, in run order.
+    #
+    # @return [Array<Mutineer::Result>]
+    attr_reader :rows
+
+    # @param results [Array<Mutineer::Result>] every result of the run.
+    def initialize(results)
+      @rows = results.select(&:kills)
+      @kill_counts = Hash.new(0)
+      @rows.each { |r| r.kills.killed_by.each { |test| @kill_counts[test] += 1 } }
+    end
+
+    # Every test that ran against at least one mutant, sorted by file, name and id.
+    #
+    # @return [Array<Array(String, String, String)>]
+    def tests
+      @tests ||= @rows.flat_map { |r| r.kills.ran + r.kills.killed_by }.uniq.sort
+    end
+
+    # True when every row is complete.
+    #
+    # @return [Boolean]
+    def complete?
+      @rows.all? { |r| r.kills.complete }
+    end
+
+    # The rows that are not complete.
+    #
+    # @return [Array<Mutineer::Result>]
+    def incomplete_rows
+      @rows.reject { |r| r.kills.complete }
+    end
+
+    # How many mutants `test` killed.
+    #
+    # @param test [Array(String, String, String)] a `[file, name, id]` test.
+    # @return [Integer]
+    def kill_count(test)
+      @kill_counts[test]
+    end
+
+    # Tests that ran in a complete row and killed no mutant.
+    #
+    # @return [Array<Array(String, String, String)>] sorted.
+    def blind
+      @blind ||= begin
+        seen = @rows.select { |r| r.kills.complete }.flat_map { |r| r.kills.ran }.to_set
+        tests.select { |test| kill_count(test).zero? && seen.include?(test) }
+      end
+    end
+
+    # Tests that killed a mutant, where every mutant they killed has another killer.
+    #
+    # @return [Array<Array(String, String, String)>] sorted.
+    def redundant
+      @redundant ||= begin
+        sole = @rows.filter_map { |r| r.kills.killed_by.first if r.kills.killed_by.size == 1 }.to_set
+        tests.select { |test| kill_count(test).positive? && !sole.include?(test) }
+      end
+    end
+  end
+end

data/lib/mutineer/minitest_integration/kill_recorder.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require_relative "outer_reporter"
+require_relative "../kill_channel"
+
+module Mutineer
+  class MinitestIntegration
+    # Sends the outcome of each test to the parent of a `--matrix` mutant run,
+    # through {KillChannel}. It never stops the run: every covering test runs,
+    # so the parent learns exactly which tests kill the mutant. Child-process
+    # only, like MinitestIntegration.
+    #
+    # Only the outer reporter counts (see {OuterReporter}): a test can build and
+    # record on its own reporter, and those results are not the run's.
+    module KillRecorder
+      extend OuterReporter::Client
+
+      # Serializes the counting and the writing of results, which Minitest
+      # records from several threads in a parallel class.
+      LOCK = Mutex.new
+
+      # Prepended on each loaded test class: one test's run. Serial and parallel
+      # runs both call it, in Minitest 5 and 6.
+      module MarkSkippedTest
+        # Runs the test inside a `skip` region once a serial test has killed.
+        #
+        # @return [Minitest::Result]
+        def run
+          KillRecorder.skipping { super }
+        end
+      end
+
+      # Prepended on each loaded test class's singleton under Minitest 6: one
+      # class's run and each test's class-level run, user wrappers included.
+      # A run without `--matrix` skips both after a stop (see
+      # StopAtFirstFailure::SkipAfterStop6).
+      module MarkSkippedClass6
+        # Runs the class inside a `skip` region once a serial test has killed.
+        #
+        # @param reporter [Minitest::CompositeReporter]
+        # @param options [Hash]
+        # @return [Object]
+        def run_suite(reporter, options = {})
+          KillRecorder.class_starting(self, reporter)
+          KillRecorder.skipping { super }
+        end
+
+        # Runs one test's class-level step inside a `skip` region once a
+        # serial test has killed.
+        #
+        # @param klass [Class]
+        # @param method_name [String]
+        # @param reporter [Minitest::CompositeReporter]
+        # @return [Object]
+        def run(klass, method_name, reporter)
+          KillRecorder.skipping { super }
+        end
+      end
+
+      # The Minitest 5 form of {MarkSkippedClass6}.
+      module MarkSkippedClass5
+        # Runs the class inside a `skip` region once a serial test has killed.
+        #
+        # @param reporter [Minitest::CompositeReporter]
+        # @param options [Hash]
+        # @return [Object]
+        def run(reporter, options = {})
+          KillRecorder.class_starting(self, reporter)
+          KillRecorder.skipping { super }
+        end
+
+        # Runs one test's class-level step inside a `skip` region once a
+        # serial test has killed.
+        #
+        # @param klass [Class]
+        # @param method_name [String]
+        # @param reporter [Minitest::CompositeReporter]
+        # @return [Object]
+        def run_one_method(klass, method_name, reporter)
+          KillRecorder.skipping { super }
+        end
+      end
+
+      # Prepended on `Minitest::CompositeReporter`.
+      module Record
+        # Records the result, then sends it to the channel.
+        #
+        # @param result [Minitest::Result] the result of one test.
+        # @return [void]
+        def record(result)
+          super
+          KillRecorder.record(self, result)
+        end
+      end
+
+      class << self
+        # The write end of the channel of the armed run.
+        #
+        # @return [IO, nil]
+        attr_accessor :channel
+
+        # True once the `parallel` line has gone out.
+        #
+        # @return [Boolean, nil]
+        attr_accessor :parallel_marked
+
+        # The loaded test classes of the armed run.
+        #
+        # @return [Array<Class>, nil]
+        attr_accessor :runnables
+
+        # How many results the outer reporter has recorded, skips included.
+        #
+        # @return [Integer, nil]
+        attr_accessor :seen
+
+        # True once a serial test killed: from then on, a run without `--matrix`
+        # skips each later test and class.
+        #
+        # @return [Boolean, nil]
+        attr_accessor :serial_killed
+
+        # Installs the hooks, arms the recorder for this process, and writes the
+        # channel's `start` line. Call it after the test files load, so the
+        # recorder knows the test classes. An unknown Minitest shape arms
+        # nothing and writes nothing, so the parent sees no `start` and keeps
+        # the row incomplete.
+        #
+        # @param channel [IO] the write end of the channel.
+        # @param runnables [Array<Class>] the loaded test classes.
+        # @return [Boolean] false when the Minitest shape is unknown.
+        def arm!(channel, runnables)
+          outer = OuterReporter.hook_for_loaded_minitest
+          return false unless outer
+
+          OuterReporter.prepend_once(::Minitest::CompositeReporter, Record)
+          OuterReporter.prepend_once(::Minitest.singleton_class, outer)
+          class_hook = outer.equal?(OuterReporter::Hook6) ? MarkSkippedClass6 : MarkSkippedClass5
+          runnables.each do |klass|
+            OuterReporter.prepend_once(klass, MarkSkippedTest)
+            OuterReporter.prepend_once(klass.singleton_class, class_hook)
+          end
+          OuterReporter.register(self)
+          self.armed_pid = Process.pid
+          self.armed_reporter = nil
+          self.channel = channel
+          self.parallel_marked = false
+          # A copy: Minitest's list is live, and a class a test defines during
+          # the run joins it without running, which would break the count.
+          self.runnables = runnables.dup
+          self.seen = 0
+          self.serial_killed = false
+          KillChannel.write_start(channel)
+          true
+        end
+
+        # Writes the channel's `end` line once the suite has returned and the
+        # outer reporter has seen every test the loaded classes run. A return
+        # alone proves nothing: Minitest catches an Interrupt in a test and
+        # returns after the tests so far. Does nothing unless the recorder is
+        # armed in this process.
+        #
+        # @return [void]
+        def finish!
+          return unless channel && armed_here?
+
+          KillChannel.write_end(channel) if seen == planned_tests
+        end
+
+        # True when the test class runs its tests in parallel threads
+        # (`parallelize_me!`). Minitest runs these after every serial class, and
+        # the stop at the first failure cannot skip the tests it already queued.
+        # Minitest 6 names the order `run_order`; Minitest 5 names it `test_order`.
+        #
+        # @param klass [Class] a loaded test class.
+        # @return [Boolean]
+        def parallel?(klass)
+          %i[run_order test_order].any? { |order| klass.respond_to?(order) && klass.public_send(order) == :parallel }
+        end
+
+        # Clears the armed state.
+        #
+        # @return [void]
+        def disarm!
+          self.armed_pid = nil
+          self.armed_reporter = nil
+          self.channel = nil
+          self.runnables = nil
+          self.serial_killed = false
+        end
+
+        # Writes the `parallel` line when the first parallel class starts on the
+        # outer reporter. The class object is known here, so an anonymous class
+        # (which Minitest records with no name) counts too. Minitest runs every
+        # serial class first, so a kill before this line came from a serial
+        # test. A test that runs a class on its own reporter is not the run's
+        # parallel phase, so it marks nothing.
+        #
+        # @param klass [Class] the test class starting its run.
+        # @param reporter [Minitest::CompositeReporter] the reporter it runs on.
+        # @return [void]
+        def class_starting(klass, reporter)
+          return unless channel && outer_reporter?(reporter) && parallel?(klass)
+
+          LOCK.synchronize { mark_parallel }
+        end
+
+        # Runs the block between `skip` and `unskip` when a serial test has
+        # killed in this armed process, else just runs it. No `ensure`: a block
+        # that never returns (an exit, a crash) must leave its region open, so
+        # the parent knows the child ended where a run without `--matrix`
+        # would not have been.
+        #
+        # @yieldreturn [Object]
+        # @return [Object] the block's value.
+        def skipping
+          open = channel && serial_killed && armed_here?
+          KillChannel.write_skip(channel) if open
+          value = yield
+          KillChannel.write_unskip(channel) if open
+          value
+        end
+
+        # Sends one result recorded on `reporter`: a pass, or a kill for a
+        # failure or an error. Skips send no test line, though they count as
+        # seen, and results on other reporters count for nothing. The
+        # `parallel` line goes out when the first parallel class starts (see
+        # {.class_starting}), so a kill that precedes it came from a serial test.
+        #
+        # @param reporter [Minitest::CompositeReporter] the recording reporter.
+        # @param result [Minitest::Result] the result of one test.
+        # @return [void]
+        def record(reporter, result)
+          return unless channel && outer_reporter?(reporter)
+
+          LOCK.synchronize do
+            self.seen += 1
+            send_result(result)
+          end
+        end
+
+        private
+
+        # Writes one result's line. A recorder that raised would change the
+        # verdict, so a result it cannot describe (a Minitest without
+        # `source_location` or `klass` on its results) is a `lost` line, which
+        # keeps the row incomplete, as on the RSpec side.
+        #
+        # @param result [Minitest::Result] the result of one test.
+        # @return [void]
+        def send_result(result)
+          return if result.skipped?
+
+          event = result.passed? ? KillChannel::PASS : KillChannel::KILL
+          self.serial_killed = true if event == KillChannel::KILL && !parallel_marked
+          file, line = Array(result.source_location)
+          KillChannel.write(channel, event, file, *name_and_id(result, line))
+        rescue StandardError
+          KillChannel.write_lost(channel)
+        end
+
+        # The test's name and id. `Class#method` is unique within a run, so the
+        # name is also the id. An anonymous class has no name (Minitest records
+        # nil), so its tests would all merge into `#method`; their id adds the
+        # line that defines the method, which no mutant changes. The test's file
+        # is already part of its identity, so the id holds no path.
+        #
+        # @param result [Minitest::Result] the result of one test.
+        # @param line [Integer, nil] the line that defines the test method.
+        # @return [Array(String, String)] name and id.
+        def name_and_id(result, line)
+          return ["#{result.klass}##{result.name}"] * 2 unless result.klass.to_s.empty?
+
+          name = "(anonymous)##{result.name}"
+          [name, "#{name}@#{line}"]
+        end
+
+        # Writes the `parallel` line, once.
+        #
+        # @return [void]
+        def mark_parallel
+          return if parallel_marked
+
+          self.parallel_marked = true
+          KillChannel.write_parallel(channel)
+        end
+
+        # How many tests the loaded classes ran, or nil when it cannot be told.
+        # Asked after the run, because `runnable_methods` shuffles with the
+        # seed that `Minitest.run` sets.
+        #
+        # @return [Integer, nil]
+        def planned_tests
+          runnables.sum { |klass| klass.runnable_methods.size }
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/mutineer/minitest_integration/outer_reporter.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Mutineer
+  class MinitestIntegration
+    # Finds the outer reporter of a Minitest run, for the hooks that act only on
+    # the run's own results. A test can build a reporter of its own and record
+    # on it, or start a nested run, so the first reporter the run hands to its
+    # suites is the one that counts. Child-process only, like
+    # MinitestIntegration.
+    #
+    # A client module extends {Client}, registers here, and sets its armed pid.
+    # The hook then gives the outer reporter to each client armed in this
+    # process. Minitest 5 and 6 need different hook points; an unknown shape
+    # gets no hook.
+    module OuterReporter
+      # Prepended on the `Minitest` singleton class for Minitest 6.
+      module Hook6
+        # Hands the outer reporter to the armed clients. Only the first call
+        # counts, because a test can call this method with its own reporter.
+        #
+        # @param reporter [Minitest::CompositeReporter] the outer reporter.
+        # @param options [Hash] the Minitest options.
+        # @return [Object] whatever Minitest returns.
+        def run_all_suites(reporter, options)
+          OuterReporter.seen(reporter)
+          super
+        end
+      end
+
+      # Prepended on the `Minitest` singleton class for Minitest 5.
+      module Hook5
+        # The Minitest 5 form of Hook6#run_all_suites.
+        #
+        # @param reporter [Minitest::CompositeReporter] the outer reporter.
+        # @param options [Hash] the Minitest options.
+        # @return [Object] whatever Minitest returns.
+        def __run(reporter, options)
+          OuterReporter.seen(reporter)
+          super
+        end
+      end
+
+      # The per-process state a client keeps. Forked workers inherit it, and
+      # the pid keeps them from acting on it.
+      module Client
+        # The pid of the armed process.
+        #
+        # @return [Integer, nil]
+        attr_accessor :armed_pid
+
+        # The outer reporter of the armed run.
+        #
+        # @return [Minitest::CompositeReporter, nil]
+        attr_accessor :armed_reporter
+
+        # True when the client is armed in this process.
+        #
+        # @return [Boolean]
+        def armed_here?
+          armed_pid == Process.pid
+        end
+
+        # True when `reporter` is the outer reporter of the run armed in this
+        # process.
+        #
+        # @param reporter [Minitest::CompositeReporter] the recording reporter.
+        # @return [Boolean]
+        def outer_reporter?(reporter)
+          armed_here? && reporter.equal?(armed_reporter)
+        end
+      end
+
+      class << self
+        # The registered clients, in registration order.
+        #
+        # @return [Array<Module>]
+        def clients
+          @clients ||= []
+        end
+
+        # Registers a client once.
+        #
+        # @param client [Module] a module that extends {Client}.
+        # @return [void]
+        def register(client)
+          clients << client unless clients.include?(client)
+        end
+
+        # Gives `reporter` to every client armed in this process that has no
+        # outer reporter yet.
+        #
+        # @param reporter [Minitest::CompositeReporter] a reporter a run uses.
+        # @return [void]
+        def seen(reporter)
+          clients.each do |client|
+            client.armed_reporter ||= reporter if client.armed_here?
+          end
+        end
+
+        # The outer-reporter hook for the loaded Minitest.
+        #
+        # @return [Module, nil] {Hook6}, {Hook5}, or nil for an unknown shape.
+        def hook_for_loaded_minitest
+          runnable = ::Minitest::Runnable
+          if ::Minitest.respond_to?(:run_all_suites) && runnable.respond_to?(:run_suite)
+            Hook6
+          elsif ::Minitest.respond_to?(:__run) && runnable.respond_to?(:run_one_method)
+            Hook5
+          end
+        end
+
+        # Prepends `mod` on `target` once. A copy on a superclass does not
+        # count, because it comes after the own methods of `target`.
+        #
+        # @param target [Module] the class or singleton class.
+        # @param mod [Module] the module to prepend.
+        # @return [void]
+        def prepend_once(target, mod)
+          return if target.ancestors.take_while { |a| !a.equal?(target) }.include?(mod)
+
+          target.prepend(mod)
+        end
+      end
+    end
+  end
+end

data/lib/mutineer/minitest_integration/stop_at_first_failure.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "outer_reporter"
+
+module Mutineer
+  class MinitestIntegration
+    # Stops a Minitest run at the first failing test: one failure already
+    # kills the mutant. Child-process only, like MinitestIntegration.
+    #
+    # It sets a flag instead of unwinding the stack, so that class-level
+    # wrappers (`after_all`, a block-form transaction) still finish. The
+    # remaining tests and classes then return before they start.
+    #
+    # Minitest 5 and 6 need different hook points. An unknown shape installs
+    # no hook, and the run is a full run. The outer reporter comes from
+    # {OuterReporter}, shared with {KillRecorder}.
+    module StopAtFirstFailure
+      extend OuterReporter::Client
+
+      # Prepended on `Minitest::CompositeReporter`.
+      module RecordFailure
+        # Records the result, then sets the stop flag on a failure or an
+        # error. Only the outer reporter counts: a test can build and record
+        # on its own reporter.
+        #
+        # @param result [Minitest::Result] the result of one test.
+        # @return [void]
+        def record(result)
+          super
+          return if result.passed? || result.skipped?
+          return unless StopAtFirstFailure.outer_reporter?(self)
+
+          StopAtFirstFailure.stopped = true
+        end
+      end
+
+      # Prepended on the singleton class of each test class for Minitest 6.
+      module SkipAfterStop6
+        # Skips the test class after a stop.
+        #
+        # @param reporter [Minitest::CompositeReporter] the reporter.
+        # @param options [Hash] the Minitest options.
+        # @return [Object, nil] whatever Minitest returns, or nil when skipped.
+        def run_suite(reporter, options = {})
+          return if StopAtFirstFailure.stopped_here?
+
+          super
+        end
+
+        # Skips one test after a stop, without a record.
+        #
+        # @param klass [Class] the test class.
+        # @param method_name [String] the test method.
+        # @param reporter [Minitest::CompositeReporter] the reporter.
+        # @return [Object, nil] whatever Minitest returns, or nil when skipped.
+        def run(klass, method_name, reporter)
+          return if StopAtFirstFailure.stopped_here?
+
+          super
+        end
+      end
+
+      # Prepended on the singleton class of each test class for Minitest 5.
+      module SkipAfterStop5
+        # Skips the test class after a stop.
+        #
+        # @param reporter [Minitest::CompositeReporter] the reporter.
+        # @param options [Hash] the Minitest options.
+        # @return [Object, nil] whatever Minitest returns, or nil when skipped.
+        def run(reporter, options = {})
+          return if StopAtFirstFailure.stopped_here?
+
+          super
+        end
+
+        # Skips one test after a stop, without a record.
+        #
+        # @param klass [Class] the test class.
+        # @param method_name [String] the test method.
+        # @param reporter [Minitest::CompositeReporter] the reporter.
+        # @return [Object, nil] whatever Minitest returns, or nil when skipped.
+        def run_one_method(klass, method_name, reporter)
+          return if StopAtFirstFailure.stopped_here?
+
+          super
+        end
+      end
+
+      class << self
+        # True after the outer reporter records a failure or an error.
+        #
+        # @return [Boolean, nil]
+        attr_accessor :stopped
+
+        # Installs the hooks and arms the stop for this process. Call it after
+        # the test files load, so that every test class gets its prepend.
+        #
+        # @param runnables [Array<Class>] the loaded test classes.
+        # @return [Boolean] false when the Minitest shape is unknown.
+        def arm!(runnables)
+          outer, skip = hooks_for_loaded_minitest
+          return false unless outer
+
+          OuterReporter.prepend_once(::Minitest::CompositeReporter, RecordFailure)
+          OuterReporter.prepend_once(::Minitest.singleton_class, outer)
+          runnables.each { |klass| OuterReporter.prepend_once(klass.singleton_class, skip) }
+          OuterReporter.register(self)
+          self.armed_pid = Process.pid
+          self.armed_reporter = nil
+          self.stopped = false
+          true
+        end
+
+        # Clears the armed state.
+        #
+        # @return [void]
+        def disarm!
+          self.armed_pid = nil
+          self.armed_reporter = nil
+          self.stopped = false
+        end
+
+        # True when the armed run in this process has stopped.
+        #
+        # @return [Boolean]
+        def stopped_here?
+          stopped == true && armed_here?
+        end
+
+        private
+
+        # Picks the hook modules for the loaded Minitest.
+        #
+        # @return [Array(Module, Module), nil] the outer reporter hook and the
+        #   skip hook, or nil for an unknown shape.
+        def hooks_for_loaded_minitest
+          outer = OuterReporter.hook_for_loaded_minitest
+          if outer.equal?(OuterReporter::Hook6) then [outer, SkipAfterStop6]
+          elsif outer.equal?(OuterReporter::Hook5) then [outer, SkipAfterStop5]
+          end
+        end
+      end
+    end
+  end
+end