mutation_tester 1.4.2 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c743765bd0adb455bf1162627a35cb5b3232d45cfb83dca91ab139248a3acac1
-  data.tar.gz: 71eb3f98c61271896c6c4cc2e3b9b69c62fee77d50b3d94c0237b0dac9eefd53
+  metadata.gz: 95884456f3cb22f463001c227181cbb9250fe09c3e94eec4039cc0fac54c6e18
+  data.tar.gz: 984f636d787af8f79d4d117684f57a69bdd48347651ecbb6421468d2730522e8
 SHA512:
-  metadata.gz: 3fac687f4fd5496daced6e16cf30e3dc39a0816fc5be7fe9f37caae4a05d3e088bdf1f80ee5b23f72610741d767cd410de81c6fcec09b4456d2936549f32266c
-  data.tar.gz: 13842db8fe228decfe6d3e165e5f80ea3c18af549e09051a3b12342f1ff3251ea5f81f8d375d1f0bdc5e76b6320f101ce791900016b8054630a3e0c2e14f3227
+  metadata.gz: 890a83603e65df88fcad21e62a27faa57c8540c403d8ca92ae218b9471d04471272f01f409f7c32cff8bf567feda042167c75b7be83962315c06976626ec142b
+  data.tar.gz: 943bb88ba38f80d37c78ecde8f91567000e952a4b68209cfac9d94aa336129b8ce2bdec2eaac4759fa328fb334daa79fd34a8a7a587d069804fcf1d4c907c943

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [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/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/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

@@ -238,6 +238,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
@@ -198,7 +198,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 +210,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 +265,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/version.rb

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

data/readme.md

@@ -210,7 +210,8 @@ mutation_test [OPTIONS] --glob 'lib/**/*.rb'
 | `--fail-fast` | Stop the run at the first surviving mutant and finish with a failing status. Works in single-file mode and with `--glob`. |
 | `--timeout-factor N` | Per-mutant timeout budget as `N` times the measured baseline test run, never below 5 s (default: 5, must be > 0). Ignored when `config.timeout` is set explicitly, which keeps a fixed budget. See [Configuration](#configuration). |
 | `--timeout-policy MODE` | Scoring policy for timed-out mutants: `killed` (default) counts a timeout as a kill; `separate` keeps timeouts out of the score entirely (`killed / (killed + survived)`) and reports them only as their own category in the console, JSON and HTML reports. |
-| `--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. You provision the databases (e.g. `rake parallel:prepare`). Not supported by the `in_memory` runner (it falls back to `fork`). See [Making parallelism work with Rails](#making-parallelism-work-with-rails). |
+| `--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. You provision the databases (e.g. `rake parallel:prepare`). A parallel `in_memory` run falls back to `fork` unless `--after-fork` is also given; a serial run (`-p 1`) decides mutants in a shadow workspace instead of mutating the checkout in place. See [Making parallelism work with Rails](#making-parallelism-work-with-rails). |
+| `--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. With `--worker-env` set, this keeps the `in_memory` runner available in parallel runs. A clone whose after-fork file raises is dropped with a stderr warning and its worker falls back to file-based execution. See [Making parallelism work with Rails](#making-parallelism-work-with-rails). |
 | `--strict-equality` | Enable the opt-in strict-equality probes (`==` → `eql?` and `==` → `equal?`). Default off; expect noise on code that does not distinguish numeric types or object identity. See [Strict Equality Mutations](docs/mutation-types.md#strict-equality-mutations-opt-in). |
 | `-h, --help` | Show help message. |
 | `-v, --version` | Show version. |
@@ -510,6 +511,19 @@ MutationTester.configure do |config|
   # setting a specific mode forces it. See the Execution model section below.
   config.runner = :auto
 
+  # Per-worker database isolation (parallel_tests TEST_ENV_NUMBER convention).
+  # Set to an environment variable name to give each parallel worker a distinct
+  # value before it boots its test environment. Equivalent to the --worker-env
+  # CLI flag. See Making parallelism work with Rails below.
+  # config.worker_env_var = "TEST_ENV_NUMBER"
+
+  # 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 database connection. Keeps the in_memory
+  # runner available in parallel worker-env runs. Equivalent to the
+  # --after-fork CLI flag.
+  # config.after_fork_file = "db/mutation_after_fork.rb"
+
   # Two-phase test selection (RSpec only): fast-kill on a matching example
   # subset, always confirmed by the full file before a mutant is reported as
   # survived. Set to false to always run the full file. See Execution model.
@@ -651,10 +665,41 @@ bundle exec mutation_test --glob 'app/models/**/*.rb' \
 
 `MUTATION_TESTER_WORKER_ENV=TEST_ENV_NUMBER` is equivalent to passing the flag.
 
-**Runner support.** `--worker-env` works with the `fork` and `spawn` runners, where each mutant boots its test
-environment freshly and picks up the variable. The `in_memory` runner clones a single preloaded worker that has already
-connected to one database, so it cannot isolate a per-worker database; when `--worker-env` is set the runner selection
-skips `in_memory` and uses `fork`, announcing the reason on stderr.
+**Runner support.** `--worker-env` works with the `fork` and `spawn` runners out of the box, because each mutant boots
+its test environment freshly and picks up the variable. The `in_memory` runner clones a single preloaded worker that
+has already connected to one database, so setting the variable alone cannot re-point an existing connection; in a
+parallel run without `--after-fork` the runner selection therefore skips `in_memory` and uses `fork`, announcing the
+reason on stderr. A serial run (`-p 1`) has only one worker and stays in memory.
+
+**Keeping the in-memory runner with `--after-fork`.** Pass `--after-fork FILE` (or
+`MUTATION_TESTER_AFTER_FORK=FILE`) to keep the `in_memory` runner in parallel worker-env runs. Each preloaded clone
+then receives its per-worker value of the `--worker-env` variable and loads `FILE` right after forking, and that file
+is where your app re-establishes its per-worker state. For a Rails app with a `TEST_ENV_NUMBER`-keyed `database.yml`
+that usually means reconnecting ActiveRecord:
+
+```ruby
+# db/mutation_after_fork.rb
+ActiveRecord::Base.establish_connection(
+  ActiveRecord::Base.configurations
+    .configs_for(env_name: 'test', name: 'primary')
+    .configuration_hash
+    .merge(database: "myapp_test#{ENV['TEST_ENV_NUMBER']}")
+)
+```
+
+```bash
+bundle exec mutation_test app/models/user.rb spec/models/user_spec.rb \
+  -p 4 --worker-env TEST_ENV_NUMBER --after-fork db/mutation_after_fork.rb
+```
+
+The file runs once per clone, inside the clone only (never in the primary preloaded worker or in your shell process).
+If it raises, the clone reports the error on stderr and is dropped, and its worker decides its share of mutants through
+the file-based path; if the file does not exist, the whole run falls back to file-based execution with a warning.
+
+**Serial runs never mutate your checkout.** With `--worker-env` set, a `-p 1` run on the file-based runners decides
+each mutant in a shadow workspace instead of writing mutants into the real source file, so a killed process cannot
+leave a mutated file behind. (Without `--worker-env`, a serial file-based run still uses in-place mutation with a
+`.mutation_backup` file that the next run restores automatically.)
 
 **Still simplest without a parallel database setup:** if you have not provisioned per-worker databases, keep Rails
 model runs on serial `-p 1`. `--worker-env` is only useful once the databases exist.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mutation_tester
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 1.5.0
 platform: ruby
 authors:
 - Kamil Dzierbicki
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-05 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parallel