mutation_tester 1.4.2 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c743765bd0adb455bf1162627a35cb5b3232d45cfb83dca91ab139248a3acac1
-  data.tar.gz: 71eb3f98c61271896c6c4cc2e3b9b69c62fee77d50b3d94c0237b0dac9eefd53
+  metadata.gz: e32ba3afbad23fb7f2d04c12f197c8e7d7af50d0eb537266f76e3bd957165110
+  data.tar.gz: b27a1b44965b42cb4498daaba8d221dcf820b71fd3e61f3b94c47a71c7cad41d
 SHA512:
-  metadata.gz: 3fac687f4fd5496daced6e16cf30e3dc39a0816fc5be7fe9f37caae4a05d3e088bdf1f80ee5b23f72610741d767cd410de81c6fcec09b4456d2936549f32266c
-  data.tar.gz: 13842db8fe228decfe6d3e165e5f80ea3c18af549e09051a3b12342f1ff3251ea5f81f8d375d1f0bdc5e76b6320f101ce791900016b8054630a3e0c2e14f3227
+  metadata.gz: 4a05a309477ff66005be2371bedd4b5ce4b3622a064f2013b3b62336dbe5d43af7c0e27526eee2ab186c07d9faef5fc8e3a568fe1bdda5e428c3142af19b0165
+  data.tar.gz: 3fd04d05930cf47e0a4fb15680531586dfd9183ecd77ec3040aae3e5397ca1cd0cef2ac68ea087acf87c0acdd43dd8f3a18a40a46f05d8c5fac9a545511988f0

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [1.5.1] - 2026-08-13
+
+- Fixed load-time mutants losing per-worker database isolation in a parallel in-memory run with `--worker-env` and `--after-fork`. Mutants on load-time code (constants, class macros, `included do`) are decided file-based on purpose, but that file-based run acquires a fork-runner worker, and a worker booted inside a `Parallel` worker process inherited the parent process's value of the worker-env variable instead of the per-worker assignment: with 8 workers, every load-time mutant's test run hit the parent's database concurrently, races on shared rows failed tests unrelated to the mutant, and those failures were scored as kills. The same file could report 75% and 100% on consecutive runs with no error and no timeout in the output, while the spawn path and the pooled fork runner (which already carried the per-worker value) stayed stable. The fork execution path now passes the same per-worker env override the spawn path always used, and the worker applies it inside the forked test child before the spec loads, so every execution path resolves the same per-worker database. Reported in the field with exactly this signature: only class-macro mutants unstable, serial and fork-runner scores identical and stable.
+
+## [1.5.0] - 2026-08-08
+
+- Added `--after-fork FILE` (and `config.after_fork_file` / the `MUTATION_TESTER_AFTER_FORK` environment variable): a Ruby file loaded inside each preloaded in-memory clone right after it forks and receives its per-worker environment, so the app can re-establish per-worker state such as its ActiveRecord connection. With `--worker-env` set, this keeps the `in_memory` runner available in parallel runs instead of falling back to `fork`: each clone now receives its own per-worker value of the variable through the existing per-clone environment plumbing and runs the after-fork file once, giving in-memory execution and per-worker database isolation at the same time. Failure modes stay loud: a clone whose after-fork file raises reports the error on stderr and is dropped, its worker deciding its share of mutants file-based, and a missing after-fork file makes the whole run fall back to file-based execution with a warning. A serial in-memory run (`-p 1`) has only one worker and now stays in memory with `--worker-env` even without the hook.
+- A serial file-based run (`-p 1`) with `--worker-env` now decides each mutant in a shadow workspace instead of writing mutants into the real source file with a `.mutation_backup` alongside, so a process killed mid-run can no longer leave a mutated source file in the checkout. This combination occurs naturally when a caller uses one code path for both a parallel run and a serial re-run. Without `--worker-env` serial file-based runs keep the in-place strategy (the next run still restores a leftover backup automatically).
+
 ## [1.4.2] - 2026-08-05
 
 - Added `--spec-map 'PATTERN=>REPLACEMENT'`, a repeatable rule that builds the whole spec path from the whole source path with a regular expression, for the layouts the `{name}` template cannot express. `{name}` is the source path minus a leading `lib/`, so a template can only wrap it with a prefix and a suffix; every mapping that substitutes *inside* the path, after a variable-length prefix, was out of reach: `packs/identity/app/models/party.rb -> packs/identity/test/models/party_test.rb` (Packwerk / packs-rails), the same shape with Rails engines, and the plain Rails `app/ -> test/` rule. Because `--since` requires `--glob` and `--glob` maps through `--spec-glob`, such a layout previously lost the entire batch tier at once and had to be reimplemented in a wrapper script. The first matching rule wins and a source matching no rule falls back to `--spec-glob`, so one run can cover `app/` through a rule and `lib/` through the template. The flag works with `--glob`, a positional `FILE` list and `--staged`; a malformed rule is a usage error (exit code `2`) reported before any mutation runs.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mutation_tester (1.4.2)
+    mutation_tester (1.5.1)
       parallel (~> 1.20)
       parser (~> 3.3)
       rainbow (~> 3.0)

data/docs/execution-runners.md

@@ -134,6 +134,18 @@ no fallback is possible.
   in a fresh fork of its own clone. If a pooled worker dies mid-run, that
   worker finishes its share of mutants through the file-based path with a
   warning; the other workers stay in memory.
+- With `--worker-env` the preloaded clones would all share the primary
+  worker's already-established database connection, so a parallel run
+  (`-p N`, N > 1) skips the in-memory runner with a warning unless
+  `--after-fork FILE` is also given. With `--after-fork`, each clone
+  receives its per-worker value of the `--worker-env` variable and loads
+  `FILE` right after forking, and that file re-establishes the per-worker
+  state (typically the ActiveRecord connection), which keeps the whole run
+  in memory with per-worker database isolation. A serial run (`-p 1`) has
+  only one worker and stays in memory without any hook. A clone whose
+  after-fork file raises reports the error on stderr and is dropped, and
+  its worker falls back to the file-based path; a missing after-fork file
+  makes the whole run fall back with a warning.
 - Before any mutant runs, the runner re-applies the **unmutated** source in a
   probe child and runs the suite. If that probe fails (for example the file has
   top-level side effects that break on a second execution, or the class is

data/examples/github_actions/ai_mutation_gate.yml

@@ -17,7 +17,7 @@ jobs:
     timeout-minutes: 30
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/examples/github_actions/mutation_test.yml

@@ -30,7 +30,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/exe/mutation_test

@@ -88,10 +88,14 @@ OptionParser.new do |opts|
     options[:strict_equality] = true
   end
 
-  opts.on('--worker-env NAME', 'Set environment variable NAME to a distinct per-worker value before each parallel worker boots (parallel_tests TEST_ENV_NUMBER convention: worker 0 -> "", worker N -> N+1), so a parallel_tests-style database.yml selects a per-worker database. Provision the databases yourself (e.g. rake parallel:prepare). The in_memory runner cannot isolate a per-worker database, so this flag makes the runner fall back to fork.') do |name|
+  opts.on('--worker-env NAME', 'Set environment variable NAME to a distinct per-worker value before each parallel worker boots (parallel_tests TEST_ENV_NUMBER convention: worker 0 -> "", worker N -> N+1), so a parallel_tests-style database.yml selects a per-worker database. Provision the databases yourself (e.g. rake parallel:prepare). Without --after-fork a parallel in_memory run falls back to fork (preloaded clones share one database connection); pair it with --after-fork to keep the in_memory runner. A serial run (-p 1) decides mutants in a shadow workspace instead of mutating the checkout in place.') do |name|
     options[:worker_env] = name
   end
 
+  opts.on('--after-fork FILE', 'Ruby file loaded inside each preloaded in-memory clone right after it forks and receives its per-worker environment (see --worker-env), so the app can re-establish per-worker state such as its database connection (e.g. a file calling ActiveRecord::Base.establish_connection). With --worker-env set, this keeps the in_memory runner available in parallel runs.') do |file|
+    options[:after_fork] = file
+  end
+
   opts.on('-h', '--help', 'Show this help message') do
     puts opts
     exit
@@ -178,6 +182,7 @@ apply_configuration = lambda do
     config.timeout_factor = options[:timeout_factor] if options[:timeout_factor]
     config.timeout_policy = options[:timeout_policy] if options[:timeout_policy]
     config.worker_env_var = options[:worker_env] if options.key?(:worker_env)
+    config.after_fork_file = options[:after_fork] if options.key?(:after_fork)
     config.fail_fast = options.fetch(:fail_fast, false)
     config.mutation_types[:strict_equality] = true if options[:strict_equality]
 

data/lib/mutation_tester/configuration.rb

@@ -19,7 +19,8 @@ module MutationTester
       number <= 0 ? '' : (number + 1).to_s
     end
 
-    attr_reader :parallel_processes, :runner, :worker_env_var, :timeout, :timeout_factor, :timeout_policy
+    attr_reader :parallel_processes, :runner, :worker_env_var, :after_fork_file, :timeout, :timeout_factor,
+      :timeout_policy
 
     attr_accessor :baseline_duration,
       :baseline_timeout,
@@ -38,6 +39,7 @@ module MutationTester
       self.parallel_processes = ENV['MUTATION_TESTER_PARALLEL_PROCESSES'] || self.class.auto_parallel_processes
       self.runner = ENV['MUTATION_TESTER_RUNNER'] || :auto
       self.worker_env_var = ENV['MUTATION_TESTER_WORKER_ENV']
+      self.after_fork_file = ENV['MUTATION_TESTER_AFTER_FORK']
       @timeout = DEFAULT_TIMEOUT
       @timeout_factor = DEFAULT_TIMEOUT_FACTOR
       @timeout_policy = :killed
@@ -136,6 +138,11 @@ module MutationTester
       @worker_env_var = normalized.empty? ? nil : normalized
     end
 
+    def after_fork_file=(value)
+      normalized = value.to_s.strip
+      @after_fork_file = normalized.empty? ? nil : File.expand_path(normalized)
+    end
+
     def worker_env_assignment(index)
       return nil unless @worker_env_var
 

data/lib/mutation_tester/fork_runner/worker.rb

@@ -70,6 +70,7 @@ supervise_child = lambda do |job, out, child_body|
     rescue Errno::EACCES, Errno::EPERM
     end
     Dir.chdir(job['chdir']) if job['chdir']
+    job['env']&.each { |name, value| ENV[name] = value }
     mirror_load_path.call(job['mirror_of'], job['chdir'])
     sink = File.open(job['log'] || File::NULL, 'w')
     sink.sync = true
@@ -238,6 +239,17 @@ spawn_clone = lambda do |request, out|
     out.close
     STDIN.reopen(File::NULL)
     request['env']&.each { |name, value| ENV[name] = value }
+    if request['after_fork']
+      begin
+        load(request['after_fork'])
+      rescue ScriptError, StandardError => e
+        clone_out.puts(JSON.generate(
+          'event' => 'clone_error',
+          'message' => "the after-fork file #{request['after_fork']} raised #{e.class}: #{e.message}; this clone is unavailable"
+        ))
+        raise
+      end
+    end
     serve.call(input, clone_out)
   end
   Process.detach(child)

data/lib/mutation_tester/fork_runner.rb

@@ -39,10 +39,10 @@ module MutationTester
         refill_pool(pool_key(use_bundle_exec, framework), count, primary, env_for: env_for)
       end
 
-      def prepare_in_memory_pool(count, primary)
+      def prepare_in_memory_pool(count, primary, env_for: nil, after_fork: nil)
         return [] unless available? && primary&.ready?
 
-        refill_pool(IN_MEMORY_POOL_KEY, count, primary)
+        refill_pool(IN_MEMORY_POOL_KEY, count, primary, env_for: env_for, after_fork: after_fork)
       end
 
       def in_memory_pool_prepared?
@@ -116,13 +116,13 @@ module MutationTester
         Parallel.worker_number if defined?(Parallel) && Parallel.respond_to?(:worker_number)
       end
 
-      def refill_pool(key, count, primary, env_for: nil)
+      def refill_pool(key, count, primary, env_for: nil, after_fork: nil)
         entry = (pool[key] ||= { owner: Process.pid, runners: [] })
         entry[:runners] = entry[:runners].each_with_index.map do |runner, index|
-          runner&.ready? ? runner : primary.fork_clone(env: env_for&.call(index))
+          runner&.ready? ? runner : primary.fork_clone(env: env_for&.call(index), after_fork: after_fork)
         end
         entry[:runners].size.upto(count - 1) do |index|
-          entry[:runners] << primary.fork_clone(env: env_for&.call(index))
+          entry[:runners] << primary.fork_clone(env: env_for&.call(index), after_fork: after_fork)
         end
         entry[:runners]
       end
@@ -154,7 +154,7 @@ module MutationTester
     end
 
     def execute(spec_file, timeout: nil, chdir: nil, capture: false, args: [], stop_on_first_failure: false,
-                mirror_of: nil)
+                mirror_of: nil, env: nil)
       log = capture ? Tempfile.new(['mutation_tester_fork', '.log']) : nil
       job = {
         spec: spec_file,
@@ -163,7 +163,8 @@ module MutationTester
         log: log&.path,
         args: args,
         stop_on_first_failure: stop_on_first_failure,
-        mirror_of: mirror_of
+        mirror_of: mirror_of,
+        env: env
       }
       @job_writer.puts(JSON.generate(job))
       status = await_result(timeout)['status']
@@ -198,7 +199,7 @@ module MutationTester
       fail_worker
     end
 
-    def fork_clone(env: nil)
+    def fork_clone(env: nil, after_fork: nil)
       return nil unless ready?
       return nil unless File.respond_to?(:mkfifo)
 
@@ -210,6 +211,7 @@ module MutationTester
 
       clone_request = { 'job' => job_path, 'events' => events_path }
       clone_request['env'] = env if env
+      clone_request['after_fork'] = after_fork if after_fork
       @job_writer.puts(JSON.generate('clone' => clone_request))
       event = read_event(monotonic_time + CLONE_TIMEOUT)
       return nil unless event.is_a?(Hash) && event['event'] == 'cloned'
@@ -264,6 +266,11 @@ module MutationTester
           next
         end
 
+        if event['event'] == 'clone_error'
+          warn("[MutationTester] #{event['message']}")
+          return false
+        end
+
         return event['event'] == 'ready'
       end
     end

data/lib/mutation_tester/mutation_runner.rb

@@ -56,16 +56,17 @@ module MutationTester
       elsif in_memory_first?
         run_in_memory_series(mutations, &progress_callback)
       elsif @config.parallel_processes == 1
-        run_in_place_series(mutations, &progress_callback)
+        run_file_based_series(mutations, &progress_callback)
       else
         run_in_shadow_parallel(mutations, &progress_callback)
       end
     end
 
     def in_memory_first?
-      return false if @config.worker_env_var
+      return false unless %i[in_memory auto].include?(@config.runner)
+      return true unless @config.worker_env_var
 
-      %i[in_memory auto].include?(@config.runner)
+      @config.parallel_processes == 1 || !@config.after_fork_file.nil?
     end
 
     def run_in_memory_series(mutations, &progress_callback)
@@ -100,7 +101,12 @@ module MutationTester
       blocker = prepare_in_memory_execution
       return fall_back_to_parallel_file_based(blocker, mutations, &progress_callback) if blocker
 
-      pool = ForkRunner.prepare_in_memory_pool([@config.parallel_processes, mutations.size].min, @in_memory_runner)
+      pool = ForkRunner.prepare_in_memory_pool(
+        [@config.parallel_processes, mutations.size].min,
+        @in_memory_runner,
+        env_for: worker_env_for,
+        after_fork: @config.after_fork_file
+      )
       if pool.compact.empty?
         return fall_back_to_parallel_file_based('the preloaded worker pool could not be cloned', mutations, &progress_callback)
       end
@@ -161,6 +167,28 @@ module MutationTester
       cleanup_shadow_workspaces
     end
 
+    def run_file_based_series(mutations, &progress_callback)
+      project_root = @config.worker_env_var ? discoverable_project_root : nil
+      return run_in_place_series(mutations, &progress_callback) unless project_root
+
+      run_in_shadow_series(mutations, project_root, &progress_callback)
+    end
+
+    def run_in_shadow_series(mutations, project_root, &progress_callback)
+      warn "[MutationTester] --worker-env #{@config.worker_env_var} is set, so the serial run decides each mutant in a shadow workspace and never mutates the checkout in place."
+      shadow_run_root
+      results = []
+      mutations.each_with_index do |mutation, index|
+        result = run_single_mutation(mutation, :shadow, project_root)
+        progress_callback.call(mutation, index + 1) if progress_callback
+        results << result
+        break if stop_early?(result)
+      end
+      results
+    ensure
+      cleanup_shadow_workspaces
+    end
+
     def run_in_place_series(mutations, &progress_callback)
       write_in_place_backup
       results = []
@@ -401,6 +429,9 @@ module MutationTester
 
     def prepare_in_memory_execution
       return 'Process.fork is not supported on this platform' unless ForkRunner.available?
+      if @config.after_fork_file && !File.exist?(@config.after_fork_file)
+        return "the after-fork file #{@config.after_fork_file} does not exist"
+      end
       if InMemoryLoader.load_time_defined_guard?(@original_content)
         return 'the source file uses defined? at load time, so redefinition would silently skip the guarded code'
       end
@@ -451,7 +482,7 @@ module MutationTester
       offset_callback = progress_callback && lambda do |mutation, index|
         progress_callback.call(mutation, completed + index)
       end
-      run_in_place_series(mutations, &offset_callback)
+      run_file_based_series(mutations, &offset_callback)
     end
 
     def fall_back_to_parallel_file_based(reason, mutations, &progress_callback)
@@ -470,8 +501,9 @@ module MutationTester
     def announce_worker_env_in_memory_opt_out
       return unless @config.worker_env_var
       return unless %i[in_memory auto].include?(@config.runner)
+      return if @config.parallel_processes == 1 || @config.after_fork_file
 
-      warn "[MutationTester] --worker-env #{@config.worker_env_var} is set, so the in-memory runner is skipped (its clones share one preloaded database connection); using the fork runner for per-worker database isolation."
+      warn "[MutationTester] --worker-env #{@config.worker_env_var} is set without --after-fork, so the in-memory runner is skipped (its clones share one preloaded database connection); using the fork runner for per-worker database isolation. Pass --after-fork FILE to keep the in-memory runner and re-establish per-worker connections inside each clone."
     end
 
     def run_mutation_load_time(mutation, result, project_root)

data/lib/mutation_tester/test_command.rb

@@ -51,7 +51,8 @@ module MutationTester
             capture: capture,
             args: filter_args,
             stop_on_first_failure: @stop_on_first_failure,
-            mirror_of: mirror_of
+            mirror_of: mirror_of,
+            env: worker_env_overrides
           )
         end
       end

data/lib/mutation_tester/version.rb

@@ -1,3 +1,3 @@
 module MutationTester
-  VERSION = '1.4.2'.freeze
+  VERSION = '1.5.1'.freeze
 end