mutineer 1.7.0 → 1.8.0

data/lib/mutineer/job_plan.rb

@@ -11,6 +11,8 @@ require_relative "mutator_registry"
 require_relative "mutant_id"
 require_relative "project_path"
 require_relative "external_backend"
+require_relative "isolation"
+require_relative "test_runners"
 require_relative "orphan_guard"
 
 module Mutineer
@@ -37,7 +39,20 @@ module Mutineer
     # `{id:, file:, subject:}` hash per matched mutant, in collection order: its
     # new id, its project-relative file and its subject's qualified name;
     # recorded even when a new id is also listed, since the old entry still
-    # over-matches other files) and `id_map` (every new id => its old-format id).
+    # over-matches other files), `id_map` (every reported mutant's new id =>
+    # its old-format id), `dropped_id_map` (the same for each dropped repeat of
+    # an edit: its id is still current for `mutineer migrate`) and `declined`
+    # (operator name => count of candidates that operator found and did not
+    # mutate, {Mutators::Base#declined}; only counts above zero, keys sorted).
+    # The name is the {MutatorRegistry::ALL} key, or the class's `to_s` for an
+    # operator outside the registry. `--only` narrows `declined`, and `--since`
+    # does not: a declined candidate has no mutation to place on a line.
+    #
+    # Mutations are collected in {MutatorRegistry::ALL} order, whatever the
+    # order of `operator_classes`. Two operators can give the same mutated
+    # source (#275), and the copy of the registry-first operator is the one
+    # that runs, so the kept copy and the run order do not depend on the
+    # `--operators` order.
     #
     # Subjects sharing a qualified name in one file (two owner-less `def index`
     # in two DSL blocks) get a per-file ordinal in discovery order, so their ids
@@ -46,8 +61,15 @@ module Mutineer
     # @param config [Mutineer::Config] run configuration.
     # @param operator_classes [Array<Class>] resolved operators.
     # @return [Array(Array, Array<Result>, Hash<String,String>, Hash{Symbol => Hash})]
-    #   jobs, ignored, source_map, and extras (`:legacy_ignore_matches`, `:id_map`).
+    #   jobs, ignored, source_map, and extras (`:legacy_ignore_matches`,
+    #   `:id_map`, `:dropped_id_map`, `:declined`).
     def self.collect_jobs(config, operator_classes)
+      # Registry order, so a repeat across operators keeps the registry-first
+      # copy (#275). A class outside ALL goes last; ties keep the input order.
+      rank = MutatorRegistry::ALL.values
+      operator_classes = operator_classes.each_with_index
+                                         .sort_by { |klass, i| [rank.index(klass) || rank.size, i] }
+                                         .map(&:first)
       source_map = {}
       disabled_map = {}
       id_paths = {}
@@ -61,10 +83,18 @@ module Mutineer
       ignored_results = []
       legacy_ignore_matches = {}
       id_map = {}
+      dropped_id_map = {}
+      declined = Hash.new(0)
       Project.discover(config.sources, only: config.only).each do |subject|
-        source = (source_map[subject.file] ||= File.read(subject.file))
+        source = (source_map[subject.file] ||= File.read(subject.file, encoding: "UTF-8"))
         disabled = (disabled_map[subject.file] ||= suppress_map(source, subject.file))
-        mutations = operator_classes.flat_map { |klass| klass.new.mutations_for(subject, source) }
+        # A repeated operator name runs once, so its declines count once.
+        mutations = operator_classes.uniq.flat_map do |klass|
+          operator = klass.new
+          found = operator.mutations_for(subject, source)
+          declined[MutatorRegistry::ALL.key(klass) || klass.to_s] += operator.declined
+          found
+        end
         id_path = (id_paths[subject.file] ||= ProjectPath.relative(subject.file, config.project_root))
         decls = name_decls[[id_path, subject.qualified_name]]
         ordinal = (decls[subject.def_node.location.start_offset] ||= decls.size)
@@ -72,22 +102,27 @@ module Mutineer
         legacy_ids = MutantId.legacy_for_subject(subject, source, mutations)
         lines = mutations.map { |m| source.byteslice(0, m.start_offset).count("\n") + 1 }
         keys = result_keys(mutations, source, lines)
-        # A repeat of an earlier edit on the same line is dropped (#159),
-        # separately among the run and the ignored mutants, so an ignored copy
-        # never hides a copy that should run. A dropped copy records nothing.
+        # A repeat of an earlier edit on the same line, from any operator, is
+        # dropped (#159, #275), separately among the run and the ignored
+        # mutants, so an ignored copy never hides a copy that should run. A
+        # dropped copy is not reported, but its id stays current for migrate.
         seen = { run: Set.new, ignored: Set.new }
         mutations.each_with_index do |mutation, i|
           id = ids[i]
           legacy = legacy_ids[i]
           ignored = suppressed?(mutation.operator, lines[i], [id, legacy], disabled, ignore_set)
-          next unless seen[ignored ? :ignored : :run].add?(keys[i])
-
-          id_map[id] = legacy
           # An old entry still over-matches other files even when the new id is
-          # listed too, so every old-entry match is reported for migration.
+          # listed too, so every old-entry match is reported for migration,
+          # including a dropped copy's.
           if ignore_set.include?(legacy)
             (legacy_ignore_matches[legacy] ||= []) << { id: id, file: id_path, subject: subject.qualified_name }
           end
+          unless seen[ignored ? :ignored : :run].add?(keys[i])
+            dropped_id_map[id] = legacy
+            next
+          end
+
+          id_map[id] = legacy
           if ignored
             reason = suppression_reason(mutation.operator, lines[i], [id, legacy], disabled, ignore_reasons)
             ignored_results << Result.ignored.with(subject: subject, mutation: mutation, id: id, reason: reason)
@@ -96,13 +131,15 @@ module Mutineer
           end
         end
       end
-      [jobs, ignored_results, source_map, { legacy_ignore_matches: legacy_ignore_matches, id_map: id_map }]
+      declined = declined.select { |_, count| count.positive? }.sort.to_h
+      [jobs, ignored_results, source_map, { legacy_ignore_matches: legacy_ignore_matches, id_map: id_map,
+                                            dropped_id_map: dropped_id_map, declined: declined }]
     end
 
-    # One key per mutation; two mutations share a key exactly when they are
-    # the same operator on the same line and give the same mutated source (one
-    # edit, #159). The caller drops a repeat after ids are assigned. Only a
-    # group of same-operator, same-line mutations can repeat, so only those
+    # One key per mutation; two mutations share a key exactly when they are on
+    # the same line and give the same mutated source (one edit), from one
+    # operator (#159) or two (#275). The caller drops a repeat after ids are
+    # assigned. Only a group of same-line mutations can repeat, so only those
     # build a key from their text: the span from the group's earliest start to
     # its latest end, digested. Every other mutation gets a key of its own.
     #
@@ -112,7 +149,7 @@ module Mutineer
     # @return [Array<Object>] one key per mutation, in order.
     def self.result_keys(mutations, source, lines)
       keys = Array.new(mutations.size) { |i| i }
-      mutations.each_index.group_by { |i| [mutations[i].operator, lines[i]] }.each_value do |group|
+      mutations.each_index.group_by { |i| lines[i] }.each_value do |group|
         next if group.size < 2
 
         from = group.map { |i| mutations[i].start_offset }.min
@@ -120,7 +157,7 @@ module Mutineer
         group.each do |i|
           m = mutations[i]
           span = "#{source.byteslice(from...m.start_offset)}#{m.replacement}#{source.byteslice(m.end_offset...to)}"
-          keys[i] = [m.operator, lines[i], Digest::SHA256.digest(span)]
+          keys[i] = [lines[i], Digest::SHA256.digest(span)]
         end
       end
       keys
@@ -130,10 +167,14 @@ module Mutineer
     # those results would treat existing assertion failures as killed mutants.
     #
     # @param coverage_map [Mutineer::CoverageMap] the built or loaded map.
+    # @param framework [String, nil] the run's framework (nil is Minitest, as in
+    #   {TestRunners.for}). For Minitest, the message names the seed: an
+    #   order-dependent suite can pass in a random order and fail in the
+    #   pinned one (#282).
     # @return [void]
     # @raise [Mutineer::SmokeCheckError] when any captured test failed clean,
     #   or when no test recorded coverage and a capture failed.
-    def self.abort_if_unclean!(coverage_map)
+    def self.abort_if_unclean!(coverage_map, framework: nil)
       if coverage_map.map.empty? && coverage_map.failed_test_files.any?
         raise SmokeCheckError, "no test recorded coverage, and capture failed for #{coverage_map.failed_test_files.join(', ')}"
       end
@@ -141,9 +182,47 @@ module Mutineer
       files = coverage_map.failed_clean_tests
       return if files.empty?
 
+      seed_hint = TestRunners.for(framework) == TestRunners::Minitest ? minitest_seed_hint : ""
       raise SmokeCheckError,
             "the unmutated suite is not green (#{files.join(', ')}) — " \
-            "#{ExternalBackend.generic_env_hint}."
+            "#{ExternalBackend.generic_env_hint}.#{seed_hint}"
+    end
+
+    # Names the configured seed, and accounts for helper overrides.
+    #
+    # @api private
+    # @return [String]
+    def self.minitest_seed_hint
+      seed = MinitestIntegration.seed
+      " Mutineer runs Minitest with SEED=#{seed}, unless a test helper changes SEED. " \
+        "An order-dependent test can fail here and pass in another order. " \
+        "Check the listed test files with the same seed and helpers " \
+        "(for \"combined suite\", all of them together). " \
+        "Change SEED, including helper settings, to choose another order."
+    end
+
+    # The reload mutant text for a def in a concern's `included` or `prepended`
+    # block (#297): the mutated file with one statement added just before the
+    # hook call, `::Mutineer::ConcernBlocks.store_hook_def do <mutated def> end`.
+    # The statement sits in the same body as the hook call, so the stored def has
+    # the block's constant scope. After the load, the child passes the hook-def
+    # values to {ConcernBlocks.place_hook_def}. Shared by {Runner.run} and
+    # {DaemonBackend.job_result}, so both build the same text. The hook call starts
+    # before the def, so the mutation does not move its offset. A bad insert is
+    # not checked here: the child's `load` raises `SyntaxError` before any test
+    # runs, so the mutant scores `error`.
+    #
+    # @param mutated [String] the mutated source text.
+    # @param mutation [Mutineer::Mutation] the mutation.
+    # @param subject [Mutineer::Subject] a subject with a {Subject#reload_hook_call}.
+    # @param source [String] the original source text.
+    # @return [Array(String, Hash{Symbol => Object})] the mutant text, and the
+    #   original def's `line`, `name` and `singleton`.
+    def self.hook_mutant(mutated, mutation, subject, source)
+      at = subject.reload_hook_call.location.start_offset
+      stored = "::Mutineer::ConcernBlocks.store_hook_def do\n#{Isolation.mutated_def(mutation, subject, source)}\nend; "
+      [mutated.byteslice(0...at) + stored + mutated.byteslice(at..),
+       { line: subject.def_node.location.start_line, name: subject.name, singleton: subject.singleton }]
     end
 
     # Coverage-based test selection, shared by the in-process ({Runner.run}) and daemon
@@ -152,11 +231,14 @@ module Mutineer
     # order of {CoverageMap#order_tests} (paired files, then cheapest), or
     # `[:verdict, Result]` (no_coverage / uncapturable) when none do. A line
     # Ruby does not count (a later line of a multi-line statement) uses the
-    # tests that ran the statement that holds it ({StatementLines}). When the
-    # mutant sits in code of that statement that runs only sometimes (the right
-    # side of a multi-line `a && b`), those tests may not have run it, so the
-    # answer is `[:maybe, abs_test_paths]` and {selection_verdict} treats a
-    # survivor as no_coverage (#254).
+    # tests that ran the statement that holds it ({StatementLines}). When those
+    # lines give no tests, it retries with the loose lines of the statement:
+    # code of the statement that runs only sometimes (the right side of a
+    # multi-line `a && b`, #254), and a first or last line that holds other
+    # code (the opener of a one-line block, #289), but never the `def` line.
+    # Those tests may not have run the mutant, so the answer is
+    # `[:maybe, abs_test_paths]` and {selection_verdict} treats a survivor as
+    # no_coverage.
     #
     # An empty selection is `:ran_at_load` when the mutant's line ran while the
     # app booted or its class loaded ({ran_at_load?}): no test ran it, but the
@@ -182,11 +264,12 @@ module Mutineer
       if chosen.empty? && subject
         # A multi-line statement has a count on one of its lines only.
         lines = StatementLines.for(subject.def_node, source, mutation.start_offset)
-        if lines.empty?
+        chosen = lines.flat_map { |l| coverage_map.tests_for(source_file, l) }.uniq
+        if chosen.empty?
           lines = StatementLines.for(subject.def_node, source, mutation.start_offset, loose: true)
+          chosen = lines.flat_map { |l| coverage_map.tests_for(source_file, l) }.uniq
           kind = :maybe
         end
-        chosen = lines.flat_map { |l| coverage_map.tests_for(source_file, l) }.uniq
       end
       if chosen.empty?
         # Method BODY range, not the whole def: the def/end lines are "covered" at
@@ -435,16 +518,17 @@ module Mutineer
       config.sources.map { |f| File.dirname(File.expand_path(f, config.project_root)) }.uniq
     end
 
-    # Removes stale mutant tempfiles from the given directories. The daemon writes a
-    # differently-named temp, so {DaemonBackend} passes its glob when it sweeps
-    # tool-side at the end of every daemon run, empty or not.
-    # A daemon file another process still owns is left in place. In-process mutant
-    # files have no owner recorded in the name, so this still removes those orphans.
+    # Removes stale mutant tempfiles from the given directories. The default
+    # glob matches the files of both modes, so the in-process boot sweep also
+    # removes an old daemon file (#287). {DaemonBackend} passes its daemon-only
+    # glob when it sweeps tool-side at the end of every daemon run, empty or not.
+    # A file another process still owns is left in place: both modes record the
+    # creating pid in the name and lock the file while it loads (#295).
     #
     # @param dirs [Array<String>] directories to sweep.
     # @param glob [String] filename pattern to remove.
     # @return [Array<String>] the files left in place because a process owns them.
-    def self.sweep_orphans(dirs, glob = "{.,}mutineer_mutant*.rb")
+    def self.sweep_orphans(dirs, glob = OrphanGuard::TEMP_BASENAME)
       dirs.flat_map do |dir|
         Dir.glob(File.join(dir, glob)).select do |path|
           next true if OrphanGuard.mutant_file_in_use?(path)

data/lib/mutineer/kill_channel.rb

@@ -9,6 +9,7 @@ module Mutineer
   #   ["start"]                         the recorder is armed; once, first
   #   ["pass", file, name, id]          a test passed against the mutant
   #   ["kill", file, name, id]          a test failed or errored: it killed it
+  #   ["unavailable", file, name, id]   a test ran but its database failed
   #   ["parallel"]                      the run reached its parallel tests; once
   #   ["skip"]                          what runs next, a run without --matrix
   #                                     skips (see below)
@@ -27,20 +28,22 @@ module Mutineer
   #
   # Minitest runs its serial test classes first and its `parallelize_me!`
   # classes after them, and the stop at the first failure of a run without
-  # `--matrix` skips everything after a serial kill. `parallel` marks where the
+  # `--matrix` skips everything after a serial failure. `parallel` marks where the
   # parallel tests begin, so the parent can tell a kill that the stop would have
   # followed from one it could not. `cleanup` marks where the tests end and the
   # suite's own hooks begin (RSpec `after(:suite)`). It decides no verdict
   # (the `skip` regions do); it only marks a later test line as out of order.
   #
-  # After the first serial kill, a run without `--matrix` skips every later
+  # After the first serial failure, a run without `--matrix` skips every later
   # test and every later test class or example group, but it still runs the
   # rest of the code around the failing test: the remainder of its Minitest
   # class `run` wrapper, the `after(:all)` hooks of its RSpec groups, and the
   # suite hooks. The recorder writes `skip` as it enters something that run
   # would skip and `unskip` as that returns, so a child that exits, crashes or
   # hangs inside a skipped region is one the plain run would have stopped
-  # before (see {Isolation.finish}). The pairs nest.
+  # before (see {Isolation.finish}). Its first failure decides the verdict:
+  # killed for a real kill, error for an unavailable database outcome. The
+  # pairs nest. An unavailable result also leaves the row incomplete.
   #
   # A row is complete only with `start` and `end`, in order, and no lost line: a
   # test that exits the process, a crash, an interrupted run or a recorder that
@@ -61,6 +64,9 @@ module Mutineer
     # Event for a test that failed or errored against the mutant: it killed it.
     KILL = "kill"
 
+    # Event for a test whose database failed, so it provides no mutation verdict.
+    UNAVAILABLE = "unavailable"
+
     # Event that opens a recorded run.
     START = "start"
 
@@ -87,17 +93,18 @@ module Mutineer
 
     # What one child sent. `killed` and `ran` are sorted, unique
     # `[file, name, id]` tests (`ran` includes the killers); `lost` counts lines
-    # that could not be read, including a partial last line. `parallel` and
-    # `cleanup` say the marker arrived, and `serial_kill` that a test killed
-    # before the `parallel` marker. `skipping` counts the {SKIP} regions still
+    # that could not be read, including a partial last line, and unavailable
+    # outcomes. `parallel` and `cleanup` say the marker arrived. `serial_kill`
+    # or `serial_error` says which failure came first before `parallel`.
+    # `skipping` counts the {SKIP} regions still
     # open when the stream ended. `invalid` is set by any line out of order.
-    Report = Struct.new(:killed, :ran, :started, :finished, :parallel, :cleanup, :serial_kill, :skipping, :invalid,
+    Report = Struct.new(:killed, :ran, :started, :finished, :parallel, :cleanup, :serial_kill, :serial_error, :skipping, :invalid,
                         :lost, keyword_init: true)
 
     # Writes one test line.
     #
     # @param io [IO] the write end of the channel.
-    # @param event [String] {PASS} or {KILL}.
+    # @param event [String] {PASS}, {KILL}, or {UNAVAILABLE}.
     # @param file [String] the file that defines the test.
     # @param name [String] the test's display name, e.g. `CalculatorTest#test_add`.
     # @param id [String] what tells the test apart from others with its file and
@@ -169,7 +176,7 @@ module Mutineer
     # @return [Report]
     def self.parse(buffer)
       report = Report.new(killed: [], ran: [], started: false, finished: false, parallel: false, cleanup: false,
-                          serial_kill: false, skipping: 0, invalid: false, lost: 0)
+                          serial_kill: false, serial_error: false, skipping: 0, invalid: false, lost: 0)
       buffer.dup.force_encoding(Encoding::UTF_8).each_line do |line|
         fields = line.end_with?("\n") ? parse_line(line) : nil
         fields ? apply(report, fields) : report.lost += 1
@@ -211,10 +218,13 @@ module Mutineer
         report.invalid = true unless open?(report) && !report.cleanup
         test = fields[1, 3]
         report.ran << test
-        return unless fields[0] == KILL
-
-        report.killed << test
-        report.serial_kill = true unless report.parallel
+        if fields[0] == UNAVAILABLE
+          report.lost += 1
+          report.serial_error = true unless report.parallel || report.serial_kill
+        elsif fields[0] == KILL
+          report.killed << test
+          report.serial_kill = true unless report.parallel || report.serial_error
+        end
       end
     end
 
@@ -238,7 +248,7 @@ module Mutineer
 
       valid =
         case fields[0]
-        when PASS, KILL then fields.size == 4
+        when PASS, KILL, UNAVAILABLE then fields.size == 4
         when START, PARALLEL, SKIP, UNSKIP, CLEANUP, LOST, FINISH then fields.size == 1
         end
       fields if valid

data/lib/mutineer/migrate.rb

@@ -7,11 +7,12 @@ require_relative "mutator_registry"
 
 module Mutineer
   # Rewrites old-format mutant ids in a `.mutineer.yml` `ignore:` list to the
-  # current id format. The map is the inverse of the `id_map` from
-  # {JobPlan.collect_jobs}: each old id goes to every new id that still hashes
-  # to it, in collection order. The map covers only the configured operators
-  # and the sources on the command line. Ids are static hashes, so this runs
-  # no tests.
+  # current id format. The map is the inverse of the `id_map` and
+  # `dropped_id_map` from {JobPlan.collect_jobs}: each old id goes to every new
+  # id that still hashes to it, reported ids first, each group in collection
+  # order. A dropped repeat of an edit is not reported, but its id is still
+  # current (#275). The map covers only the configured operators and the
+  # sources on the command line. Ids are static hashes, so this runs no tests.
   #
   # The file is edited as text. A YAML load and dump would drop comments and
   # reorder keys. Only a bare id inside `ignore:` is replaced. A flow list may
@@ -23,7 +24,7 @@ module Mutineer
   # one mapping, so it is left in place and reported for a hand edit. A
   # baseline file is never read.
   module Migrate
-    # One old id and the new ids that replace it, in collection order.
+    # One old id and the new ids that replace it, in {Migrate.id_maps} order.
     Replacement = Data.define(:old_id, :new_ids)
 
     # The outcome of rewriting one file in memory. `text` is what to write.
@@ -42,12 +43,13 @@ module Mutineer
     def self.id_maps(config)
       names = config.operators || MutatorRegistry::DEFAULT_NAMES
       _jobs, _ignored, _source_map, extras = JobPlan.collect_jobs(config, MutatorRegistry.resolve(names))
+      all = extras[:id_map].merge(extras[:dropped_id_map])
       old_to_new = {}
-      extras[:id_map].each do |new_id, old_id|
+      all.each do |new_id, old_id|
         list = (old_to_new[old_id] ||= [])
         list << new_id unless list.include?(new_id)
       end
-      [extras[:id_map].keys.to_set, old_to_new]
+      [all.keys.to_set, old_to_new]
     end
 
     # Rewrites `ignore:` ids in `text`. An id that is already a current new id

data/lib/mutineer/minitest_integration/in_test_database_error.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require_relative "outer_reporter"
+require_relative "../redaction"
+
+module Mutineer
+  class MinitestIntegration
+    # Scores a run as `error`, not `killed`, when its first failing test failed
+    # because of an Active Record connection or lock error (#296). Such a
+    # failure says the database broke, not that a test caught the mutant.
+    # Child-process only, like MinitestIntegration.
+    #
+    # Only the first failed result on the outer reporter counts (see
+    # {OuterReporter}). A run that stops at its first failure ends there, so a
+    # full run and a `--matrix` run give the same verdict. One limit: the tests
+    # of a `parallelize_me!` class record in the order their threads finish, so
+    # a mutant that makes one parallel test hit a database error and another
+    # fail an assertion can score `error` in one run and `killed` in the next.
+    # Stdlib only: the app-side daemon loads this file without Prism. An
+    # unknown Minitest shape arms nothing, and the run keeps its 0 or 1.
+    module InTestDatabaseError
+      extend OuterReporter::Client
+
+      # The Active Record errors that mean the database, not the test, failed.
+      # Subclasses count too: `ConnectionTimeoutError` (a pool timeout) and
+      # `DatabaseConnectionError` are `ConnectionNotEstablished`. Looked up by
+      # name when a result is recorded, so a project without Active Record, or
+      # a Rails without `ConnectionFailed` (before 7.1), matches nothing. Other
+      # `StatementInvalid` errors are not here: a mutant can cause bad SQL.
+      NAMES = %w[
+        ActiveRecord::ConnectionNotEstablished
+        ActiveRecord::ConnectionFailed
+        ActiveRecord::Deadlocked
+        ActiveRecord::LockWaitTimeout
+      ].freeze
+
+      # Subclasses of {NAMES} that point at the code, not the database. Rails 8
+      # raises `ConnectionNotDefined` for a role or shard that no connection
+      # defines, which a mutant of a `connected_to` call can cause. Rails 7.2
+      # raises a plain `ConnectionNotEstablished` there, so on 7.2 such a mutant
+      # scores `error`. The message is not matched (plan Q2).
+      CODE_ERROR_NAMES = %w[ActiveRecord::ConnectionNotDefined].freeze
+
+      # The lock errors in {NAMES}, which get their own stderr hint.
+      LOCK_ERROR_NAMES = %w[ActiveRecord::Deadlocked ActiveRecord::LockWaitTimeout].freeze
+
+      # Prepended on `Minitest::CompositeReporter`.
+      module RecordFirstFailure
+        # Records the result, then lets the module keep the first failure.
+        #
+        # @param result [Minitest::Result] the result of one test.
+        # @return [void]
+        def record(result)
+          super
+          InTestDatabaseError.record(self, result)
+        end
+      end
+
+      class << self
+        # The first failed result's database error, false when that result
+        # failed for another reason, or nil before any failure.
+        #
+        # @return [Exception, false, nil]
+        attr_accessor :first_failure
+
+        # Installs the hooks and arms the module for this process.
+        #
+        # @return [Boolean] false when the Minitest shape is unknown.
+        def arm!
+          outer = OuterReporter.hook_for_loaded_minitest
+          return false unless outer
+
+          OuterReporter.prepend_once(::Minitest::CompositeReporter, RecordFirstFailure)
+          OuterReporter.prepend_once(::Minitest.singleton_class, outer)
+          OuterReporter.register(self)
+          self.armed_pid = Process.pid
+          self.armed_reporter = nil
+          self.first_failure = nil
+          true
+        end
+
+        # Clears the armed state.
+        #
+        # @return [void]
+        def disarm!
+          self.armed_pid = nil
+          self.armed_reporter = nil
+          self.first_failure = nil
+        end
+
+        # Keeps the first failed result recorded on the outer reporter. Minitest
+        # records from several threads only under its own reporter lock. A
+        # result it cannot read counts as an ordinary failure, so a fault here
+        # keeps the old verdict and never turns a kill into an error.
+        #
+        # @param reporter [Minitest::CompositeReporter] the recording reporter.
+        # @param result [Minitest::Result] the result of one test.
+        # @return [void]
+        def record(reporter, result)
+          return if result.passed? || result.skipped?
+          return unless first_failure.nil? && outer_reporter?(reporter)
+
+          self.first_failure = database_error(result.failures.first) || false
+        rescue StandardError
+          self.first_failure = false
+        end
+
+        # The run's exit code: 2 instead of 1 when the armed run's first failure
+        # was a database error. Then it also writes one line on stderr that
+        # names the error. `STDERR`, not `warn`: a test can leave `$stderr` as
+        # a `StringIO`. The flush matters because both fork boundaries end with
+        # `exit!`.
+        #
+        # @param code [Integer] 0 or 1 from the run.
+        # @return [Integer] `code`, or 2.
+        def exit_code(code)
+          error = first_failure if armed_here?
+          return code unless code == 1 && error
+
+          STDERR.puts(line(error))
+          STDERR.flush
+          2
+        end
+
+        # The database error a failure wraps. The first entry of a result is
+        # the error that ended the test: Minitest records the setup or body
+        # error before a teardown error. The cause chain is not read: Active
+        # Record already translates driver errors into the listed classes.
+        #
+        # Minitest before 5.14 names the wrapped error `exception`.
+        #
+        # Shared with the matrix recorder so an unavailable database outcome
+        # cannot be named as a mutation kill.
+        #
+        # @api private
+        # @param failure [Minitest::Assertion, nil] the result's first entry.
+        # @return [Exception, nil]
+        def database_error(failure)
+          return unless failure.is_a?(::Minitest::UnexpectedError)
+
+          error = failure.respond_to?(:error) ? failure.error : failure.exception
+          return if loaded(CODE_ERROR_NAMES).any? { |klass| error.is_a?(klass) }
+
+          error if loaded(NAMES).any? { |klass| error.is_a?(klass) }
+        end
+
+        private
+
+        # The named classes this process has loaded.
+        #
+        # @param names [Array<String>] constant names.
+        # @return [Array<Class>]
+        def loaded(names)
+          names.filter_map { |name| Object.const_get(name) if Object.const_defined?(name) }
+        end
+
+        # The stderr line. Redacted before the cut to one line, so a cut can
+        # never split a password away from its URL. The wording fits every run,
+        # the clean check included, and a mutant can cause the error too.
+        #
+        # @param error [Exception] the database error.
+        # @return [String]
+        def line(error)
+          text = Redaction.text("#{error.class}: #{error.message}".scrub)
+          text = text.lines.first.to_s.chomp.delete_suffix(".")
+          "[mutineer-child] a test failed with a database error, so the run has no verdict: #{text}. #{hint(error)}"
+        end
+
+        # What to check for the error: a lock error comes from a second
+        # connection or thread, any other from the server.
+        #
+        # @param error [Exception] the database error.
+        # @return [String]
+        def hint(error)
+          if loaded(LOCK_ERROR_NAMES).any? { |klass| error.is_a?(klass) }
+            "Look for a test or app code that holds a lock on a second connection or thread."
+          else
+            "Check that the database server is up and has free connections."
+          end
+        end
+      end
+    end
+  end
+end