coatepec 0.7.0 → 0.9.0

data/lib/coatepec/spec/path_policy.rb

@@ -3,23 +3,32 @@
 module Coatepec
   module Spec
     # Validates rails_spec_run's `paths` selectors against the allowed spec
-    # roots before any RSpec process is started, rejecting absolute paths,
-    # `..` traversal, symlink escapes, non-`_spec.rb` files, and oversized
-    # selector lists.
+    # and test roots before any test process is started, rejecting absolute
+    # paths, `..` traversal, symlink escapes, files that are neither
+    # `_spec.rb` under a spec root nor `_test.rb` under a test root, and
+    # oversized selector lists. Also classifies the whole list as RSpec or
+    # Minitest from the selectors' shape: a list may not mix the two.
     class PathPolicy
       MAX_SELECTORS = 100
 
+      KINDS = {
+        rspec: { roots: :spec_root_candidates, suffix: "_spec.rb" },
+        minitest: { roots: :test_root_candidates, suffix: "_test.rb" }
+      }.freeze
+
       def initialize(project)
         @project = project
       end
 
+      # Returns { selectors: [...], framework: :rspec | :minitest }.
       def validate!(selectors)
         raise Coatepec::Error.new(:invalid_spec_path, "No spec paths given") if selectors.nil? || selectors.empty?
         if selectors.size > MAX_SELECTORS
           raise Coatepec::Error.new(:invalid_spec_path, "At most #{MAX_SELECTORS} spec paths are allowed")
         end
 
-        selectors.map { |selector| validate_one(selector) }
+        classified = selectors.map { |selector| validate_one(selector) }
+        { selectors: classified.map { |c| c[:selector] }, framework: single_framework!(classified) }
       end
 
       private
@@ -31,9 +40,24 @@ module Coatepec
 
         real_path = resolve_real_path!(selector, path_part)
         reject_escape!(selector, real_path)
-        reject_wrong_kind!(selector, real_path)
+        framework = framework_for!(selector, real_path)
+
+        { selector: line_part ? "#{path_part}:#{line_part}" : path_part, framework: framework }
+      end
+
+      def single_framework!(classified)
+        frameworks = classified.map { |c| c[:framework] }.uniq
+        return frameworks.first if frameworks.size == 1
 
-        line_part ? "#{path_part}:#{line_part}" : path_part
+        raise Coatepec::Error.new(:mixed_test_frameworks, mixed_frameworks_message(classified))
+      end
+
+      # Names the minority selectors: the ones an agent most likely added by
+      # mistake to an otherwise single-framework call.
+      def mixed_frameworks_message(classified)
+        majority = classified.group_by { |c| c[:framework] }.max_by { |_, list| list.size }.first
+        odd = classified.reject { |c| c[:framework] == majority }.map { |c| c[:selector] }
+        "A single call may not mix RSpec and Minitest selectors; these do not match the others: #{odd.join(", ")}"
       end
 
       def resolve_real_path!(selector, path_part)
@@ -74,15 +98,24 @@ module Coatepec
         raise Coatepec::Error.new(:invalid_spec_path, "Spec path escapes the project root: #{selector}")
       end
 
-      def reject_wrong_kind!(selector, real_path)
-        return if under_allowed_root?(real_path) && (File.directory?(real_path) || real_path.end_with?("_spec.rb"))
+      # A directory under a root is that root's kind; a file must also carry
+      # the kind's suffix. The two root sets never overlap (spec/ vs test/),
+      # so the iteration order does not matter.
+      def framework_for!(selector, real_path)
+        KINDS.each do |framework, kind|
+          next unless under_any_root?(real_path, @project.public_send(kind[:roots]))
+          return framework if File.directory?(real_path) || real_path.end_with?(kind[:suffix])
+        end
 
-        raise Coatepec::Error.new(:invalid_spec_path,
-                                  "Spec path is not an allowed spec root or _spec.rb file: #{selector}")
+        raise Coatepec::Error.new(
+          :invalid_spec_path,
+          "Spec path is not an allowed spec/test root, a _spec.rb file under spec/, " \
+          "or a _test.rb file under test/: #{selector}"
+        )
       end
 
-      def under_allowed_root?(real_path)
-        @project.spec_root_candidates.any? do |candidate|
+      def under_any_root?(real_path, roots)
+        roots.any? do |candidate|
           real_candidate = File.realpath(candidate)
           real_path == real_candidate || real_path.start_with?("#{real_candidate}/")
         end

data/lib/coatepec/spec/process_strategy.rb

@@ -4,18 +4,22 @@ require "tempfile"
 
 module Coatepec
   module Spec
-    # Shared child-process lifecycle for running an isolated RSpec run: spawns
-    # (via a subclass's #start), reaps with a timeout budget (TERM then KILL
-    # on overrun), and hands the captured output/JSON to Result. Subclasses
-    # (ForkStrategy, SpawnStrategy) only implement how the child is started.
+    # Shared child-process lifecycle for running an isolated test run (RSpec
+    # or Minitest, chosen by the injected adapter): spawns (via a subclass's
+    # #start), reaps with a timeout budget (TERM then KILL on overrun), and
+    # hands the captured output/JSON to Result. Subclasses (ForkStrategy,
+    # SpawnStrategy) only implement how the child is started; the adapter
+    # supplies the framework-specific CLI args, in-process call, and spawn
+    # command line.
     class ProcessStrategy
-      def initialize(project_root, project: nil, rails_runtime: nil)
+      def initialize(project_root, adapter: nil, project: nil, rails_runtime: nil)
         @project_root = project_root
+        @adapter = adapter || RSpecAdapter.new(project_root)
         @project = project
         @rails_runtime = rails_runtime
       end
 
-      def run(args, timeout_seconds)
+      def run(args, timeout_seconds, include_passing: false, include_stdout: "failures")
         out_r, out_w = IO.pipe
         err_r, err_w = IO.pipe
         json_path = Tempfile.create(["coatepec-rspec", ".json"], &:path)
@@ -23,14 +27,22 @@ module Coatepec
         pid = start_or_release(args, out_w, err_w, json_path, [out_r, err_r])
         [out_w, err_w].each(&:close)
 
-        reap(pid, out_r, err_r, timeout_seconds, json_path)
+        reap(pid, [out_r, err_r], timeout_seconds, json_path,
+             { include_passing: include_passing, include_stdout: include_stdout })
+          .merge(execution_mode: execution_mode)
       end
 
       private
 
-      # Subclasses start a process and return its pid; RSpec's own output
-      # must be wired to out_w/err_w.
-      def start(_full_args, _out_w, _err_w)
+      # Every result says how it ran, so an absent key can never be mistaken for "the guard fell back".
+      def execution_mode
+        raise NotImplementedError, "#{self.class} must implement #execution_mode"
+      end
+
+      # Subclasses start a process and return its pid; the test framework's
+      # own output must be wired to out_w/err_w. json_path is where the
+      # adapter's structured per-example output must land.
+      def start(_full_args, _out_w, _err_w, _json_path)
         raise NotImplementedError, "#{self.class} must implement #start"
       end
 
@@ -39,20 +51,19 @@ module Coatepec
       # released have to be freed here. The original exception still reaches
       # the caller -- only GuardedForkStrategy intercepts it to fall back.
       def start_or_release(args, out_w, err_w, json_path, read_ends)
-        start(args + json_format_args(json_path), out_w, err_w)
+        start(args + @adapter.json_args(json_path), out_w, err_w, json_path)
       rescue StandardError
         ([out_w, err_w] + read_ends).each { |io| io.close unless io.closed? }
         File.delete(json_path) if File.exist?(json_path)
         raise
       end
 
-      def json_format_args(json_path)
-        ["--format", "progress", "--format", "json", "--out", json_path]
-      end
-
-      def reap(pid, out_r, err_r, timeout_seconds, json_path)
+      # result_options are Result.build's include_* keywords, bundled so the positional list stays short.
+      def reap(pid, pipes, timeout_seconds, json_path, result_options)
+        out_r, err_r = pipes
         status = wait_with_timeout(pid, timeout_seconds)
-        result = Result.build(pid: pid, status: status, out_r: out_r, err_r: err_r, json_path: json_path)
+        result = Result.build(pid: pid, status: status, out_r: out_r, err_r: err_r, json_path: json_path,
+                              **result_options)
         [out_r, err_r].each(&:close)
         result
       ensure

data/lib/coatepec/spec/result.rb

@@ -4,45 +4,79 @@ require "json"
 
 module Coatepec
   module Spec
-    # Turns a finished RSpec child process's exit status, captured
-    # stdout/stderr (each capped at MAX_OUTPUT_BYTES), and RSpec's own JSON
-    # formatter output into the flat result hash rails_spec_run returns.
+    # Turns a finished test child's exit status, captured output (each capped
+    # at MAX_OUTPUT_BYTES) and the framework's JSON summary into the flat
+    # result hash rails_spec_run returns. Passing examples are omitted unless
+    # include_passing; stdout is kept for failing runs unless include_stdout
+    # says always or never, and its repeated failure blocks are collapsed by FailureCollapser.
     module Result
       MAX_OUTPUT_BYTES = 256 * 1024
+      MAX_EXAMPLES = 500
+      STDOUT_MODES = %w[failures always never].freeze
 
       module_function
 
-      def build(pid:, status:, out_r:, err_r:, json_path:)
-        stdout_result = read_bounded(out_r)
+      def build(pid:, status:, out_r:, err_r:, json_path:, include_passing: false, include_stdout: "failures")
+        validate_stdout_mode!(include_stdout)
+        captured = read_bounded(out_r)
+        stdout_result = keep_stdout?(include_stdout, status) ? collapse_failures(captured) : captured.merge(text: nil)
         stderr_result = read_bounded(err_r)
         summary = read_summary(json_path)
 
         base(pid, status, stdout_result, stderr_result).merge(
           summary: summary && summary_fields(summary),
-          examples: (summary&.fetch("examples", []) || []).first(500).map { |e| example_fields(e) }
+          examples: selected_examples(summary, include_passing).map { |e| example_fields(e) }
         )
       end
 
-      # rubocop:disable Metrics/MethodLength -- one flat hash literal mapping
-      # Process::Status/captured-output fields to the result payload's own
-      # field names; splitting it would scatter that 1:1 mapping across
-      # methods for no readability gain.
+      # A green run's stdout is progress dots and a summary line the payload already carries as counts.
+      def keep_stdout?(mode, status)
+        mode == "always" || (mode == "failures" && !passed?(status))
+      end
+
+      def passed?(status)
+        status.exited? && status.exitstatus.zero?
+      end
+
+      # The MCP schema enforces the enum; this guards the worker command against any other caller.
+      def validate_stdout_mode!(mode)
+        return if STDOUT_MODES.include?(mode)
+
+        raise Coatepec::Error.new(:invalid_include_stdout,
+                                  "include_stdout must be one of #{STDOUT_MODES.join(", ")}, got #{mode.inspect}")
+      end
+
+      # Repeated failure text is the bulk of a failing run's stdout; examples[] already names every failing test.
+      def collapse_failures(captured)
+        captured.merge(text: FailureCollapser.call(captured[:text]))
+      end
+
+      # Passing examples are dropped before the cap so a large green run never crowds out its failures.
+      def selected_examples(summary, include_passing)
+        examples = summary&.dig("examples") || []
+        examples = examples.reject { |e| e["status"] == "passed" } unless include_passing
+        examples.first(MAX_EXAMPLES)
+      end
+
       def base(pid, status, stdout_result, stderr_result)
         {
-          status: status.exited? && status.exitstatus.zero? ? "passed" : "failed",
+          status: passed?(status) ? "passed" : "failed",
           exit_code: status.exitstatus,
-          child_pid: pid,
-          signaled: status.signaled?,
-          termsig: status.termsig,
-          stopsig: status.stopsig,
-          coredump: status.respond_to?(:coredump?) ? status.coredump? : false,
+          **process_fields(pid, status),
           stdout: stdout_result[:text],
           stdout_truncated: stdout_result[:truncated],
           stderr: stderr_result[:text],
           stderr_truncated: stderr_result[:truncated]
         }
       end
-      # rubocop:enable Metrics/MethodLength
+
+      # A normal exit has nothing to say about signals; these five appear only when the child did not exit.
+      def process_fields(pid, status)
+        return {} if status.exited?
+
+        { child_pid: pid, signaled: status.signaled?, termsig: status.termsig, stopsig: status.stopsig,
+          coredump: status.respond_to?(:coredump?) ? status.coredump? : false }
+      end
 
       def read_summary(json_path)
         return nil unless File.exist?(json_path) && !File.empty?(json_path)
@@ -50,22 +84,30 @@ module Coatepec
         JSON.parse(File.read(json_path))
       end
 
+      # error_count and assertion_count exist only for Minitest; RSpec's JSON has neither, so they read as nil.
       def summary_fields(summary)
         {
           example_count: summary.dig("summary", "example_count"),
           failure_count: summary.dig("summary", "failure_count"),
+          error_count: summary.dig("summary", "error_count"),
+          pending_count: summary.dig("summary", "pending_count"),
+          assertion_count: summary.dig("summary", "assertion_count"),
           duration: summary.dig("summary", "duration")
         }
       end
 
+      # description is Minitest's id by construction and RSpec's full_description; only emit it when it adds something.
       def example_fields(example)
-        {
+        description = example["full_description"]
+        fields = {
           id: example["id"],
-          description: example["full_description"],
+          description: description,
           status: example["status"],
           file_path: example["file_path"],
           line_number: example["line_number"]
         }
+        fields.delete(:description) if description.nil? || description == example["id"]
+        fields
       end
 
       def read_bounded(io)

data/lib/coatepec/spec/rspec_adapter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Spec
+    # The RSpec half of the framework adapter contract the process
+    # strategies run against: CLI args, the JSON formatter wiring, the
+    # in-process call a forked child makes, and the spawn command line.
+    # Every method here is a verbatim extraction of what Runner/
+    # ProcessStrategy/ForkStrategy/SpawnStrategy did inline before
+    # TestUnit::Adapter needed the same seams.
+    class RSpecAdapter
+      def initialize(project_root)
+        @project_root = project_root
+      end
+
+      def framework
+        :rspec
+      end
+
+      def require_framework!
+        require "rspec/core"
+      rescue LoadError
+        raise Coatepec::Error.new(:unsupported_test_framework, "rspec-rails must be in the application's test group")
+      end
+
+      def build_args(selectors, example, seed, fail_fast)
+        args = selectors.dup
+        args += ["-e", example] if example
+        args += ["--seed", seed.to_s] if seed
+        args << "--fail-fast" if fail_fast
+
+        args
+      end
+
+      def json_args(json_path)
+        ["--format", "progress", "--format", "json", "--out", json_path]
+      end
+
+      # Runs inside the forked child. RSpec freezes its own "load started
+      # at" timestamp once, at the moment rspec/core.rb is first required --
+      # in this architecture, that's when the long-lived warm worker booted,
+      # not when THIS run started. Every forked child inherits that frozen
+      # timestamp via copy-on-write, so RSpec's own "(files took N seconds
+      # to load)" reporting would otherwise measure "time since the worker
+      # booted" and grow across every run for as long as the worker stays
+      # warm. Reset it fresh before each run.
+      def run_in_process(full_args, _json_path)
+        RSpec.configuration.start_time = RSpec::Core::Time.now
+
+        RSpec::Core::Runner.run(full_args, $stderr, $stdout)
+      end
+
+      def spawn_command(full_args, _json_path)
+        [{ "RAILS_ENV" => "test" }, ["bundle", "exec", "rspec", *full_args]]
+      end
+    end
+  end
+end

data/lib/coatepec/spec/runner.rb

@@ -2,10 +2,11 @@
 
 module Coatepec
   module Spec
-    # Validates a `rails_spec_run` request's paths, builds the RSpec CLI
-    # args, and delegates to the platform-appropriate process strategy
-    # (fork on Linux, spawn on macOS, or a guarded fork on macOS when the
-    # project opts in via .coatepec.yml).
+    # Validates a `rails_spec_run` request's paths, picks the RSpec or
+    # Minitest adapter from their shape, builds the CLI args, and delegates
+    # to the platform-appropriate process strategy (fork on Linux, and a
+    # guarded fork on macOS unless the project opts out via .coatepec.yml,
+    # which selects a fresh spawn per call).
     class Runner
       DEFAULT_TIMEOUT = 120
 
@@ -16,16 +17,37 @@ module Coatepec
         @rails_runtime = rails_runtime
       end
 
-      def run(paths:, example: nil, seed: nil, fail_fast: false, timeout_seconds: DEFAULT_TIMEOUT)
-        require_rspec!
-        selectors = @path_policy.validate!(paths)
-        args = build_args(selectors, example, seed, fail_fast)
+      def run(paths:, example: nil, seed: nil, fail_fast: false, timeout_seconds: DEFAULT_TIMEOUT,
+              include_passing: false, include_stdout: "failures")
+        validated = @path_policy.validate!(paths)
+        adapter = adapter_for(validated[:framework])
+        adapter.require_framework!
+        args = adapter.build_args(validated[:selectors], example, seed, fail_fast)
 
-        strategy_class.new(@project_root, project: @project, rails_runtime: @rails_runtime).run(args, timeout_seconds)
+        result = strategy_class
+                 .new(@project_root, adapter: adapter, project: @project, rails_runtime: @rails_runtime)
+                 .run(args, timeout_seconds, include_passing: include_passing, include_stdout: include_stdout)
+        @rails_runtime&.record_execution_mode(result[:execution_mode])
+        result
+      end
+
+      # Reported by rails_runtime_status so a caller can see which path a run will take.
+      def strategy_name
+        { ForkStrategy => "fork", GuardedForkStrategy => "guarded_fork", SpawnStrategy => "spawn" }
+          .fetch(strategy_class)
       end
 
       private
 
+      # Selector shape decides the framework (see PathPolicy); the adapter
+      # decides everything framework-specific after that.
+      def adapter_for(framework)
+        case framework
+        when :minitest then TestUnit::Adapter.new(@project_root)
+        else RSpecAdapter.new(@project_root)
+        end
+      end
+
       def strategy_class
         case RbConfig::CONFIG["host_os"]
         when /linux/ then ForkStrategy
@@ -36,27 +58,11 @@ module Coatepec
         end
       end
 
-      # Reading @project.config here means an invalid .coatepec.yml only
-      # raises :invalid_config on macOS -- the Linux branch never touches it.
-      # Accepted asymmetry: the file exists to configure this branch.
+      # Forking is the default; only an explicit `macos_fork: false` spawns. Only the macOS
+      # branch reads the file here; the MCP layer reads it on every call for `defaults`.
       def macos_strategy_class
         @project.config.macos_fork? ? GuardedForkStrategy : SpawnStrategy
       end
-
-      def require_rspec!
-        require "rspec/core"
-      rescue LoadError
-        raise Coatepec::Error.new(:unsupported_test_framework, "rspec-rails must be in the application's test group")
-      end
-
-      def build_args(selectors, example, seed, fail_fast)
-        args = selectors.dup
-        args += ["-e", example] if example
-        args += ["--seed", seed.to_s] if seed
-        args << "--fail-fast" if fail_fast
-
-        args
-      end
     end
   end
 end

data/lib/coatepec/spec/spawn_strategy.rb

@@ -2,17 +2,18 @@
 
 module Coatepec
   module Spec
-    # Runs RSpec in a freshly `Process.spawn`ed `bundle exec rspec` (macOS
-    # and any platform without a working fork): slower per run since Rails
-    # boots from scratch, but avoids fork-safety pitfalls.
+    # Runs the test framework in a freshly `Process.spawn`ed process --
+    # `bundle exec rspec`, or the Minitest child entry -- (macOS and any
+    # platform without a working fork): slower per run since Rails boots
+    # from scratch, but avoids fork-safety pitfalls.
     class SpawnStrategy < ProcessStrategy
       private
 
-      def start(full_args, out_w, err_w)
-        Process.spawn(
-          { "RAILS_ENV" => "test" }, "bundle", "exec", "rspec", *full_args,
-          chdir: @project_root, out: out_w, err: err_w, pgroup: true
-        )
+      def execution_mode = "spawn"
+
+      def start(full_args, out_w, err_w, json_path)
+        env, argv = @adapter.spawn_command(full_args, json_path)
+        Process.spawn(env, *argv, chdir: @project_root, out: out_w, err: err_w, pgroup: true)
       end
     end
   end

data/lib/coatepec/test_unit/adapter.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module TestUnit
+    # The Minitest half of the framework adapter contract (see
+    # Spec::RSpecAdapter for the RSpec half and the method-by-method
+    # contract). Everything Rails-/Minitest-specific about running a
+    # `test/` selection lives here; the process strategies stay
+    # framework-agnostic.
+    #
+    # The parent (warm worker) only ever calls require_framework!,
+    # build_args, json_args and spawn_command. run_in_process runs in the
+    # child -- a fork of the worker on Linux, or the fresh process
+    # child_entry.rb starts on macOS -- and is the single place Minitest is
+    # configured, so fork and spawn behave identically.
+    class Adapter
+      CHILD_ENTRY = File.expand_path("child_entry.rb", __dir__)
+      JSON_PATH_ENV = "COATEPEC_MINITEST_JSON"
+
+      def initialize(project_root)
+        @project_root = project_root
+      end
+
+      def framework
+        :minitest
+      end
+
+      # Only `minitest` itself here, never rails/test_help: that file runs
+      # ActiveRecord::Migration.maintain_test_schema! and installs fixture
+      # hooks at require time, which belongs in the child (mirroring how the
+      # RSpec path requires rspec/core in the parent and lets rails_helper
+      # load rspec/rails in the child). Practically unreachable -- activesupport
+      # depends on minitest -- but kept as the symmetric guard.
+      def require_framework!
+        require "minitest"
+      rescue LoadError
+        raise Coatepec::Error.new(:unsupported_test_framework, "minitest must be in the application's bundle")
+      end
+
+      # Selectors first, then flags: run_in_process relies on that order to
+      # hand Rails::TestUnit::Runner.load_tests the selectors alone.
+      def build_args(selectors, example, seed, fail_fast)
+        args = selectors.dup
+        args += [name_filter_flag, "/#{Regexp.escape(example)}/"] if example
+        args += ["--seed", seed.to_s] if seed
+        args << "--fail-fast" if fail_fast
+
+        args
+      end
+
+      # Minitest's option parser raises on unknown flags, so the JSON path
+      # reaches the reporter in-process (fork) or via the environment (spawn).
+      def json_args(_json_path)
+        []
+      end
+
+      def spawn_command(full_args, json_path)
+        [{ "RAILS_ENV" => "test", JSON_PATH_ENV => json_path }, ["bundle", "exec", "ruby", CHILD_ENTRY, *full_args]]
+      end
+
+      # Runs in the child. Rails is already booted (config/environment) by
+      # the caller. Returns the process exit status.
+      def run_in_process(full_args, json_path)
+        prepare_child_environment
+        configure_minitest!(json_path)
+
+        ::Rails::TestUnit::Runner.load_tests(selectors_from(full_args))
+        ::Minitest.run(full_args) ? 0 : 1
+      end
+
+      private
+
+      # Minitest 6 renamed -n/--name (options[:filter]) to -i/--include
+      # (options[:include]); Rails' own plugin shims -n on 6 with a warning.
+      def name_filter_flag
+        ::Minitest::VERSION.start_with?("6") ? "-i" : "-n"
+      end
+
+      # Every validated selector starts with its root directory name, never
+      # with "-", so the flags boundary is exact.
+      def selectors_from(full_args)
+        full_args.take_while { |arg| !arg.start_with?("-") }
+      end
+
+      # PARALLEL_WORKERS must be set before any test file loads: a generated
+      # test_helper.rb calls `parallelize(workers: :number_of_processors)`
+      # at class-body time and reads the variable right then. Without it, a
+      # selection above the parallelization threshold (50 by default) forks
+      # a worker tree, each wanting its own database, under this run's one
+      # timeout budget. The load-path entry is what `rails test` itself adds
+      # (Rails::Command::TestCommand#perform) so `require "test_helper"`
+      # resolves.
+      def prepare_child_environment
+        ENV["PARALLEL_WORKERS"] = "1"
+        test_dir = File.join(@project_root, "test")
+        $LOAD_PATH.unshift(test_dir) unless $LOAD_PATH.include?(test_dir)
+      end
+
+      # rails/test_help pulls in active_support/testing/autorun, which on
+      # Minitest 6 already does `Minitest.load :rails`; the guarded call here
+      # covers a test_help that does not, without registering Rails' plugin
+      # twice (init_plugins would then run plugin_rails_init twice). Minitest
+      # 5's #run globs installed gems' plugins itself, so nothing is needed.
+      def configure_minitest!(json_path)
+        require "rails/test_help"
+        ::Minitest.load(:rails) if ::Minitest.respond_to?(:load) && !::Minitest.extensions.include?("rails")
+        require_relative "line_filtering"
+        LineFiltering.install!
+        register_reporter(json_path)
+      end
+
+      # Minitest's plugin hook: Minitest.run builds its reporter, then calls
+      # plugin_<name>_init for every registered extension with the reporter
+      # exposed as Minitest.reporter. Rails' own init only swaps the
+      # Summary/Progress reporters, so ours survives it.
+      #
+      # Ours goes to the *front* of the composite, not the end: Rails'
+      # TestUnitReporter implements --fail-fast by raising Interrupt from
+      # inside #record, and CompositeReporter delivers #record in list order,
+      # so a reporter behind it never sees the very failure that aborted the
+      # run -- the one result a fail-fast caller most wants reported.
+      def register_reporter(json_path)
+        require_relative "json_reporter"
+        reporter = JsonReporter.new(json_path, @project_root)
+        ::Minitest.extensions << "coatepec" unless ::Minitest.extensions.include?("coatepec")
+        ::Minitest.singleton_class.define_method(:plugin_coatepec_init) do |_options|
+          ::Minitest.reporter.reporters.unshift(reporter)
+        end
+      end
+    end
+  end
+end

data/lib/coatepec/test_unit/child_entry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Entry point for Coatepec::Spec::SpawnStrategy when the selection is
+# Minitest: `bundle exec ruby <this file> <selectors and flags>`, run from
+# the target app's root with COATEPEC_MINITEST_JSON pointing at the file
+# the JSON reporter must write. Boots the app exactly as the warm worker
+# would, then hands off to the same TestUnit::Adapter#run_in_process a
+# forked child uses, so fork and spawn configure Minitest identically.
+#
+# `bundle exec` already prepends -rbundler/setup via RUBYOPT; the explicit
+# require keeps this script correct if it is ever run without it, and
+# mirrors exe/coatepec-worker's ordering rationale (default gems must be
+# pinned by Bundler before anything else can auto-activate them).
+require "bundler/setup"
+
+$LOAD_PATH.unshift(File.expand_path("../..", __dir__))
+require "coatepec/errors"
+require "coatepec/test_unit/adapter"
+
+project_root = Dir.pwd
+require File.join(project_root, "config/environment")
+
+json_path = ENV.fetch(Coatepec::TestUnit::Adapter::JSON_PATH_ENV)
+status = Coatepec::TestUnit::Adapter.new(project_root).run_in_process(ARGV, json_path)
+$stdout.flush
+$stderr.flush
+# rails/test_help requires active_support/testing/autorun, which arms
+# Minitest.autorun's at_exit hook. A plain `exit` would therefore run the
+# whole suite a second time -- from the now option-stripped ARGV, so without
+# the seed/filter/fail-fast -- and overwrite the JSON report with that second
+# run's results. exit! skips at_exit handlers, exactly as ForkStrategy's
+# child does.
+Kernel.exit!(status)