Class: Mutineer::Runner

Inherits:
Object
  • Object
show all
Defined in:
lib/mutineer/runner.rb

Overview

Orchestrates one mutation end-to-end: apply it textually, validate the result, select its covering test files from the coverage map, then run only those against the mutated source in an isolated child process (strategy whole-file reload via load).

The source file path is passed explicitly because Mutation carries only byte offsets, not its file. Coverage-map selection replaces a hardcoded test file: a mutation whose line no test exercises is :no_coverage (no fork); otherwise exactly the covering test files run in the child.

Constant Summary collapse

SOURCE_NEEDS_BOOT_HINT =

Extra line when a source raises NameError and the run has no boot file. require: files load after the sources, so they cannot define names the source needs while it loads (#376, #217).

"a source that needs other files loaded first takes them from " \
"`boot:` (or `--boot`), which loads before the sources; " \
"`require:` files load after them"

Class Method Summary collapse

Class Method Details

.check_boot_files!(config) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Checks that the boot file and every --require file exist, so a missing one stays a usage error (exit 2) on paths that skip the later require.

Parameters:

Raises:

  • (Errno::ENOENT) —

    when a file does not exist.



590
591
592
# File 'lib/mutineer/runner.rb', line 590

def self.check_boot_files!(config)
  [config.boot, *config.require_paths].compact.each { |f| project_file!(config.project_root, f) }
end

.ensure_rails_env(config) ⇒ Object

When --rails is on and RAILS_ENV is unset, default it to "test" (and say so) before the app boots. Otherwise it boots development and nothing is measured. An explicitly-set RAILS_ENV is always respected.



418
419
420
421
422
423
424
# File 'lib/mutineer/runner.rb', line 418

def self.ensure_rails_env(config)
  return unless config.rails
  return unless ENV["RAILS_ENV"].nil? || ENV["RAILS_ENV"].empty?

  ENV["RAILS_ENV"] = "test"
  warn "[mutineer] RAILS_ENV was unset; defaulting to 'test' for --rails."
end

.execute(config) ⇒ Array(Mutineer::AggregateResult, Hash<String, String>, Hash)

Full orchestration: resolve operators, discover subjects, build the coverage map, run every mutation, and aggregate. Returns [AggregateResult, source_map, extras], where extras is the hash JobPlan.collect_jobs returns (:legacy_ignore_matches, :id_map, :dropped_id_map, :copies, :declined, :subjects, :unmutated_subjects), plus :unscoped_mutants under --since. The CLI then reports + applies the exit code; the integration test asserts directly on the AggregateResult.

The parent process requires each source file so its classes exist; forked children inherit them, so a covering test file's own require_relative of the source is a no-op and does not clobber the mutated load (spec ยง7).

Parameters:

Returns:



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
# File 'lib/mutineer/runner.rb', line 79

def self.execute(config)
  # Rails reads PARALLEL_WORKERS when a test helper calls parallelize.
  # Set it before any boot or child spawn, then put the caller's value back.
  # The ensure below reads these. Set them before anything that can raise.
  filter_owned = false
  urls_owned = false
  previous_parallel_workers = ENV["PARALLEL_WORKERS"]
  RailsRunEnv.pin_process!
  # The CLI installs the filter first and owns it for the report that
  # follows this method. A library caller owns it for the run itself.
  # Direct writes from a fork or a subprocess then go through the pipe (#341).
  case OutputFilter.install
  when :started
    filter_owned = true
  when :failed
    raise "cannot redirect stdout and stderr for redaction"
  end
  if Redaction.extra_urls.empty?
    Redaction.extra_urls = DatabaseUrls.from_files(config.project_root)
    urls_owned = true
  end
  operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)

  # External backend: run the suite as a subprocess in the app's own runtime.
  # It does no in-process boot/require or coverage build, so branch before any
  # of that. The in-process path below is untouched.
  return execute_external(config, operator_classes) if config.test_command

  # Daemon backend: boot the app ONCE in a persistent subprocess under the
  # app's bundle and fork per mutant. Tool-side we only discover jobs + build
  # payloads (Prism), so branch before any in-process boot.
  if config.daemon
    # The daemon loads these files itself and would report a missing one as
    # a boot failure (exit 1). Check here so it stays a usage error (exit 2),
    # as it is in process.
    check_boot_files!(config)
    return DaemonBackend.execute(config, operator_classes)
  end

  # Both strategies (whole-file reload and redefine, #279) write
  # .mutineer_mutant*.rb into each source dir. Redefine falls back to the
  # system temp dir for a read-only source dir, which this sweep does not
  # reach; the OS cleans it, as in 1.x. The snippet rewrites `__dir__`,
  # `__FILE__`, and `require_relative` to the original file, so that
  # fallback does not false-kill (#339). A SIGKILL'd child skips the
  # tempfile's ensure-unlink, orphaning it. `ensure` is unreliable vs
  # SIGKILL, so the PARENT sweeps each source dir before and after the run.
  # Orphans are impossible after a normal run. The first sweep runs before
  # the boot: a file an older version left without the dot would stop
  # Zeitwerk (#253).
  dirs = JobPlan.source_dirs(config)
  JobPlan.sweep_orphans(dirs)
  # A `--since` run with no changed mutant has nothing to execute. Collect
  # and scope once before loading the app or capturing coverage so an empty
  # scope can return without paying for a full clean-suite run. Nonempty
  # scopes reuse this work after coverage capture instead of repeating source
  # discovery, parsing, and git diff.
  since_scope = nil
  if config.since
    # The empty-scope return skips the later require calls, so keep missing
    # boot and --require paths as usage errors on that path too.
    check_boot_files!(config)

    since_jobs, since_ignored, since_source_map, since_extras =
      JobPlan.collect_jobs(config, operator_classes)
    since_jobs, since_ignored, since_extras[:unscoped_mutants] =
      JobPlan.scope_since(since_jobs, since_ignored, since_source_map, config, extras: since_extras)
    if since_jobs.empty?
      return [AggregateResult.new(since_ignored), since_source_map, since_extras]
    end
    since_scope = [since_jobs, since_ignored, since_source_map, since_extras]
  end

  # Before boot and `--require`, so a `config.seed=` in those files is
  # recorded and every forked child keeps it (#282).
  prepare_rspec_seed!(config)

  # Boot mode: require the boot file ONCE so the app env (e.g. Rails) is booted
  # in the parent and inherited by every fork. Do NOT manually require the
  # sources. Under Zeitwerk a manual require of an autoloadable file raises;
  # the booted env autoloads them, and subject discovery is a static Prism
  # parse that needs nothing loaded. Standalone mode requires the sources as
  # before so their classes exist for the children to inherit.
  if config.boot
    # Under --rails an unset RAILS_ENV boots development, where the test
    # suite is not loaded. Coverage comes back empty and EVERY mutant is
    # falsely reported no_coverage (score N/A, exit 0). Default it to test.
    ensure_rails_env(config)

    # Coverage instruments only files loaded AFTER it starts. Start it BEFORE
    # the boot require so the entire app loaded during boot is instrumented;
    # forked children then measure each test's coverage delta against it.
    # An earlier run in this process leaves Coverage suspended (see below).
    # Coverage a host started is the host's: it is left running.
    require "coverage"
    own_coverage = !Coverage.running?
    case Coverage.state
    when :idle then Coverage.start(lines: true, methods: true)
    when :suspended then Coverage.resume
    end
    require_project_file(config.project_root, config.boot)
  else
    # No boot file, so each source loads here, and require: files load
    # after this loop (#217). A NameError means the source named
    # something that is not loaded yet; the hint points at boot:, which
    # loads first (#376).
    config.sources.each do |f|
      require_project_file(config.project_root, f, on_name_error: SOURCE_NEEDS_BOOT_HINT)
    end
  end
  config.require_paths.each { |f| require_project_file(config.project_root, f) }
  preload_owners(config) if config.boot && config.strategy == "redefine"

  if config.boot
    # Rails/Minitest test files do `require "test_helper"`, which needs the
    # test root on $LOAD_PATH (`bin/rails test` adds it). Prepend each test
    # file's helper root here in the parent so loading them in the fork
    # children (both coverage capture and per-mutant) resolves.
    boot_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
    JobPlan.test_load_roots(boot_tests).each { |d| $LOAD_PATH.unshift(d) unless $LOAD_PATH.include?(d) }

    # Boot mode now uses coverage selection too: capture each test's coverage
    # by forking the booted parent, then select covering tests per mutant.
    coverage_map = CoverageMap.new(
      source_paths: config.sources, test_paths: config.tests,
      cache_dir: File.expand_path(config.cache_dir, config.project_root), project_root: config.project_root,
      load_paths: config.load_paths, framework: config.framework,
      boot_path: File.expand_path(config.boot, config.project_root),
      require_paths: config.require_paths, # loaded above; here only for the cache digest
      verbose: config.verbose,
      coverage_from: config.coverage_from && File.expand_path(config.coverage_from, config.project_root),
      capture_timeout: config.capture_timeout || CoverageMap::DEFAULT_CAPTURE_TIMEOUT
    ).build_via_fork(after_fork: (config.rails ? -> { reconnect_active_record } : nil))
    # Nothing reads Coverage once the map is built (cache hit or not), so
    # stop paying for it in every mutant fork (#228).
    Coverage.suspend if own_coverage && Coverage.running?
  else
    # As in boot mode, and with lib first as `rake test` does.
    test_roots = JobPlan.test_load_roots(config.tests.map { |t| File.expand_path(t, config.project_root) })
    libs = config.load_paths.map { |p| File.expand_path(p, config.project_root) }
    $LOAD_PATH.unshift(*(libs + test_roots).uniq.reject { |d| $LOAD_PATH.include?(d) })
    # Relative, so the cache digest does not depend on the checkout path.
    rel_roots = test_roots.map { |d| Pathname(d).relative_path_from(File.expand_path(config.project_root)).to_s }
    coverage_map = CoverageMap.new(
      source_paths: config.sources, test_paths: config.tests,
      cache_dir: File.expand_path(config.cache_dir, config.project_root), project_root: config.project_root,
      load_paths: config.load_paths + rel_roots, framework: config.framework,
      require_paths: config.require_paths, verbose: config.verbose,
      capture_timeout: config.capture_timeout || CoverageMap::DEFAULT_CAPTURE_TIMEOUT
    ).build_or_load
  end
  JobPlan.abort_if_unclean!(coverage_map, framework: config.framework)

  # Collect every (subject, mutation) up front so the pool can fan them out.
  if since_scope
    jobs, ignored_results, source_map, extras = since_scope
  else
    jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
    jobs, ignored_results, extras[:unscoped_mutants] =
      JobPlan.scope_since(jobs, ignored_results, source_map, config, extras: extras)
  end

  strategy = config.strategy
  # Fail-fast must be serial: a parallel stop_when fires on the first survivor
  # by wall-clock, not input order, so the survivor set would diverge from
  # --jobs 1 (daemon already forces serial for the same reason).
  jobs_n = config.fail_fast ? 1 : config.jobs
  results =
    begin
      framework = config.framework
      stop_when = config.fail_fast ? ->(r) { r.survived? } : nil
      progress  = Progress.new(jobs.size)
      bare = WorkerPool.new(jobs_n).run(jobs, stop_when: stop_when,
                                              on_result: ->(_r) { progress.tick }) do |subject, mutation|
        run(mutation, source_file: subject.file, coverage_map: coverage_map,
            subject: subject, strategy: strategy, rails: config.rails, framework: framework,
            timeout: config.timeout || Isolation::DEFAULT_TIMEOUT, matrix: config.matrix)
      end
      # The bare Results carry only status (Subjects hold live AST nodes that
      # do not marshal); reattach subject+mutation+id in the parent, in order.
      # filter_map drops nils for jobs --fail-fast left unscheduled.
      share_tests(bare.each_with_index.filter_map do |r, i|
        r = unreported_row(r) if r && config.matrix
        r&.with(subject: jobs[i][0], mutation: jobs[i][1], id: jobs[i][2])
      end)
    ensure
      JobPlan.sweep_orphans(dirs)
    end

  [AggregateResult.new(results + ignored_results), source_map, extras]
ensure
  # A caller that set PARALLEL_WORKERS keeps that value after the run.
  RailsRunEnv.restore_process!(previous_parallel_workers)
  OutputFilter.uninstall if filter_owned
  # The CLI set its own list before this method and restores it. Clear
  # only the list this call loaded.
  Redaction.extra_urls = [] if urls_owned
end

.execute_external(config, operator_classes) ⇒ Array(Mutineer::AggregateResult, Hash<String,String>, Hash)

External backend orchestration. Runs each mutant's whole-file mutation on disk (crash-safe swap) and executes the user's --test-command as a subprocess in the app's own runtime. Serial by construction (one shared DB, no per-worker isolation yet). No coverage narrowing: every mutant runs the full --test set; the score is therefore an upper bound and not comparable to an in-process run (the CLI discloses this).

Parameters:

  • config (Mutineer::Config) —

    run configuration (test_command set).

  • operator_classes (Array<Class>) —

    resolved operators.

Returns:



301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
# File 'lib/mutineer/runner.rb', line 301

def self.execute_external(config, operator_classes)
  abs_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
  sources   = config.sources.map { |s| FileSwap.canonical_path(File.expand_path(s, config.project_root)) }
  dirs      = sources.map { |s| File.dirname(s) }.uniq

  # Own every source before healing leftovers or reading bytes for mutation.
  # A backup file alone is not ownership; flock is. Canonical paths so
  # symlink aliases of one inode share one lock, independent of cache_dir.
  FileSwap.owning(sources) do
    # Heal any file a prior hard-killed run left mutated BEFORE reading source.
    # collect_jobs computes mutation offsets/ids from the on-disk bytes, so a
    # still-mutated file would yield garbage offsets against the later-healed
    # source. Heal first, then discover jobs from the clean tree.
    FileSwap.restore_orphans(dirs)

    jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
    jobs, ignored_results, extras[:unscoped_mutants] =
      JobPlan.scope_since(jobs, ignored_results, source_map, config, extras: extras)

    # Nothing to mutate: return before the smoke check, which runs the whole
    # --test set to calibrate a timeout no mutant would use (#76).
    next [AggregateResult.new(ignored_results), source_map, extras] if jobs.empty?

    # Calibrate the per-mutant timeout from the clean run (a real suite far
    # outlasts the 10s in-process fork budget), and abort if it is not green.
    # 3x the clean run, floor 30s, ceiling 300s: a heuristic. The floor covers
    # a fast suite; the ceiling bounds a hung mutant (infinite loop) so a
    # handful cannot stall a serial run for ~45min on a slow suite.
    smoke_elapsed, check_summary, random_order = ExternalBackend.smoke_check!(config.test_command, abs_tests)
    timeout = [[smoke_elapsed * 3, 30].max, 300].min.ceil
    # #292: the summary check needs a summary line to look for. Without one
    # on the clean run, keep the exit-code rule and say what that costs.
    unless check_summary
      warn "[mutineer] the clean run of --test-command printed no Minitest or RSpec summary line " \
           "(such as \"3 runs, 3 assertions, 0 failures, 0 errors\" or \"3 examples, 0 failures\"), " \
           "so the crash check is off: an exit 1 counts as a kill even when the suite crashed " \
           "before its tests ran. Use the default Minitest or RSpec progress output to turn it on."
    end
    # #338: each mutant run picks its own order, so an order-dependent
    # suite can fail a mutant run for a reason the mutant did not cause.
    if random_order
      runner, seed = random_order
      fix = if runner == :minitest
              "set SEED=#{seed} before the mutineer command (SEED=#{seed} mutineer run ...), " \
                "not inside --test-command"
            else
              # SPEC_OPTS is read after the command line, so it would undo the fix.
              "add --order defined to the rspec command in --test-command and keep " \
                "--order rand out of SPEC_OPTS"
            end
      warn "[mutineer] the clean run of --test-command printed a #{runner == :minitest ? 'Minitest' : 'RSpec'} " \
           "seed (#{seed}) and Mutineer found no fixed seed, so each mutant run may use a new test " \
           "order and an order-dependent suite can give a false kill. To fix the order, #{fix}."
    end

    results = []
    progress = Progress.new(jobs.size)
    begin
      jobs.each do |subject, mutation, id|
        r = run_external(subject, mutation, config.test_command, abs_tests,
                         timeout: timeout, verbose: config.verbose, check_summary: check_summary)
        results << r.with(subject: subject, mutation: mutation, id: id)
        progress.tick
        break if config.fail_fast && r.survived? # stop at the first survivor
      end
    ensure
      FileSwap.restore_orphans(dirs)
    end

    [AggregateResult.new(results + ignored_results), source_map, extras]
  end
end

.fixture_transaction_open?(base) ⇒ Boolean (private)

Pure, injectable predicate: true when a transactional-fixture transaction is already open on the connection. Keys off open_transactions so it is correct whenever the transaction exists, regardless of when it opened. Any probe error degrades safe to false -> caller clears (existing behaviour).

Returns:

  • (Boolean)


669
670
671
672
673
674
# File 'lib/mutineer/runner.rb', line 669

def self.fixture_transaction_open?(base)
  pool = base.connection_pool
  pool.active_connection? && base.connection.open_transactions.positive?
rescue StandardError
  false
end

.preload_owners(config) ⇒ void

This method returns an undefined value.

Loads the class or module of every subject in the booted parent, before the boot coverage is read. Under redefine a child resolves the owner by name (Isolation.nesting_keywords), so a lazily loaded class (Zeitwerk, autoload) would run its class body there, with the original method, and that run would count as no load at all. Loading it here makes its class-body calls load lines, the same as an eager load. A constant that fails to load stays lazy.

Parameters:



402
403
404
405
406
407
408
409
410
411
412
413
# File 'lib/mutineer/runner.rb', line 402

def self.preload_owners(config)
  Project.discover(config.sources, only: config.only).each do |subject|
    next if subject.owner_unknown

    Isolation.nesting_keywords(subject.lexical_namespace)
    # The owner itself, as the child resolves it: a Class.new block owner
    # has no lexical namespace.
    Object.const_get(subject.namespace.join("::")) unless subject.namespace.empty?
  rescue StandardError, ScriptError
    nil
  end
end

.prepare_rspec_seed!(config) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Installs the RSpec seed watcher in this process when the run uses RSpec. Boot and --require files then load with the watcher on, and forks inherit the record of a seed they set. A project without rspec is left for the child to report, as before.

Parameters:



603
604
605
606
607
608
609
610
611
# File 'lib/mutineer/runner.rb', line 603

def self.prepare_rspec_seed!(config)
  return unless config.framework == "rspec"

  require "rspec/core"
  ::RSpec::Core::Runner.disable_autorun!
  TestRunners::RSpecSeed.install!
rescue LoadError
  nil
end

.project_file!(root, path) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The absolute path of a project file require can load: as given, or with .rb or the native-extension suffix.

Parameters:

  • root (String) —

    the project root.

  • path (String) —

    the path as the user gave it.

Returns:

  • (String)

Raises:

  • (Errno::ENOENT) —

    when the requested file does not exist.

  • (ArgumentError) —

    when Ruby cannot expand the path.



574
575
576
577
578
579
580
# File 'lib/mutineer/runner.rb', line 574

def self.project_file!(root, path)
  file = File.expand_path(path, root)
  suffixes = ["", ".rb", ".#{RbConfig::CONFIG.fetch('DLEXT')}"]
  raise Errno::ENOENT, path unless suffixes.any? { |suffix| File.file?("#{file}#{suffix}") }

  file
end

.reconnect_active_record ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Reconnects ActiveRecord in a forked child when available.



550
551
552
553
554
555
556
557
558
559
560
561
562
# File 'lib/mutineer/runner.rb', line 550

def self.reconnect_active_record
  return unless defined?(ActiveRecord::Base)

  base = ActiveRecord::Base
  # Clearing connections here drops an open transactional-fixture
  # transaction, so the test loses its fixture rows and fails. Skip the clear
  # when a transaction is open; otherwise clear (per-fork write-safety).
  return if fixture_transaction_open?(base)

  base.connection_handler.clear_all_connections!
rescue StandardError
  nil
end

.relative_kills(result, root) ⇒ Mutineer::Result

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Rewrites the test files of a result's Kills row relative to the project root, the form the coverage map and the report use. A result without a row comes back unchanged.

Parameters:

  • result (Mutineer::Result) —

    a mutant result.

  • root (String) —

    project root.

Returns:



511
512
513
514
515
516
517
518
519
# File 'lib/mutineer/runner.rb', line 511

def self.relative_kills(result, root)
  return result unless (kills = result.kills)

  paths = {}
  rel = lambda do |tests|
    tests.map { |file, name, id| [(paths[file] ||= ProjectPath.relative(file, root)), name, id] }.uniq.sort
  end
  result.with(kills: kills.with(killed_by: rel.call(kills.killed_by), ran: rel.call(kills.ran)))
end

.require_project_file(root, path, on_name_error: nil) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Require one project file in the tool process. A failure becomes a ProjectLoadError whose message, and each cause in its list, is redacted. The original backtrace is kept; the cause is not, because Ruby would print its raw message.

Parameters:

  • root (String) —

    the project root.

  • path (String) —

    the path as the user gave it.

  • on_name_error (String, nil) (defaults to: nil) —

    ProjectLoadError#hint when the file raises NameError. Sources pass SOURCE_NEEDS_BOOT_HINT. The boot file and require: files pass nil: those errors are not this case.

Raises:

  • (Errno::ENOENT) —

    when the requested file does not exist.

  • (ProjectLoadError) —

    when the file raises while it loads.



636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
# File 'lib/mutineer/runner.rb', line 636

def self.require_project_file(root, path, on_name_error: nil)
  # Outside the rescue: a path Ruby cannot expand (`~nosuchuser/boot.rb`)
  # stays a usage error (exit 2), not a load failure.
  file = project_file!(root, path)

  begin
    require file
  rescue StandardError, ScriptError => e
    # Every part is redacted on its own, so the message build cannot raise
    # on mixed encodings and leave the raw error as the new one's cause.
    causes = []
    cause = e.cause
    while cause
      causes << Redaction.describe(cause)
      cause = cause.cause
    end
    # The exception that escaped, not an exception it wrapped. A
    # RuntimeError whose cause is a NameError is a different failure.
    hint = on_name_error if e.is_a?(NameError)
    error = ProjectLoadError.new(
      "cannot load #{Redaction.text(path)}: #{Redaction.describe(e)}",
      causes: causes, hint: hint
    )
    error.set_backtrace(e.backtrace)
    raise error, cause: nil
  end
end

.run(mutation, source_file:, coverage_map: nil, subject: nil, strategy: "reload", timeout: Isolation::DEFAULT_TIMEOUT, rails: false, framework: "minitest", matrix: false) ⇒ Mutineer::Result

Runs a single mutation through isolation.

Parameters:

  • mutation (Mutineer::Mutation) —

    mutation to run.

  • source_file (String) —

    source file path.

  • coverage_map (Mutineer::CoverageMap, nil) (defaults to: nil) —

    coverage map.

  • subject (Mutineer::Subject, nil) (defaults to: nil) —

    subject for surgical strategy; redefine also loads each of its enclosing subjects.

  • strategy (String) (defaults to: "reload") —

    mutation strategy.

  • timeout (Integer) (defaults to: Isolation::DEFAULT_TIMEOUT) —

    child timeout in seconds.

  • rails (Boolean) (defaults to: false) —

    whether Rails reconnect handling is enabled.

  • framework (String) (defaults to: "minitest") —

    test framework name.

  • matrix (Boolean) (defaults to: false) —

    a --matrix run: run every covering test and attach the Kills row, with project-relative test files.

Returns:



440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
# File 'lib/mutineer/runner.rb', line 440

def self.run(mutation, source_file:, coverage_map: nil, subject: nil, strategy: "reload",
             timeout: Isolation::DEFAULT_TIMEOUT, rails: false, framework: "minitest", matrix: false)
  source  = Parser.read(source_file)
  mutated = mutation.apply(source)

  # Validity rule: a mutant that does not re-parse is skipped before forking.
  return Result.skipped if Parser.invalid?(mutated)

  # Coverage selection (both standalone and boot mode): a mutation on a line
  # no test exercises is :no_coverage (no fork); otherwise exactly the
  # covering test files run in the child. Shared with the daemon path so both
  # narrow identically (score parity).
  kind, payload = JobPlan.coverage_selection(source_file, mutation, subject, source, coverage_map)
  return payload if kind == :verdict
  # A :maybe mutant that cannot be placed stays no_coverage, as before #254.
  return kind == :maybe ? Result.no_coverage : Result.unplaceable if subject&.unplaceable?(strategy)

  abs_tests = payload
  # A :maybe mutant records whether the mutated expression ran (#345).
  sentinel = kind == :maybe ? ReachProbe.sentinel : nil
  reach_key = sentinel && ReachProbe.reach_key

  begin
    result = Isolation.run(timeout: timeout, channel: matrix) do |channel|
      # Forking inherits the parent's live DB connection; sharing one socket
      # across processes corrupts it. Drop it so AR reconnects per child.
      reconnect_active_record if rails
      if strategy == "redefine"
        # Load each enclosing def too: its body holds the original nested def,
        # which a call to it would define again over the mutant (#290).
        Isolation.apply_surgical(mutation, subject, source, reach_path: sentinel&.path, reach_key: reach_key)
        s = subject
        while (s = s.enclosing_subject)
          Isolation.apply_surgical(mutation, s, source, reach_path: sentinel&.path, reach_key: reach_key)
        end
      elsif subject&.reload_hook_call
        # #297: a def in a concern's hook block reaches each class that has it.
        code, hook_def = JobPlan.hook_mutant(mutated, mutation, subject, source, reach_path: sentinel&.path,
                                             reach_key: reach_key)
        Isolation.apply_whole_file(code, source_file, hook_def: hook_def)
      else
        Isolation.apply_whole_file(ReachProbe.wrap_mutation(mutated, mutation, sentinel&.path, reach_key),
                                    source_file)
      end
      # A reload can run the expression while the file loads. That is not
      # a test reaching it (#345).
      ReachProbe.forget_load(sentinel.path, reach_key) if sentinel
      if channel
        # --matrix: every covering test runs, and each outcome goes to the parent.
        TestRunners.for(framework).run(abs_tests, record_to: channel)
      else
        # One failing test already kills the mutant, so the child stops there.
        TestRunners.for(framework).run(abs_tests, stop_at_first_failure: true)
      end
    end
    result = relative_kills(result, coverage_map.project_root)
    result = JobPlan.load_verdict(result, source_file, mutation, subject, source, coverage_map)
    JobPlan.selection_verdict(kind, result, reached: ReachProbe.reached?(sentinel))
  ensure
    ReachProbe.close_sentinel(sentinel)
  end
end

.run_external(subject, mutation, command, abs_tests, timeout:, verbose:, check_summary:) ⇒ Mutineer::Result

Runs one mutant through the external backend: apply the whole-file mutation on disk, run the command, restore. An invalid (non-reparsing) mutant would fail to load (scored error, or a false killed without the summary check), so skip it tool-side (Prism, already cheap) and never write the file, preserving the skipped verdict the in-process path gives at the pre-fork check.

Parameters:

Returns:



382
383
384
385
386
387
388
389
390
# File 'lib/mutineer/runner.rb', line 382

def self.run_external(subject, mutation, command, abs_tests, timeout:, verbose:, check_summary:)
  source  = Parser.read(subject.file)
  mutated = mutation.apply(source)
  return Result.skipped if Parser.invalid?(mutated)

  FileSwap.with(subject.file, mutated) do
    ExternalBackend.run(command, abs_tests, timeout: timeout, verbose: verbose, check_summary: check_summary)
  end
end

.share_tests(results) ⇒ Array<Mutineer::Result>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Makes every Kills row refer to one shared, frozen array per test. Each row arrives with its own copy of every test it ran, and a large matrix (thousands of mutants times hundreds of tests) would otherwise hold that many copies. Results without a row come back unchanged.

A test is its file and its id. The name is display data and can differ between mutants (an RSpec example worded from its matcher reads differently under each mutant), so every row gets the name the first mutant reported, and one example stays one test.

Parameters:

Returns:



534
535
536
537
538
539
540
541
542
543
544
# File 'lib/mutineer/runner.rb', line 534

def self.share_tests(results)
  shared = {}
  share = lambda do |tests|
    tests.map { |file, name, id| shared[[file, id]] ||= [file, name, id].map { |s| -s }.freeze }.uniq.sort.freeze
  end
  results.map do |r|
    next r unless (kills = r.kills)

    r.with(kills: kills.with(killed_by: share.call(kills.killed_by), ran: share.call(kills.ran)))
  end
end

.unreported_row(result) ⇒ Mutineer::Result

A --matrix error that carries no Kills row (the worker crashed, or its result was lost) gets an empty, incomplete row: its tests never reported, so a blind test may have killed it, and the report must say so.

Parameters:

Returns:



284
285
286
287
288
# File 'lib/mutineer/runner.rb', line 284

def self.unreported_row(result)
  return result unless result.error? && result.kills.nil?

  result.with(kills: Kills.new(killed_by: [], ran: [], complete: false))
end