minitest-mergify 2026.10.8

data/lib/mergify/minitest/selection.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Mergify
+  module Minitest
+    # The run's tests, as the session asks Test Selection about them, and the
+    # order they run in: on a merge-queue bisection step, Fail First puts
+    # first the tests that failed in the step above.
+    #
+    # Minitest has no collection of its own: every test file is loaded before
+    # it runs, so the run's tests are each class's test methods, once
+    # Minitest's filters (`-n`, `-e`, Rails' `file:line`) left them, which is
+    # what Minitest itself runs. Each class then runs what is narrowed here.
+    class Selection
+      # A test the run collected: its class, its method, and the name Mergify
+      # knows it by.
+      Test = Struct.new(:klass, :method_name, :name)
+
+      # Every test the run collected, as Minitest's filters left them.
+      attr_reader :tests
+
+      def initialize(tests)
+        @tests = tests
+        @first = Set.new
+      end
+
+      # How many tests the run is to run: every one it collected.
+      def to_run
+        @tests.size
+      end
+
+      # The tests `runnables` hold once Minitest's filters, in `options`, left
+      # them, each named by `names`.
+      def self.collect(runnables, names, options)
+        tests = runnables.flat_map do |klass|
+          filtered(klass, options).filter_map do |method|
+            file = klass.instance_method(method).source_location&.first
+            Test.new(klass, method, names.of(klass.name, method, file).name) if file
+          end
+        end
+        new(tests)
+      end
+
+      # Minitest 6 names its filters `include` and `exclude`, and filters a
+      # class's tests in `filter_runnable_methods`; Minitest 5 does the same
+      # inline, `include` under the name `filter`.
+      def self.filtered(klass, options)
+        return klass.filter_runnable_methods(options) if klass.respond_to?(:filter_runnable_methods)
+
+        include = pattern(options[:filter])
+        exclude = pattern(options[:exclude])
+        klass.runnable_methods
+             .select { |method| !include || matches?(include, klass, method) }
+             .reject { |method| exclude && matches?(exclude, klass, method) }
+      end
+
+      # Whether `filter` takes the test, as Minitest asks it: by its method,
+      # or by `Class#method`. With `===`, which a Regexp, a String and Rails'
+      # `file:line` filter each answer their own way.
+      def self.matches?(filter, klass, method)
+        filter === method || filter === "#{klass}##{method}" # rubocop:disable Style/CaseEquality
+      end
+
+      # A filter given as `/.../` is a regular expression, as Minitest reads it.
+      def self.pattern(filter)
+        filter.is_a?(String) && filter =~ %r{/(.*)/} ? Regexp.new(Regexp.last_match(1)) : filter
+      end
+
+      # Hand the session what the run collected, and put first what Fail
+      # First puts first, when Mergify answered the run is a bisection step.
+      def apply(test_run)
+        test_run.select(@tests.map(&:name))
+        fail_first = test_run.fail_first
+        put_first(fail_first) if fail_first
+      end
+
+      # The names of the tests the run is to run: every one it collected.
+      def names_to_run
+        @tests.to_set(&:name)
+      end
+
+      # The tests of `klass`, of `methods`, that run now.
+      def narrow(klass, methods)
+        case @pass
+        when :first then methods.select { |method| @first.include?([klass, method]) }
+        when :rest then methods.reject { |method| @first.include?([klass, method]) }
+        else methods
+        end
+      end
+
+      # Run the suites Minitest runs in `run_suites`: the tests put first,
+      # then, unless the recorder says to stop once all of them recorded, the
+      # rest.
+      def run(recorder, &run_suites)
+        return run_suites.call if @first.empty?
+
+        @pass = :first
+        run_suites.call
+        # They may run in Minitest's threads or Rails' workers: their results
+        # come back after the suites were handed over.
+        recorder.wait_for(@first_names)
+        return if recorder.stopping?
+
+        @pass = :rest
+        run_suites.call
+      ensure
+        @pass = nil
+      end
+
+      private
+
+      def put_first(fail_first)
+        names = fail_first.put_first(@tests.map { |test| [test.name, test.name] }).to_set
+        first = @tests.select { |test| names.include?(test.name) }
+        @first = first.to_set { |test| [test.klass, test.method_name] }
+        @first_names = names
+      end
+    end
+  end
+end

data/lib/mergify/minitest/test_run.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'minitest'
+require 'mergify/ci/core'
+require_relative 'version'
+
+module Mergify
+  module Minitest
+    # The run's session: what this process reads once (the CI context, the
+    # trace a caller handed down, the run's id), and what the run reports.
+    class TestRun
+      # What Minitest is, as the session takes it: what it calls a test; what
+      # it can do about Fail First; and Minitest itself, which the trace
+      # names.
+      FRAMEWORK = {
+        test_noun: 'test',
+        # Minitest runs tests, the ones put first in a pass of their own that
+        # the main process waits for, wherever its workers run them: it sees
+        # every result and stops the run.
+        fail_first: { unit: 'test', waits_for_all: true, workers_stop_the_run: false },
+        # Flaky detection reruns a test after the suite, as many times as
+        # every other one it reruns, and nothing retries a failure.
+        reruns: { plans_repeats: true, retries_failures: false },
+        framework: { name: 'minitest', version: ::Minitest::VERSION, language: 'ruby' }
+      }.freeze
+
+      CI_ENABLE_ENV = 'MERGIFY_CI_ENABLE'
+      CI_DEBUG_ENV = 'MERGIFY_CI_DEBUG'
+
+      attr_reader :session
+
+      # `doubles` has the session play Mergify in memory, answering and
+      # keeping what it would send (the session's test doubles, by port, as a
+      # Hash: `trace`, `record`). It is for the gem's own specs, which install
+      # their TestRun before the run starts. The one the plugin builds takes
+      # none, and the gem reads no switch for them.
+      def initialize(doubles: nil)
+        @session = Mergify::CI::Core::Native::Session.start(
+          VERSION, output, doubles, enabled?, client: 'minitest-mergify', **FRAMEWORK
+        )
+        # What a run that reports loads before its tests: the quarantine list
+        # for the branch they target. Without one (no branch, a failed fetch,
+        # no token) nothing is quarantined, and its block says why.
+        @quarantine = @session.load_before_tests if reports?
+      end
+
+      # Whether the run reports to Mergify at all: in CI, or turned on with
+      # MERGIFY_CI_ENABLE. The session decides.
+      def reports?
+        @session.reports?
+      end
+
+      # Hand the session what this run is about to execute, by name, once
+      # Minitest applied its filters: in a job that opted in, it asks Mergify
+      # whether the run is a merge-queue bisection step, and the collection's
+      # fingerprint travels on the verdict and the trace.
+      def select(names)
+        @session.select(names)
+        nil
+      end
+
+      # The run's Fail First, which the session hands out when Mergify
+      # answered `failure_first` and the run runs it; nil otherwise.
+      def fail_first
+        @session.fail_first
+      end
+
+      # Record a test's final status (`passed`, `failed`, `skipped` or
+      # `quarantined_failed`) and how long it took, for the session's verdict.
+      def record_test(name, status, run_time)
+        @session.record_test(name, status, run_time.to_f)
+      end
+
+      # How many distinct tests reached a final status.
+      def executed_count
+        @session.executed_count
+      end
+
+      # Write what this session concluded to Mergify, before the trace goes:
+      # the session decides whether there is a verdict to send -- only a run
+      # that asked for a selection has one -- builds it from what it recorded
+      # and from how the run ended (`not_run` tests it was to run never ran;
+      # `told_to_stop`, Fail First stopped it), and sends it. A verdict that
+      # did not land is a line of the summary.
+      def report_verdict(not_run:, told_to_stop:)
+        @session.end_run(not_run, told_to_stop)
+        @session.report_verdict(false)
+      end
+
+      # Whether flaky detection runs in this run: Mergify answered, and the
+      # repository opted in.
+      def flaky_detection_runs?
+        @session.flaky_detection_runs?
+      end
+
+      # Whether flaky detection found a new test flaky, which fails the run.
+      def flaky_detection_fails_the_run?
+        @session.flaky_detection_fails_the_run?
+      end
+
+      # Prepare flaky detection for the tests the run ran, by name, each also
+      # known by its former names (`former_names`, a list by name), which
+      # Mergify's lists may still hold it under: the run's reruns, or nil
+      # when nothing is to rerun. Which tests it reruns, and how many times, are the
+      # session's.
+      def prepare_reruns(names, former_names)
+        @session.state_former_names(former_names)
+        @session.prepare_reruns(names)
+      end
+
+      # An attempt at a test, ended with `outcome` (`'passed'` or `'failed'`)
+      # after `duration_ms`: its first one, then each rerun.
+      def record_attempt(name, outcome, duration_ms)
+        @session.record_attempt(name, outcome, duration_ms)
+      end
+
+      # Account for a test that ended with `outcome` (`'passed'`, `'failed'`
+      # or `'skipped'`), under each of its `names`, as `{ 'quarantined' =>
+      # bool, 'absorbed' => bool }`: an absorbed failure fails nothing.
+      def record_quarantine(names, outcome)
+        return { 'quarantined' => false, 'absorbed' => false } unless @quarantine
+
+        @quarantine.record(names, outcome)
+      end
+
+      # Hand the session a test once it finished (see
+      # `Mergify::CI::Core::Native::Session#record_case`): its span joins the
+      # run's trace.
+      def record_case(test_case)
+        @session.record_case(test_case)
+      end
+
+      # Have the session send the run's trace, once, at the end, under a
+      # session span that fails with the run. An upload that did not land is
+      # a line of the summary, never a failure of the suite.
+      def report_trace(failed:)
+        @session.report_trace(failed) if reports?
+      end
+
+      # What the session says once the run is over, each line a `[severity,
+      # text]` pair. A process parallel_tests started ran a share of the
+      # suite only: it sets TEST_ENV_NUMBER, to an empty string for its first.
+      def summary
+        @session.summary(ENV.key?('TEST_ENV_NUMBER'))
+      end
+
+      private
+
+      # Where the session sends the trace: shown in debug mode, sent
+      # otherwise -- to Mergify, or to the test doubles a spec handed over.
+      def output
+        Mergify::CI::Core::Utils.env_truthy?(CI_DEBUG_ENV) ? 'debug' : 'send'
+      end
+
+      # The gem's enable switch: the run then reports outside CI too.
+      def enabled?
+        Mergify::CI::Core::Utils.env_truthy?(CI_ENABLE_ENV)
+      end
+    end
+  end
+end

data/lib/mergify/minitest/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Mergify
+  module Minitest
+    # Placeholder: the release workflow stamps the real version from the git
+    # tag at build time, as it does for every client in this repository.
+    VERSION = '2026.10.8'
+  end
+end

data/lib/mergify/minitest.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'minitest/version'
+
+module Mergify
+  module Minitest
+    class << self
+      # The run's TestRun: the plugin builds it, unless one is installed
+      # before the run starts, as the gem's own specs install theirs, with
+      # the session's test doubles.
+      attr_accessor :test_run
+    end
+  end
+end

data/lib/minitest/mergify.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'minitest'
+require 'minitest/spec'
+require_relative 'mergify_plugin'
+require_relative '../mergify/minitest/declarations'
+
+# What a suite requires to report to Mergify, before its tests are defined.
+# Minitest 6 loads only the plugins it is asked for, so this registers ours;
+# Minitest 5 registers every installed plugin by itself, ours again, and the
+# plugin sets itself up once. Either way, only a suite that requires it gives
+# a test with no body the place it is declared (see Declarations); requiring
+# the spec DSL for that does what `minitest/autorun` does anyway.
+Minitest.extensions << 'mergify' unless Minitest.extensions.include?('mergify')
+Mergify::Minitest::Declarations.install

data/lib/minitest/mergify_plugin.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'mergify/minitest/plugin'
+
+# Minitest's plugin entry point. Minitest 5 finds this file in every installed
+# gem and loads it by itself; Minitest 6 loads it when the suite requires
+# `minitest/mergify`.
+module Minitest
+  # Called once Minitest has parsed its options, before any test runs.
+  def self.plugin_mergify_init(options)
+    Mergify::Minitest::Plugin.init(options)
+  end
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: minitest-mergify
+version: !ruby/object:Gem::Version
+  version: 2026.10.8
+platform: ruby
+authors:
+- Mergify
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: mergify-ci-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2026.10.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2026.10.8
+description: 'Minitest integration for Mergify Test Engine: the run reported to CI
+  Insights, test quarantine, Fail First on merge-queue bisection steps, and flaky
+  test detection.'
+email:
+- support@mergify.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- THIRD_PARTY_LICENSES
+- lib/mergify/minitest.rb
+- lib/mergify/minitest/declarations.rb
+- lib/mergify/minitest/names.rb
+- lib/mergify/minitest/plugin.rb
+- lib/mergify/minitest/recorder.rb
+- lib/mergify/minitest/reruns.rb
+- lib/mergify/minitest/results.rb
+- lib/mergify/minitest/selection.rb
+- lib/mergify/minitest/test_run.rb
+- lib/mergify/minitest/version.rb
+- lib/minitest/mergify.rb
+- lib/minitest/mergify_plugin.rb
+homepage: https://docs.mergify.com/test-engine/test-frameworks/minitest/
+licenses:
+- LicenseRef-Mergify-Proprietary
+metadata:
+  homepage_uri: https://docs.mergify.com/test-engine/test-frameworks/minitest/
+  bug_tracker_uri: https://github.com/Mergifyio/mergify-cli/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Minitest plugin for Mergify Test Engine
+test_files: []