minitest-mergify 2026.10.8

data/lib/mergify/minitest/declarations.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Mergify
+  module Minitest
+    # Where a spec test with no body is declared, which Minitest records
+    # nowhere. `it "does a thing"` without a block gets Minitest's own body, a
+    # proc in minitest/spec.rb that skips the test, so the test's method, its
+    # results' location and every name built on them would point into the
+    # Minitest gem, at a path that differs from one machine to the next. This
+    # gives it the same skip, declared at the `it`'s own line instead.
+    #
+    # Prepended to Minitest's spec DSL when the suite requires
+    # `minitest/mergify`, before its tests are defined; a test defined earlier
+    # keeps Minitest's body.
+    module Declarations
+      # The body Minitest gives such a test.
+      BODY = 'proc { skip "(no tests defined)" }'
+
+      def it(*args, &block)
+        body = block || Declarations.body_at(self, caller_locations(1, 1).first)
+        super(*args, &body)
+      end
+
+      # `specify` is an alias of Minitest's `it`, so it goes around this one.
+      def specify(*args, &block)
+        body = block || Declarations.body_at(self, caller_locations(1, 1).first)
+        super(*args, &body)
+      end
+
+      # The body, compiled as if written at `site`: the point is that it
+      # reports the suite's file and line, not this one's.
+      def self.body_at(klass, site)
+        klass.class_eval(BODY, site.path, site.lineno)
+      end
+
+      def self.install
+        ::Minitest::Spec::DSL.prepend(self) unless ::Minitest::Spec::DSL.ancestors.include?(self)
+      end
+    end
+  end
+end

data/lib/mergify/minitest/names.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'mergify/ci/core'
+
+module Mergify
+  module Minitest
+    # The name Mergify knows each test by, with the file and the function its
+    # span reports.
+    #
+    # A class named by a constant cannot share its name with another one, so
+    # its tests are named as Minitest names them, `Class#method`. A class
+    # `describe` creates is named after its text, which two files can repeat,
+    # so its tests are named as rspec-mergify names its examples, by
+    # `CI::Core::TestNames`: `<file> > <describes> > <title>`. The title is
+    # the `it`'s text without the counter Minitest numbers it with, by its
+    # position in its `describe`: adding a test would otherwise rename every
+    # one below it. An `it` written without text is titled by its block's
+    # code. A title its `describe` repeats keeps the counter, so those tests
+    # stay apart.
+    #
+    # Each test also has a former name, the one a JUnit upload gave it:
+    # `Class.method`, as minitest-junit and minitest-reporters write the class
+    # and the method, and `mergify ci junit-process` joins them. Mergify's
+    # lists may still hold a test under it.
+    class Names
+      # `declared_in` is the file the test is declared in when its code is
+      # elsewhere, which leaves its line unknown; nil when they are the same.
+      Named = Struct.new(:name, :former, :function, :file, :declared_in, keyword_init: true)
+
+      # What Minitest puts before an `it`'s text: its position in its
+      # `describe`, on four digits or more.
+      COUNTER = /\Atest_\d{4,}_/
+
+      # The text Minitest gives an `it` written without one.
+      ANONYMOUS = 'anonymous'
+
+      def initialize(runnables, root)
+        @root = root
+        @described = {}
+        runnables.each { |klass| index(klass) if described?(klass) }
+      end
+
+      # The test `method` of the class named `klass`, as a result carries
+      # them, its code in `file`.
+      def of(klass, method, file)
+        @described.fetch([klass, method, File.expand_path(file)]) do
+          Named.new(name: "#{klass}##{method}", former: "#{klass}.#{method}", function: method,
+                    file: CI::Core::TestNames.relative(file, @root))
+        end
+      end
+
+      private
+
+      # A class `describe` created, rather than one a constant names.
+      def described?(klass)
+        klass.respond_to?(:desc) && !klass.desc.nil?
+      end
+
+      def index(klass)
+        chain = describe_chain(klass)
+        titles(klass).each do |method, title|
+          file = klass.instance_method(method).source_location&.first
+          next unless file
+
+          @described[[klass.name, method, File.expand_path(file)]] = described(klass, method, file, chain, title)
+        end
+      end
+
+      def described(klass, method, file, chain, title)
+        declared = declared_file(klass, file)
+        Named.new(name: CI::Core::TestNames.spec_name(declared, chain, title, @root),
+                  former: "#{klass.name}.#{method}", function: title,
+                  file: CI::Core::TestNames.relative(declared, @root),
+                  declared_in: (File.expand_path(declared) unless declared == file))
+      end
+
+      # The file a test of `klass` is declared in, given the one its code is
+      # in: the same, but for a test with no body that a Minitest 5 suite
+      # defined without requiring `minitest/mergify` first, whose code is
+      # Minitest's own (see Declarations). It is then taken from another test
+      # of its `describe`, when one has a body.
+      def declared_file(klass, file)
+        return file unless File.expand_path(file) == minitest_spec
+
+        klass.methods_matching(/\Atest_/)
+             .filter_map { |method| klass.instance_method(method).source_location&.first }
+             .find { |other| File.expand_path(other) != minitest_spec } || file
+      end
+
+      def minitest_spec
+        @minitest_spec ||= File.expand_path(::Minitest::Spec::DSL.instance_method(:let).source_location.first)
+      end
+
+      # Each test method's title, unless another test of the class has the
+      # same one.
+      def titles(klass)
+        titled = klass.methods_matching(/\Atest_/).to_h { |method| [method, title_of(klass, method)] }
+        repeated = titled.values.tally.select { |_, count| count > 1 }.keys
+        titled.to_h { |method, title| [method, repeated.include?(title) ? method : title] }
+      end
+
+      # Its text without the counter, or for an `it` written without one, the
+      # code of its block.
+      def title_of(klass, method)
+        text = method.sub(COUNTER, '')
+        return text unless text == ANONYMOUS
+
+        CI::Core::TestNames.block_text(klass.instance_method(method)) || text
+      end
+
+      # The texts of the `describe`s around the class's tests, outermost
+      # first, each as Minitest joined it into the class's name: a nested
+      # one's is its name without its parent's.
+      def describe_chain(klass)
+        parent = klass.superclass
+        return [*describe_chain(parent), own_text(klass, parent)] if described?(parent)
+        # A `describe` inside a class a constant names is named after it.
+        return [parent.name, own_text(klass, parent)] if klass.name.start_with?("#{parent.name}::")
+
+        [klass.name]
+      end
+
+      def own_text(klass, parent)
+        klass.name.delete_prefix("#{parent.name}::")
+      end
+    end
+  end
+end

data/lib/mergify/minitest/plugin.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'minitest'
+require 'mergify/ci/core'
+require_relative '../minitest'
+require_relative 'test_run'
+require_relative 'names'
+require_relative 'recorder'
+require_relative 'reruns'
+require_relative 'selection'
+
+module Mergify
+  module Minitest
+    # What the plugin does once Minitest has parsed its options, before any
+    # test runs: start the run's session, hand it what the run collected,
+    # and wrap the reporter Minitest reports the run through.
+    module Plugin
+      # The reporters already wrapped: Minitest 5 initializes the plugin twice
+      # when the suite also requires it, and it is set up once.
+      @wrapped = ObjectSpace::WeakMap.new
+
+      # What each class runs, as the run's selection narrows it.
+      module Narrowing
+        def runnable_methods
+          selection = Plugin.selection
+          selection ? selection.narrow(self, super) : super
+        end
+      end
+
+      # The suites Minitest runs, once or in Fail First's two passes: the
+      # loop is `run_all_suites` in Minitest 6, `__run` in Minitest 5.
+      module Passes
+        if ::Minitest.respond_to?(:run_all_suites)
+          def run_all_suites(reporter, options)
+            Plugin.run_suites(reporter) { super }
+          end
+        else
+          def __run(reporter, options)
+            Plugin.run_suites(reporter) { super }
+          end
+        end
+      end
+
+      class << self
+        # The run's selection, once the session applied it; nil before, and
+        # in a run that does not report.
+        attr_reader :selection
+
+        def init(options)
+          reporter = ::Minitest.reporter
+          return if @wrapped.key?(reporter)
+
+          @wrapped[reporter] = true
+          test_run = (Mergify::Minitest.test_run ||= TestRun.new)
+          # Also when the native extension did not load, which nothing can
+          # tell apart from a run outside CI: the report then says why it
+          # reports nothing.
+          return unless test_run.reports? || !Mergify::CI::Core::Native.available?
+
+          start(reporter, test_run, options)
+        end
+
+        # The run's suites, as the selection runs them, then flaky detection's
+        # reruns -- not after a stop Fail First made, whose whole point is to
+        # end the job sooner.
+        def run_suites(reporter, &)
+          return yield unless @selection
+
+          @selection.run(@recorder, &)
+          @reruns.run(reporter, @recorder) unless @recorder.stopping?
+        end
+
+        private
+
+        def start(reporter, test_run, options)
+          names = Names.new(::Minitest::Runnable.runnables, Dir.pwd)
+          # Collected as Minitest's filters leave the tests, before any
+          # selection narrows them.
+          @selection = nil
+          @selection = select(test_run, names, options)
+          @reruns = @selection && Reruns.new(test_run, @selection)
+          @recorder = Recorder.new(test_run, names, options[:io] || $stdout, @selection, @reruns)
+          @recorder.attach(reporter)
+          install
+        end
+
+        # Hand the session what the run collected, and apply what it decided.
+        # This runs on every CI run, opted in or not: a fault of this gem must
+        # cost the run its reduction, never its tests.
+        def select(test_run, names, options)
+          return unless test_run.reports?
+
+          Selection.collect(::Minitest::Runnable.runnables, names, options).tap { |selection| selection.apply(test_run) }
+        rescue StandardError => e
+          warn "Mergify Test Selection failed, so the full suite runs: #{e.class}: #{e.message}"
+          nil
+        end
+
+        def install
+          ::Minitest::Test.singleton_class.prepend(Narrowing) unless ::Minitest::Test.singleton_class < Narrowing
+          ::Minitest.singleton_class.prepend(Passes) unless ::Minitest.singleton_class < Passes
+        end
+      end
+    end
+  end
+end

data/lib/mergify/minitest/recorder.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'mergify/ci/core'
+require_relative 'names'
+require_relative 'results'
+
+module Mergify
+  module Minitest
+    # Hands each finished test to the session, for the run's trace, its
+    # verdict, the quarantine, Fail First and flaky detection, and prints what
+    # the session says once the run is over.
+    #
+    # It wraps the reporter Minitest sends every result through, rather than
+    # joining the reporters inside it: a plugin can replace those, and
+    # minitest-reporters does, dropping any added before it. Results recorded
+    # in another process (Rails' parallel workers) come back to this one.
+    # rubocop:disable-next Metrics/ClassLength
+    class Recorder
+      HEADER = '# Mergify CI:'
+
+      # The ANSI colour of a line the session worded, by its severity; an
+      # `info` one keeps the terminal's.
+      SEVERITY_COLOURS = { 'warning' => 33, 'error' => 31 }.freeze
+
+      # Each test's first attempt, by name: how it ended (`'passed'`,
+      # `'failed'` or `'skipped'`, before the quarantine absorbed a failure)
+      # and how long it took, in milliseconds, for flaky detection.
+      attr_reader :first_attempts
+
+      # `selection` is the run's, when it asked Test Selection; nil when it
+      # does not report. `reruns`, flaky detection's, takes the results of the
+      # tests it reruns.
+      def initialize(test_run, names, io, selection, reruns)
+        @test_run = test_run
+        @names = names
+        @io = io
+        @selection = selection
+        @reruns = reruns
+        @fail_first = selection && test_run.fail_first
+        @first_attempts = {}
+        @lock = Mutex.new
+        @changed = ConditionVariable.new
+        @stopping = false
+      end
+
+      # Wrap `reporter`, the one Minitest reports the run through.
+      def attach(reporter)
+        reporter.singleton_class.prepend(hooks)
+      end
+
+      # Before Minitest's own reporters count the result: a failure the
+      # quarantine absorbs reaches them as a skip, so it fails nothing, and
+      # Mergify still sees it fail.
+      def record(result)
+        return unless @test_run.reports?
+
+        named = named(result)
+        status = Results.status_of(result)
+        absorbed = trace(result, named, status)
+        conclude(named.name, status, absorbed, result.time)
+      end
+
+      # Whether `result` is a rerun's, which flaky detection takes as an
+      # attempt and Minitest's own reporters never see.
+      def rerun_taken?(result)
+        return false unless @reruns&.rerun?(result.klass, result.name)
+
+        @reruns.take(result, named(result).name)
+      end
+
+      # Whether Minitest is about to report a rerun of `method` of `klass` (a
+      # class, or what Rails' workers report its name as).
+      def rerun?(klass, method)
+        @reruns&.rerun?(klass.respond_to?(:name) ? klass.name : klass.to_s, method) || false
+      end
+
+      # Whether flaky detection found a new test flaky, in reruns Minitest's
+      # own results never saw: it fails the run.
+      def failed_by_reruns?
+        @test_run.reports? && @test_run.flaky_detection_fails_the_run?
+      end
+
+      # Wait until every test named `names` was recorded: a pass of Fail
+      # First ran in Minitest's threads or Rails' workers hands its results
+      # back after its suites were handed over.
+      def wait_for(names)
+        @lock.synchronize { @changed.wait(@lock) until names.all? { |name| @first_attempts.key?(name) } }
+      end
+
+      # Whether Fail First said to stop the run, once every test it put first
+      # was recorded.
+      def stopping?
+        @lock.synchronize { @stopping }
+      end
+
+      # Once Minitest has reported the run: the verdict, then the trace, then
+      # the report under its own header, after Minitest's summary. The
+      # verdict first, on purpose: it is what the next merge-queue rerun of
+      # this job is answered from, and it must never wait behind the trace
+      # upload's timeout and retries.
+      def finish(passed:)
+        report_verdict if @selection
+        @test_run.report_trace(failed: !passed)
+        print_report
+      end
+
+      private
+
+      # The test's span, as the quarantine accounts for it, and the failure
+      # it absorbs: whether it did.
+      def trace(result, named, status)
+        recorded = @test_run.record_quarantine([named.name, named.former], status)
+        @test_run.record_case(Results.case_of(result, named, recorded['quarantined']))
+        Results.absorb(result) if recorded['absorbed']
+        recorded['absorbed']
+      end
+
+      def named(result)
+        @names.of(result.klass, result.name, result.source_location.first)
+      end
+
+      # The test's first attempt, as it ended, for flaky detection, and its
+      # final status, for the verdict and Fail First: a failure the quarantine
+      # absorbed is none.
+      def conclude(name, status, absorbed, time)
+        final = absorbed ? 'quarantined_failed' : status
+        @test_run.record_test(name, final, time)
+        stop = @fail_first&.unit_done(name, final == 'failed')
+        @lock.synchronize do
+          @first_attempts[name] ||= [status, time * 1000]
+          @stopping ||= stop
+          @changed.broadcast
+        end
+      end
+
+      # How the run ended: how many of the tests it was to run never ran --
+      # the ones Fail First's stop left out, a run Minitest was interrupted
+      # in -- and whether Fail First stopped it.
+      def report_verdict
+        not_run = [@selection.to_run - @test_run.executed_count, 0].max
+        @test_run.report_verdict(not_run: not_run, told_to_stop: stopping?)
+      end
+
+      # What the wrapped reporter does before its own `record` and after its
+      # own `report`.
+      # rubocop:disable-next Metrics/MethodLength
+      def hooks
+        recorder = self
+        Module.new do
+          define_method(:prerecord) do |klass, method|
+            super(klass, method) unless recorder.rerun?(klass, method)
+          end
+
+          define_method(:record) do |result|
+            next if recorder.rerun_taken?(result)
+
+            recorder.record(result)
+            super(result)
+          end
+
+          define_method(:passed?) do
+            super() && !recorder.failed_by_reruns?
+          end
+
+          define_method(:report) do
+            super()
+            recorder.finish(passed: passed?)
+          end
+        end
+      end
+
+      # What the session says once the run is over, then what only this gem
+      # says, under a header in Minitest's style (`# Running:`); none at all
+      # when neither has anything to say.
+      def print_report
+        lines = report_lines
+        return if lines.empty?
+
+        @io.puts "\n#{HEADER}\n\n"
+        lines.each { |line| @io.puts line }
+      end
+
+      # The session's lines, each as it is in the colour of its severity, then
+      # this gem's own, after a blank line.
+      def report_lines
+        lines = @test_run.summary.map { |severity, text| in_severity_colour(text, severity) }
+        own = Mergify::CI::Core::Native.available? ? [] : [native_warning]
+        lines.any? && own.any? ? [*lines, '', *own] : [*lines, *own]
+      end
+
+      # The extension is what detects CI, so when it did not load there is no
+      # repository name either: say what actually happened instead.
+      def native_warning
+        'WARNING: the Mergify native extension could not be loaded, so this run reports nothing: ' \
+          "#{Mergify::CI::Core::Native.load_error&.message}"
+      end
+
+      # `text` in the colour of `severity` when Minitest writes to a terminal;
+      # as it is otherwise, for an `info` one, and for a blank one.
+      def in_severity_colour(text, severity)
+        colour = SEVERITY_COLOURS[severity]
+        return text unless colour && !text.empty? && @io.respond_to?(:tty?) && @io.tty?
+
+        "\e[#{colour}m#{text}\e[0m"
+      end
+    end
+  end
+end

data/lib/mergify/minitest/reruns.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'minitest'
+require_relative 'results'
+
+module Mergify
+  module Minitest
+    # Flaky detection, once the run's tests are over: the session plans how
+    # many times to rerun the tests it targets, from their first attempts, and
+    # each rerun goes through Minitest's own dispatch, so it runs where the
+    # test ran -- inline, in Minitest's threads, or in Rails' workers -- and
+    # its result comes back to the reporter Minitest records results through.
+    # There, each is an attempt for the session, which Minitest's own
+    # reporters never see.
+    class Reruns
+      def initialize(test_run, selection)
+        @test_run = test_run
+        @selection = selection
+        @pending = Hash.new(0)
+        @lock = Mutex.new
+        @changed = ConditionVariable.new
+      end
+
+      # Rerun what flaky detection targets, once `recorder` recorded every test
+      # the run was to run: a run in Minitest's threads or Rails' workers
+      # hands its results back after its suites were handed over.
+      def run(reporter, recorder)
+        return unless @test_run.flaky_detection_runs?
+
+        recorder.wait_for(@selection.names_to_run)
+        reruns = prepare(recorder.first_attempts)
+        plan = reruns&.shared_repeats
+        rerun(plan, reporter) if plan
+      end
+
+      # Whether Minitest is about to report a rerun of `method` of the class
+      # named `klass`, which the reporter keeps from Minitest's own.
+      def rerun?(klass, method)
+        @lock.synchronize { @pending[[klass, method]].positive? }
+      end
+
+      # The result of a rerun of the test named `name`, as an attempt: whether
+      # it was one.
+      def take(result, name)
+        @lock.synchronize do
+          key = [result.klass, result.name]
+          return false unless @pending[key].positive?
+
+          @test_run.record_attempt(name, Results.status_of(result), result.time * 1000)
+          @pending[key] -= 1
+          @changed.broadcast
+          true
+        end
+      end
+
+      private
+
+      # The session's reruns for every test the run ran, each known by its
+      # former name too, with the first attempt of each test flaky detection
+      # targets, as it passed or failed.
+      def prepare(first_attempts)
+        former_names = @selection.tests.to_h { |test| [test.name, ["#{test.klass.name}.#{test.method_name}"]] }
+        reruns = @test_run.prepare_reruns(first_attempts.keys, former_names)
+        first_attempts.each do |name, (outcome, duration_ms)|
+          next unless reruns&.tracks?(name) && %w[passed failed].include?(outcome)
+
+          @test_run.record_attempt(name, outcome, duration_ms)
+        end
+        reruns
+      end
+
+      # Each test of `plan` again, as many times as it says, round after
+      # round, then wait for every result.
+      def rerun(plan, reporter)
+        tests = @selection.tests.select { |test| plan['tests'].include?(test.name) }
+        expect(tests, plan['repeats'])
+        plan['repeats'].times { tests.each { |test| dispatch(test, reporter) } }
+        @lock.synchronize { @changed.wait(@lock) until @pending.values.all?(&:zero?) }
+      end
+
+      # Each of `tests` is reported `repeats` more times.
+      def expect(tests, repeats)
+        @lock.synchronize { tests.each { |test| @pending[[test.klass.name, test.method_name]] += repeats } }
+      end
+
+      # As Minitest runs a test of a class: inline and reported, or handed to
+      # its parallel executor, which reports it once it ran.
+      def dispatch(test, reporter)
+        if ::Minitest::Runnable.respond_to?(:run_suite)
+          test.klass.run(test.klass, test.method_name, reporter)
+        else
+          test.klass.run_one_method(test.klass, test.method_name, reporter)
+        end
+      end
+    end
+  end
+end

data/lib/mergify/minitest/results.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Mergify
+  module Minitest
+    # What a Minitest result says, as the session takes it.
+    module Results
+      module_function
+
+      # Why a quarantined failure reads as a skip, as Minitest's verbose
+      # output shows it.
+      QUARANTINE_MESSAGE = 'Test is quarantined from Mergify Test Insights'
+
+      # The test, as the session takes it once it finished, before the
+      # quarantine absorbed its failure. A result knows how long the test
+      # took, not when it started: Rails' parallel workers hand it over after
+      # the fact. A test declared away from its code is reported where it is
+      # declared, with no line.
+      # rubocop:disable-next Metrics/MethodLength
+      def case_of(result, named, quarantined)
+        file, line = named.declared_in ? [named.declared_in, nil] : result.source_location
+        ended = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+        {
+          'name' => named.name,
+          'file' => named.file,
+          'function' => named.function,
+          'start_unix_nano' => ended - (result.time * 1_000_000_000).round,
+          'end_unix_nano' => ended,
+          'status' => status_of(result),
+          'exception' => exception_of(result),
+          'quarantined' => quarantined,
+          'namespace' => result.klass,
+          'line' => line&.positive? ? line : nil,
+          'path' => File.expand_path(file)
+        }
+      end
+
+      # The failure the quarantine absorbed, as a skip that keeps where it was
+      # raised.
+      def absorb(result)
+        failure = result.failures.find { |raised| !raised.is_a?(::Minitest::Skip) }
+        skip = ::Minitest::Skip.new(QUARANTINE_MESSAGE)
+        skip.set_backtrace(failure&.backtrace || [])
+        result.failures = [skip]
+      end
+
+      # A skip is a failure Minitest reports apart, so it comes first.
+      def status_of(result)
+        return 'skipped' if result.skipped?
+
+        result.passed? ? 'passed' : 'failed'
+      end
+
+      # What the test raised: the first of its failures, the error behind an
+      # unexpected one rather than Minitest's wrapper.
+      def exception_of(result)
+        return if result.passed? || result.skipped?
+
+        failure = result.failures.find { |raised| !raised.is_a?(::Minitest::Skip) }
+        error = failure.respond_to?(:error) ? failure.error : failure
+        { 'type' => error.class.name, 'message' => error.message,
+          'stacktrace' => (error.backtrace || []).join("\n") }
+      end
+    end
+  end
+end