appraisal2 3.1.4 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbe46d02bf329c467f1a1174498ac52b428836db70f3b481d9895ab72eae831f
-  data.tar.gz: 478f076b882e497da7a709180c9a27bf70c9c90a0e34d3dad12a4281b49cd520
+  metadata.gz: 3ea29429e7d6b15deb35e182590258883e32ef6fecfe015c4d39d932fd4bcf96
+  data.tar.gz: 11bafabfd834fd35254e0777feaa1180be8c6f08b6ea89e92e3615cfefc2b392
 SHA512:
-  metadata.gz: bad0a5d468f7d046063b315d70f74f43e751c21a4b2316d599d6904f1e3f77b783f2bafd7d4cef9946fcb3e5757a359b1b6af431b9e99681042064d82d13d8c0
-  data.tar.gz: 2ee5da066917eaf2862328952292e79b76483befd7fcad754945dec312fa988e77813dd93e2ad7812a27489239e95da13be1159f7e068468c0c699c560398550
+  metadata.gz: 3289da2711ffa8539b1a34aba8346209e077d3fd86cf1bdb1b726bea7093bc8ae5e2f4bc62c8aa68e03783266f6c77bdb743a2dc550a4fb14fb3744714943957
+  data.tar.gz: bf38ac3a50e473895fb994b5e0e2abbcc437e18b1ec9a2f46acb232bfefce945eddbc5201c7cb1ef2ac739ed556ff3e1b1c1da739c32b3525f23bfff01c58a98

data/CHANGELOG.md

@@ -30,6 +30,53 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.2.0] - 2026-07-18
+
+- TAG: [v3.2.0][3.2.0t]
+- COVERAGE: 91.00% -- 910/1000 lines in 29 files
+- BRANCH COVERAGE: 77.54% -- 183/236 branches in 29 files
+- 42.33% documented
+
+### Added
+
+- `appraisal generate`, `install`, `update`, `generate-install`, and
+  `generate-update` can now process appraisals in parallel with
+  `--appraisal-jobs` / `-n`, or `APPRAISAL_JOBS`. Appraisal-level
+  parallelism defaults to 2 workers; use `-n 1` to run serially. Bundler older
+  than 2.1 falls back to serial processing.
+
+### Changed
+
+- Full dependency updates now run `bundle update --all` to avoid Bundler's
+  deprecated implicit full-update form.
+- Acceptance specs now opt into expensive dummy-gem and bundle fixture setup
+  through metadata, and reuse a per-worker cached default fixture stage.
+- Generated CI workflows now cache `.rspec_status` and pass it to
+  `kettle-test` so `turbo_tests2` can balance workers with historical example
+  timings.
+- `generate-install` and `generate-update` now reuse the parsed Appraisals set
+  for their generate and install/update phases.
+
+- kettle-jem-template-20260716-001 - Shim gemspec manifests now include
+  `LICENSE.md` instead of nonexistent `LICENSE.txt`.
+- kettle-jem-template-20260716-002 - Generated gemspec manifests now ship fewer
+  repository-only files by default to reduce downstream distro packaging churn.
+
+### Fixed
+
+- Appraisal command execution now checks whether the `bundle` executable can
+  boot before falling back to RubyGems spec probing and Bundler installation,
+  preserving TruffleRuby's engine-shipped Bundler in isolated subprocesses.
+- Acceptance fixture Bundler selection now detects TruffleRuby's shipped
+  Bundler without reusing a newer Bundler activated by the appraised suite.
+- Acceptance fixture binstubs now pin the selected Bundler version before
+  loading generated `bin/bundle` handoff code.
+- Bundler-backed appraisal installs now set `BUNDLE_JOBS` explicitly so the
+  configured Appraisal job count also controls Bundler's installer worker
+  count in subprocesses.
+- JRuby and TruffleRuby workflows now correctly skip ordinary pull request
+  branches unless the branch targets `jruby/`, `truffleruby/`, or `engines/`.
+
 ## [3.1.4] - 2026-07-01
 
 - TAG: [v3.1.4][3.1.4t]
@@ -429,7 +476,9 @@ Please file a bug if you notice a violation of semantic versioning.
   - code coverage tracked with Coveralls, QLTY.sh, and the kettle-soup-cover gem
   - other minor fixes and improvements
 
-[Unreleased]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.4...HEAD
+[Unreleased]: https://github.com/appraisal-rb/appraisal2/compare/v3.2.0...HEAD
+[3.2.0]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.4...v3.2.0
+[3.2.0t]: https://github.com/appraisal-rb/appraisal2/releases/tag/v3.2.0
 [3.1.4]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.3...v3.1.4
 [3.1.4t]: https://github.com/appraisal-rb/appraisal2/releases/tag/v3.1.4
 [3.1.3]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.2...v3.1.3

data/README.md

@@ -259,6 +259,21 @@ Use the command that matches the lifecycle you want:
 | `generate-install` | Yes | Yes, via install | First setup, or after intentional Appraisals changes |
 | `generate-update` | Yes | Yes, via update | Regenerate gemfiles, then update dependency locks |
 
+Appraisal2 can process appraisals in parallel with `--appraisal-jobs` / `-n`,
+or with `APPRAISAL_JOBS` when no CLI value is provided. `generate`,
+`generate-install`, and `generate-update` use this for generation. `install`,
+`update`, `generate-install`, and `generate-update` use it to fan out dependency
+resolution across appraisals. External commands run across all appraisals, such
+as `bundle exec appraisal rake test`, use `APPRAISAL_JOBS`. Appraisal-level
+parallelism defaults to 2 workers; use `-n 1` to run serially. When Appraisal2
+is running under Bundler older than 2.1, Appraisal2 falls back to serial
+processing because those Bundler versions do not provide the modern environment
+helpers used to isolate parallel Bundler subprocesses.
+
+Install commands keep `--jobs` / `-j` for the selected gem manager. With
+Bundler, `-j` controls `bundle install --jobs`, while `-n` controls how many
+appraisal gemfiles Appraisal2 processes at the same time.
+
 The deprecated rake task `rake appraisal:install` now delegates to `appraisal generate-install`, preserving its historical generate-and-install behavior while the CLI commands remain explicit.
 
 ### Command Options
@@ -270,12 +285,27 @@ Built-in dependency commands support the following options:
 | Option | Description |
 |--------|-------------|
 | `--gem-manager`, `-g` | Gem manager to use: `bundler` (default) or `ore`; applies to `install`, `update`, `generate-install`, and `generate-update` |
-| `--jobs`, `-j` | Install gems in parallel using the given number of workers; applies to `install` and `generate-install` |
+| `--appraisal-jobs`, `-n` | Process appraisals in parallel for `generate`, `install`, `update`, `generate-install`, and `generate-update` (default: 2; use `-n 1` for serial execution; Bundler < 2.1 falls back to serial processing) |
+| `--jobs`, `-j` | Pass a parallel job count to the selected gem manager; applies to `install` and `generate-install` |
 | `--retry` | Retry network and git requests that have failed; applies to `install` and `generate-install` (default: 1) |
 | `--without` | A space-separated list of groups to skip during installation; applies to `install` and `generate-install` |
 | `--full-index` | Run bundle install with the full-index argument; applies to `install` and `generate-install` |
 | `--path` | Install gems in the specified directory; applies to `install` and `generate-install` |
 
+```bash
+# Process two appraisals at a time, using the default Appraisal worker count
+bundle exec appraisal generate-install
+
+# Process four appraisals at a time
+bundle exec appraisal generate-install -n 4
+
+# Process two appraisals at a time, and give each Bundler install four jobs
+bundle exec appraisal generate-install -n 2 -j 4
+
+# Run Appraisal serially when parallel appraisal processing is not desired
+bundle exec appraisal generate-install -n 1
+```
+
 ### Using Commands with Named Appraisals
 
 #### Using Appraisal's built-in commands with named appraisals
@@ -752,7 +782,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.916-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.000-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/appraisal-rb/appraisal2/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/appraisal/appraisal.rb

@@ -94,7 +94,7 @@ module Appraisal
     end
 
     def gemfile_path
-      gemfile_root.mkdir unless gemfile_root.exist?
+      FileUtils.mkdir_p(gemfile_root)
 
       gemfile_root.join(gemfile_name).to_s
     end

data/lib/appraisal/cli.rb

@@ -2,17 +2,27 @@
 
 require "thor"
 require "fileutils"
+require "thread"
 
 module Appraisal
   class CLI < Thor
+    MINIMUM_PARALLEL_BUNDLER_VERSION = Gem::Version.new("2.1.0")
+
     default_task :install
     map ["-v", "--version"] => "version"
+    map "generate-install" => "generate_install"
+    map "generate-update" => "generate_update"
 
     class_option "gem-manager",
       :aliases => "-g",
       :type => :string,
       :default => "bundler",
       :desc => "Gem manager to use for install/update (bundler or ore)"
+    class_option "appraisal-jobs",
+      :aliases => "-n",
+      :type => :numeric,
+      :banner => "SIZE",
+      :desc => "Process appraisals in parallel using the given number of workers."
 
     class << self
       # Override help command to print out usage
@@ -59,7 +69,7 @@ module Appraisal
       :type => :numeric,
       :default => 1,
       :banner => "SIZE",
-      :desc => "Install gems in parallel using the given number of workers."
+      :desc => "Pass the given parallel job count to the selected gem manager."
     method_option "retry",
       :type => :numeric,
       :default => 1,
@@ -78,11 +88,7 @@ module Appraisal
         "Bundler will remember this option."
 
     def install
-      install_options = options.to_h
-      AppraisalFile.each do |appraisal|
-        appraisal.install(install_options)
-        appraisal.relativize
-      end
+      install_appraisals(appraisals, install_options, appraisal_jobs(options))
     end
 
     desc "generate-install", "Generate gemfiles, then resolve and install dependencies for each appraisal"
@@ -91,7 +97,7 @@ module Appraisal
       :type => :numeric,
       :default => 1,
       :banner => "SIZE",
-      :desc => "Install gems in parallel using the given number of workers."
+      :desc => "Pass the given parallel job count to the selected gem manager."
     method_option "retry",
       :type => :numeric,
       :default => 1,
@@ -109,15 +115,14 @@ module Appraisal
       :desc => "Install gems in the specified directory. " \
         "Bundler will remember this option."
     def generate_install
-      invoke(:generate, [], {})
-      invoke(:install, [], options.to_h)
+      appraisal_list = appraisals
+      generate_appraisals(appraisal_list, appraisal_jobs(options))
+      install_appraisals(appraisal_list, install_options, appraisal_jobs(options))
     end
 
     desc "generate", "Generate a gemfile for each appraisal"
     def generate
-      AppraisalFile.each do |appraisal|
-        appraisal.write_gemfile
-      end
+      generate_appraisals(appraisals, appraisal_jobs(options))
     end
 
     desc "clean", "Remove all generated gemfiles and lockfiles from gemfiles folder"
@@ -127,17 +132,14 @@ module Appraisal
 
     desc "update [LIST_OF_GEMS]", "Update dependencies for each generated appraisal gemfile"
     def update(*gems)
-      gem_manager = options["gem-manager"] || options[:gem_manager]
-      update_options = gem_manager ? {:gem_manager => gem_manager} : {}
-      AppraisalFile.each do |appraisal|
-        appraisal.update(gems, update_options)
-      end
+      update_appraisals(appraisals, gems, update_options, appraisal_jobs(options))
     end
 
     desc "generate-update [LIST_OF_GEMS]", "Generate gemfiles, then update dependencies for each appraisal"
     def generate_update(*gems)
-      invoke(:generate, [], {})
-      update(*gems)
+      appraisal_list = appraisals
+      generate_appraisals(appraisal_list, appraisal_jobs(options))
+      update_appraisals(appraisal_list, gems, update_options, appraisal_jobs(options))
     end
 
     desc "list", "List the names of the defined appraisals"
@@ -152,7 +154,99 @@ module Appraisal
 
     private
 
+    def appraisals
+      AppraisalFile.new.appraisals
+    end
+
+    def generate_appraisals(appraisal_list, jobs)
+      each_appraisal(appraisal_list, jobs) do |appraisal|
+        appraisal.write_gemfile
+      end
+    end
+
+    def install_appraisals(appraisal_list, install_options, jobs)
+      each_appraisal(appraisal_list, jobs) do |appraisal|
+        appraisal.install(install_options.dup)
+        appraisal.relativize
+      end
+    end
+
+    def update_appraisals(appraisal_list, gems, update_options, jobs)
+      each_appraisal(appraisal_list, jobs) do |appraisal|
+        appraisal.update(gems, update_options.dup)
+      end
+    end
+
+    def each_appraisal(appraisal_list, jobs)
+      jobs = worker_count(jobs, appraisal_list.length)
+      return appraisal_list.each { |appraisal| yield(appraisal) } if jobs <= 1
+
+      queue = Queue.new
+      errors = []
+      mutex = Mutex.new
+
+      appraisal_list.each { |appraisal| queue << appraisal }
+      jobs.times { queue << nil }
+
+      # rubocop:disable ThreadSafety/NewThread
+      threads = Array.new(jobs) do
+        Thread.new do
+          while (appraisal = queue.pop)
+            begin
+              yield(appraisal)
+            rescue Exception => error # rubocop:disable Lint/RescueException
+              mutex.synchronize { errors << error }
+            end
+          end
+        end
+      end
+      # rubocop:enable ThreadSafety/NewThread
+      threads.each(&:join)
+
+      raise errors.first unless errors.empty?
+    end
+
+    def worker_count(jobs, item_count)
+      jobs = jobs.to_i
+      jobs = 1 if jobs < 1
+      jobs = 1 unless parallel_appraisals_supported?
+      return jobs if item_count.zero?
+
+      [jobs, item_count].min
+    end
+
+    def parallel_appraisals_supported?
+      # Parallel install/update workers depend on Appraisal::Command being able
+      # to build independent Bundler subprocess environments. Bundler 2.1 is the
+      # floor for the modern original_env/unbundled_env API split that replaced
+      # clean_env, so older Bundler versions keep the historical serial path.
+      bundler_version = Gem::Specification.find_all_by_name("bundler").map(&:version).max
+      return false unless bundler_version
+
+      bundler_version >= MINIMUM_PARALLEL_BUNDLER_VERSION
+    end
+
+    def appraisal_jobs(command_options)
+      command_options["appraisal-jobs"] || command_options[:appraisal_jobs] || ENV["APPRAISAL_JOBS"] || 2
+    end
+
+    def install_options
+      options.to_h.reject { |key, _value| key.to_s == "appraisal-jobs" }
+    end
+
+    def update_options
+      gem_manager = options["gem-manager"] || options[:gem_manager]
+      gem_manager ? {:gem_manager => gem_manager} : {}
+    end
+
     def method_missing(name, *args)
+      case name.to_s
+      when "generate-install"
+        return generate_install
+      when "generate-update"
+        return generate_update(*args)
+      end
+
       matching_appraisal = AppraisalFile.new.appraisals.detect do |appraisal|
         appraisal.name == name.to_s
       end
@@ -213,7 +307,7 @@ module Appraisal
           Command.new(actual_args, :gemfile => matching_appraisal.gemfile_path).run
         end
       else
-        AppraisalFile.each do |appraisal|
+        each_appraisal(AppraisalFile.new.appraisals, appraisal_jobs(options)) do |appraisal|
           Command.new(ARGV, :gemfile => appraisal.gemfile_path).run
         end
       end
@@ -240,6 +334,17 @@ module Appraisal
           options[:jobs] = Regexp.last_match(1).to_i
         when /^-j(\d+)$/
           options[:jobs] = Regexp.last_match(1).to_i
+        when /^-j$/
+          options[:jobs] = args[index + 1].to_i
+          skip_next = true
+        when /^--appraisal-jobs=\d+$/
+          nil
+        when /^--appraisal-jobs$/
+          skip_next = true
+        when /^-n\d+$/
+          nil
+        when /^-n$/
+          skip_next = true
         when /^--retry=(\d+)$/
           options[:retry] = Regexp.last_match(1).to_i
         when /^--without=(.+)$/
@@ -271,6 +376,10 @@ module Appraisal
           # Next arg should be the value
           options[:gem_manager] = args[index + 1]
           skip_next = true
+        when /^--appraisal-jobs$/
+          skip_next = true
+        when /^-n$/
+          skip_next = true
         when /^-/
           # Other options are not gems, but we don't handle them all here
           # For now, just skip them to be safe if they start with -

data/lib/appraisal/command.rb

@@ -8,7 +8,9 @@ module Appraisal
     attr_reader :command, :env, :gemfile
 
     # BUNDLE_* environment variables that must be preserved for proper bundler operation
-    # and test isolation. These are preserved when using with_bundler_env to ensure:
+    # and test isolation. These are preserved after starting from Bundler's
+    # unbundled environment so Appraisal can run a fresh Bundler subprocess
+    # without losing the target appraisal and isolation settings:
     # - Bundler version switching works (BUNDLE_GEMFILE)
     # - Test isolation is maintained (BUNDLE_APP_CONFIG, etc.)
     # - User settings are respected (BUNDLE_PATH, BUNDLE_USER_CACHE, etc.)
@@ -30,6 +32,7 @@ module Appraisal
 
     PRESERVED_RUNTIME_VARS = [
       "PATH",
+      "GEM_HOME",
       "GEM_PATH"
     ].freeze
 
@@ -44,101 +47,112 @@ module Appraisal
       run_env = test_environment.merge(env)
 
       if @skip_bundle_exec
-        execute(run_env)
+        execute(ENV.to_h, run_env)
       else
-        # For bundler version switching to work reliably, we need to preserve
-        # the appraisal Gemfile while avoiding the active parent Bundler process.
-        # However, we still need to isolate from the parent's bundler state
-        # to avoid conflicts.
-        #
-        # Solution: Use a selective environment approach instead of with_original_env,
-        # which strips all BUNDLE_* variables and breaks version switching.
-        with_bundler_env do
-          apply_run_env(run_env)
-          ensure_bundler_is_available
-          ensure_locked_bundler_is_available
-          execute(run_env)
-        end
+        clean_env = bundler_env(run_env)
+        ensure_bundler_is_available(clean_env)
+        ensure_locked_bundler_is_available(clean_env)
+        execute(clean_env, run_env)
       end
     end
 
     private
 
-    # Provide a clean environment while preserving Bundler's version switching
-    # inputs and test isolation settings.
+    # Build an Appraisal subprocess environment from Bundler's explicit env APIs.
     #
-    # The current Ruby process has bundler activated, which adds bundler/setup to RUBYOPT.
-    # When we run a subprocess, we need to remove that activation so the subprocess bundler
-    # can start fresh. However, we keep all test isolation variables intact.
-    def with_bundler_env
-      backup_env = ENV.to_h
-
-      begin
-        clean_env = if Bundler.respond_to?(:original_env)
-          Bundler.original_env.to_h
-        else
-          backup_env.to_h
-        end
-
-        # Avoid leaking a global BUNDLE_LOCKFILE into subprocesses.
-        clean_env.delete("BUNDLE_LOCKFILE")
-
-        preserved_vars = PRESERVED_BUNDLE_VARS + PRESERVED_RUNTIME_VARS
-
-        preserved_vars.each do |var|
-          clean_env[var] = backup_env[var] if backup_env[var]
-        end
-
-        # Remove bundler/setup from RUBYOPT so subprocess doesn't auto-load bundler
-        if backup_env["RUBYOPT"]
-          rubyopt = backup_env["RUBYOPT"].split(" ")
-          rubyopt.reject! { |opt| opt == "-rbundler/setup" || opt.include?("bundler/setup") }
-          clean_env["RUBYOPT"] = rubyopt.join(" ") unless rubyopt.empty?
-        end
-
-        # Remove Bundler activation markers from the subprocess environment.
-        # BUNDLE_BIN_PATH pins the already-active Bundler executable, so keeping
-        # it would bypass the BUNDLED WITH version selected below.
-        clean_env.delete("BUNDLE_BIN_PATH")
-        clean_env.delete("BUNDLER_SETUP")
-        clean_env.delete("BUNDLER_VERSION")
-
-        ENV.replace(clean_env)
-
-        yield
-      ensure
-        ENV.replace(backup_env)
+    # Bundler.clean_env / Bundler.with_clean_env are removed. Bundler now exposes
+    # three related but distinct choices:
+    #
+    # - Bundler.original_env: the environment before the current Bundler activated.
+    #   This is too broad for Appraisal because unrelated original BUNDLE_* values
+    #   can leak into the appraisal subprocess.
+    # - Bundler.unbundled_env: original_env with Bundler activation removed. This
+    #   is the right base because it removes parent Bundler state, RUBYOPT
+    #   bundler/setup activation, and arbitrary BUNDLE_* values.
+    # - Bundler.with_unbundled_env: the block form of unbundled_env. Appraisal
+    #   needs a Hash to pass to Kernel.system and must re-add selected variables,
+    #   so the block helper is the wrong shape even though its semantics are close.
+    #
+    # Starting from unbundled_env would normally remove BUNDLE_GEMFILE,
+    # BUNDLE_APP_CONFIG, and related isolation knobs. Appraisal intentionally
+    # reintroduces only the variables it owns or must preserve, then sets
+    # BUNDLE_GEMFILE and the selected Bundler version for the target subprocess.
+    def bundler_env(run_env)
+      current_env = ENV.to_h
+      clean_env = if defined?(Bundler) && Bundler.respond_to?(:unbundled_env)
+        Bundler.unbundled_env.to_h
+      elsif defined?(Bundler) && Bundler.respond_to?(:original_env)
+        Bundler.original_env.to_h
+      else
+        current_env.to_h
       end
-    end
 
-    def execute(run_env)
-      announce
+      # Avoid leaking a global BUNDLE_LOCKFILE into subprocesses.
+      clean_env["BUNDLE_LOCKFILE"] = nil
+
+      preserved_vars = PRESERVED_BUNDLE_VARS + PRESERVED_RUNTIME_VARS
 
-      ENV["BUNDLE_GEMFILE"] = gemfile
-      if (bundler_version = locked_bundler_version)
-        ENV["BUNDLER_VERSION"] = bundler_version
+      preserved_vars.each do |var|
+        clean_env[var] = current_env[var] if current_env[var]
       end
-      ENV["APPRAISAL_INITIALIZED"] = "1"
+
+      clean_env["RUBYOPT"] = current_env["RUBYOPT"] if current_env["RUBYOPT"]
+
+      # Remove bundler/setup from RUBYOPT so subprocess doesn't auto-load bundler.
+      # Bundler.original_env can also contain RUBYOPT, so strip from the final
+      # command environment rather than only from the active process env.
+      if clean_env["RUBYOPT"]
+        rubyopt = clean_env["RUBYOPT"].split(" ")
+        rubyopt.reject! { |opt| opt == "-rbundler/setup" || opt.include?("bundler/setup") }
+        clean_env["RUBYOPT"] = rubyopt.join(" ")
+        clean_env["RUBYOPT"] = nil if clean_env["RUBYOPT"].empty?
+      end
+
+      # Remove Bundler activation markers from the subprocess environment.
+      # BUNDLE_BIN_PATH pins the already-active Bundler executable, so keeping
+      # it would bypass the BUNDLED WITH version selected below.
+      clean_env["BUNDLE_BIN_PATH"] = nil
+      clean_env["BUNDLE_VERSION"] = nil
+      clean_env["BUNDLER_SETUP"] = nil
+      clean_env["BUNDLER_VERSION"] = nil
+
       run_env.each_pair do |key, value|
-        ENV[key] = value
+        clean_env[key] = value
       end
 
-      exit(1) unless Kernel.system(command_as_string)
+      clean_env
     end
 
-    def apply_run_env(run_env)
-      run_env.each_pair do |key, value|
-        ENV[key] = value
+    def execute(base_env, run_env)
+      announce
+
+      process_env = base_env.merge(run_env)
+      process_env["BUNDLE_GEMFILE"] = gemfile if gemfile
+      if (bundler_version = subprocess_bundler_version(process_env))
+        process_env["BUNDLE_VERSION"] = bundler_version
+        process_env["BUNDLER_VERSION"] = bundler_version
       end
+      process_env["APPRAISAL_INITIALIZED"] = "1"
+
+      exit(1) unless Kernel.system(process_env, command_as_string)
     end
 
-    def ensure_bundler_is_available
-      # Check if any version of bundler is available
-      return if system(%(gem list --silent -i bundler))
+    def ensure_bundler_is_available(process_env)
+      rubygems_env = rubygems_command_env(process_env)
+
+      # First ask the actual Bundler executable whether it can boot in the
+      # environment Appraisal is about to use. In CI, especially on alternate
+      # Ruby engines, Bundler may be available through the active app bundle
+      # while a manually scrubbed RubyGems spec lookup cannot see it through the
+      # current GEM_HOME/GEM_PATH.
+      return if system(process_env, "bundle -v > /dev/null 2>&1")
+
+      # Check if any version of bundler is available through RubyGems.
+      return if system(rubygems_env, bundler_available_command)
 
       puts ">> Bundler not found, attempting to install..."
       # If that fails, try to install the latest stable version
-      return if system("gem install bundler")
+      return if system(rubygems_env, "ruby --disable=gems -S gem install bundler")
 
       puts
       puts <<-ERROR.rstrip
@@ -150,14 +164,16 @@ manually.
       exit(1)
     end
 
-    def ensure_locked_bundler_is_available
+    def ensure_locked_bundler_is_available(process_env)
       locked_version = locked_bundler_version
       return unless locked_version
 
-      return if system(%(gem list --silent -i bundler -v "#{locked_version}"))
+      rubygems_env = rubygems_command_env(process_env)
+
+      return if system(rubygems_env, bundler_available_command(locked_version))
 
       puts ">> Bundler #{locked_version} not found, attempting to install..."
-      return if system("gem install bundler -v #{Shellwords.escape(locked_version)} --no-document")
+      return if system(rubygems_env, "ruby --disable=gems -S gem install bundler -v #{Shellwords.escape(locked_version)} --no-document")
 
       puts
       puts <<-ERROR.rstrip
@@ -180,6 +196,37 @@ manually.
       match && match[1]
     end
 
+    def subprocess_bundler_version(process_env)
+      # Production subprocesses pin Bundler only when the appraisal lockfile
+      # says to. Acceptance specs may provide APPRAISAL_TEST_BUNDLER_VERSION so
+      # the nested subprocesses use the same isolated Bundler selected by the
+      # harness, without changing production behavior.
+      locked_bundler_version || process_env["APPRAISAL_TEST_BUNDLER_VERSION"]
+    end
+
+    def rubygems_command_env(process_env)
+      process_env.dup.tap do |env|
+        env["BUNDLE_APP_CONFIG"] = nil
+        env["BUNDLE_BIN_PATH"] = nil
+        env["BUNDLE_GEMFILE"] = nil
+        env["BUNDLE_LOCKFILE"] = nil
+        env["BUNDLE_VERSION"] = nil
+        env["BUNDLER_SETUP"] = nil
+        env["BUNDLER_VERSION"] = nil
+        env["RUBYOPT"] = nil
+      end
+    end
+
+    def bundler_available_command(version = nil)
+      requirement = version ? ", Gem::Requirement.new(#{version.inspect})" : ""
+      code = <<-RUBY.chomp
+        require "rubygems"
+        specs = Gem::Specification.find_all_by_name("bundler"#{requirement})
+        exit(specs.empty? ? 1 : 0)
+      RUBY
+      "ruby --disable=gems -e #{Shellwords.escape(code)}"
+    end
+
     def announce
       if gemfile
         puts ">> BUNDLE_GEMFILE=#{gemfile} #{command_as_string}"
@@ -219,7 +266,7 @@ manually.
 
       {
         "GEM_HOME" => ENV["GEM_HOME"],
-        "GEM_PATH" => ""
+        "GEM_PATH" => ENV["APPRAISAL_TEST_SYSTEM_GEM_PATH"].to_s
       }
     end
   end