kitchen-vagrant 2.2.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4abf5224b64f63f370ce34d71838b1aa1706a70a2a8f7285219388a977eb2bdf
-  data.tar.gz: 91b8de7ff382f07694a1df7d7714237e77be14be7b4faa854b509e97dc31fc31
+  metadata.gz: eb41469b88a11508fe064bd6b04389da5cdb617ef027e5a633f47a1c88478be0
+  data.tar.gz: d4e9d511d64c4bff5a21121f2e2e9bcad8cd453efe7981de9a2c87597bb5f758
 SHA512:
-  metadata.gz: 3b42b779d8c9726c89ef893e2ae4289775ae488eb26d2ff52d3a909e3efd97296db770801908a41beb73df703a9e065dae8836b82ce0fab7fc4dc9eb968ba02d
-  data.tar.gz: 4656b6f370e4c2233ad1c0fb8ab933599829599348fab18461f8ab487df9e180b040267e3fcd01124453b7c223f84792e276b7f8140ecf4e8c03377d62e79eb7
+  metadata.gz: 8332c2ee9115ff0c69684420767948b5ad620051b4e99b5ac763e4b08636fe81caa4678ba9ccbbb5e662f6495438499c1fdafd9e7c127738c4219980d61f09f2
+  data.tar.gz: 163808d47b023456f260985e2180e7de2f46d0b0201729d828bb328d2f16d89c381b4eb7b43191e42a8d4645c14b2e39d6e630409e0847dd01c0e4497235af73

data/lib/kitchen/driver/helpers.rb

@@ -15,30 +15,90 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "base64" unless defined?(Base64)
 require "mixlib/shellout" unless defined?(Mixlib::ShellOut)
 require "fileutils" unless defined?(FileUtils)
 require "json" unless defined?(JSON)
 
 module Kitchen
+  # Test Kitchen driver plugins.
   module Driver
+    # Helpers for talking to Hyper-V from the Vagrant driver.
+    #
+    # Hyper-V has no command line interface of its own, so everything here
+    # funnels through PowerShell: a script is wrapped so that it dot-sources
+    # the bundled `support/hyperv.ps1`, base64-encoded for `-EncodedCommand`
+    # (which sidesteps all shell quoting problems), executed, and its JSON
+    # output parsed back into Ruby.
+    #
+    # The module expects to be mixed into a {Kitchen::Configurable} that also
+    # provides {Kitchen::Logging}, which the Vagrant driver does.
+    #
+    # @author Steven Murawski <smurawski@chef.io>
     module HypervHelpers
+      # Encodes a PowerShell script for `powershell.exe -EncodedCommand`.
+      #
+      # PowerShell requires UTF-16LE, not UTF-8, and strict (unwrapped) base64.
+      #
+      # @param script [String] a PowerShell script
+      # @return [String] the script as single-line base64
+      # @api private
       def encode_command(script)
         encoded_script = script.encode("UTF-16LE", "UTF-8")
         Base64.strict_encode64(encoded_script)
       end
 
+      # The processor architecture Windows reports for this process.
+      #
+      # `PROCESSOR_ARCHITEW6432` is only set for a 32-bit process running under
+      # WOW64, where it holds the *machine's* architecture while
+      # `PROCESSOR_ARCHITECTURE` holds the emulated one -- so it wins when
+      # present.
+      #
+      # @return [String,nil] e.g. `"AMD64"`, or nil off Windows
+      # @api private
+      def os_architecture
+        ENV["PROCESSOR_ARCHITEW6432"] || ENV["PROCESSOR_ARCHITECTURE"]
+      end
+
+      # Whether the running Ruby is a 64-bit build, determined from the size of
+      # a packed pointer.
+      #
+      # @return [true,false] whether this Ruby is 64-bit
+      # @api private
+      def ruby_64bit?
+        ["foo"].pack("p").size != 4
+      end
+
+      # Whether both the OS and the running Ruby are 64-bit.
+      #
+      # @return [true,false] whether this is a 64-bit Ruby on a 64-bit Windows
+      # @api private
       def is_64bit?
-        os_arch = ENV["PROCESSOR_ARCHITEW6432"] || ENV["PROCESSOR_ARCHITECTURE"]
-        ruby_arch = ["foo"].pack("p").size == 4 ? 32 : 64
-        os_arch == "AMD64" && ruby_arch == 64
+        os_architecture == "AMD64" && ruby_64bit?
       end
 
+      # Whether both the OS and the running Ruby are 32-bit.
+      #
+      # Note this is deliberately *not* the negation of {#is_64bit?}: a 32-bit
+      # Ruby on a 64-bit Windows (the WOW64 case) is neither.
+      #
+      # @return [true,false] whether this is a 32-bit Ruby on a 32-bit Windows
+      # @api private
       def is_32bit?
-        os_arch = ENV["PROCESSOR_ARCHITEW6432"] || ENV["PROCESSOR_ARCHITECTURE"]
-        ruby_arch = ["foo"].pack("p").size == 4 ? 32 : 64
-        os_arch != "AMD64" && ruby_arch == 32
+        os_architecture != "AMD64" && !ruby_64bit?
       end
 
+      # Path to a PowerShell that matches the machine's architecture.
+      #
+      # When Ruby and Windows agree on bitness, the real `System32` PowerShell
+      # is correct. When they disagree -- a 32-bit Ruby on 64-bit Windows --
+      # `System32` would be silently redirected by WOW64 to the 32-bit
+      # PowerShell, which cannot see the Hyper-V cmdlets; `Sysnative` is the
+      # alias that reaches the 64-bit one.
+      #
+      # @return [String] absolute path to powershell.exe
+      # @api private
       def powershell_64_bit
         if is_64bit? || is_32bit?
           'c:\windows\system32\windowspowershell\v1.0\powershell.exe'
@@ -47,6 +107,12 @@ module Kitchen
         end
       end
 
+      # Builds a full `powershell.exe` command line that dot-sources the gem's
+      # `support/hyperv.ps1` helper functions and then runs `script`.
+      #
+      # @param script [String] a PowerShell script
+      # @return [String] a command line ready to hand to a shell
+      # @api private
       def wrap_command(script)
         base_script_path = File.join(File.dirname(__FILE__), "/../../../support/hyperv.ps1")
         debug("Loading functions from #{base_script_path}")
@@ -60,6 +126,7 @@ module Kitchen
       #
       # @param cmd [String] command to run locally
       # @param options [Hash] options hash
+      # @return [Hash,nil] the parsed JSON the script emitted, if any
       # @see Kitchen::ShellOut.run_command
       # @api private
       def run_ps(cmd, options = {})
@@ -70,6 +137,13 @@ module Kitchen
         execute_command wrapped_command, options
       end
 
+      # Runs a command locally and parses its output as JSON.
+      #
+      # @param cmd [String] command to run locally
+      # @param options [Hash] options passed through to `Mixlib::ShellOut`
+      # @return [Hash,Array,nil] the parsed output, or nil if there was none
+      # @raise [RuntimeError] if the command exited non-zero
+      # @api private
       def execute_command(cmd, options = {})
         debug("#Local Command BEGIN (#{cmd})")
         sh = Mixlib::ShellOut.new(cmd, options)
@@ -81,10 +155,21 @@ module Kitchen
         JSON.parse(stdout) if stdout.length > 2
       end
 
+      # Strips the interactive prompt lines PowerShell interleaves with real
+      # output, which would otherwise make the result unparseable as JSON.
+      #
+      # @param stdout [String] raw standard output
+      # @return [String] output with `PS ...>` lines removed
+      # @api private
       def sanitize_stdout(stdout)
         stdout.split("\n").select { |s| !s.start_with?("PS") }.join("\n")
       end
 
+      # Asks Hyper-V for the virtual switch new VMs should be attached to.
+      #
+      # @return [String] the name of the switch
+      # @raise [RuntimeError] if no usable switch could be determined
+      # @api private
       def hyperv_switch
         default_switch_object = run_ps hyperv_default_switch_ps
         if default_switch_object.nil? ||
@@ -96,6 +181,11 @@ module Kitchen
         default_switch_object["Name"]
       end
 
+      # The PowerShell that {#hyperv_switch} runs. Honours
+      # `KITCHEN_HYPERV_SWITCH`; without it, `Get-DefaultVMSwitch` picks one.
+      #
+      # @return [String] a PowerShell script emitting a JSON switch object
+      # @api private
       def hyperv_default_switch_ps
         <<-VMSWITCH
           Get-DefaultVMSwitch #{ENV["KITCHEN_HYPERV_SWITCH"]} | ConvertTo-Json
@@ -104,6 +194,11 @@ module Kitchen
 
       private
 
+      # Renders a Ruby Array as a PowerShell array literal.
+      #
+      # @param list [Array,nil] the values to render
+      # @return [String] e.g. `@("a", "b")`, or `@()` when empty
+      # @api private
       def ruby_array_to_ps_array(list)
         return "@()" if list.nil? || list.empty?
 

data/lib/kitchen/driver/vagrant.rb

@@ -18,6 +18,13 @@
 require "erb" unless defined?(Erb)
 require "fileutils" unless defined?(FileUtils)
 require "rubygems/version"
+# :nocov:
+# Chefstyle's Chef/Ruby/UnlessDefinedRequire wants this guard, but the guard's
+# other branch is unreachable: kitchen has already loaded "time" by here. The
+# repo enforces a branch-coverage floor, so exclude the line rather than let
+# the two rules fight.
+require "time" unless defined?(Time.now.iso8601)
+# :nocov:
 
 require "kitchen"
 require_relative "vagrant_version"
@@ -31,6 +38,10 @@ module Kitchen
     #
     # @author Fletcher Nichol <fnichol@nichol.ca>
     class Vagrant < Kitchen::Driver::Base
+      # Machine states Vagrant reports for a box that is up and reachable.
+      #
+      # @return [Array<String>]
+      LIVE_STATES = %w{running}.freeze
 
       include ShellOut
       include Kitchen::Driver::HypervHelpers
@@ -127,6 +138,11 @@ module Kitchen
         info("Vagrant instance #{instance.to_str} created.")
       end
 
+      # The box this Instance should use when the user has not named one.
+      #
+      # Platforms the Bento project builds are mapped onto their `bento/`
+      # box; anything else is assumed to name a box directly.
+      #
       # @return [String,nil] the Vagrant box for this Instance
       def default_box
         if bento_box?(instance.platform.name)
@@ -136,6 +152,11 @@ module Kitchen
         end
       end
 
+      # The box URL this Instance should use when the user has not named one.
+      #
+      # Always nil: modern Vagrant resolves boxes through Vagrant Cloud, so an
+      # explicit URL is only needed for privately hosted boxes.
+      #
       # @return [String,nil] the Vagrant box URL for this Instance
       def default_box_url
         nil
@@ -157,6 +178,12 @@ module Kitchen
         state.delete(:hostname)
       end
 
+      # Packages a created instance into a redistributable `.box` file in the
+      # current working directory, then destroys the instance.
+      #
+      # @param state [Hash] mutable instance state
+      # @raise [UserError] if the instance has not been created
+      # @raise [ActionFailed] if the action could not be completed
       def package(state)
         if state[:hostname].nil?
           raise UserError, "Vagrant instance not created!"
@@ -172,6 +199,27 @@ module Kitchen
         destroy(state)
       end
 
+      # Reports what Vagrant currently thinks of the machine.
+      #
+      # @param state [Hash] instance state naming the machine
+      # @return [Hash] a Test Kitchen status hash, or the base implementation's
+      #   answer when there is nothing to ask Vagrant about
+      def status(state)
+        return super unless state[:hostname]
+
+        machine_state = vagrant_machine_state
+        return super unless machine_state
+
+        {
+          live: LIVE_STATES.include?(machine_state),
+          state: machine_state,
+          source: "driver",
+          resource_id: instance.name,
+          message: "Vagrant reports the machine as #{machine_state}",
+          checked_at: Time.now.utc.iso8601,
+        }
+      end
+
       # A lifecycle method that should be invoked when the object is about
       # ready to be used. A reference to an Instance is required as
       # configuration dependant data may be access through an Instance. This
@@ -209,6 +257,23 @@ module Kitchen
         end
       end
 
+      # Checks the host-side things a Vagrant run needs, reporting rather than
+      # raising so `kitchen doctor` can list every problem at once.
+      #
+      # {#verify_dependencies} already raises on an old or absent Vagrant, but
+      # it only runs on the actions that need it. This repeats the version rule
+      # as a report and adds the file and folder checks that nothing validates
+      # today.
+      #
+      # @param state [Hash] mutable instance and driver state
+      # @return [Boolean] true when a problem was reported
+      def doctor(state) # rubocop:disable Lint/UnusedMethodArgument
+        problems = vagrant_problems + template_problems + synced_folder_problems
+
+        problems.each { |problem| warn(problem) }
+        !problems.empty?
+      end
+
       # @return [TrueClass,FalseClass] whether or not the transport's name
       #   implies a WinRM-based transport
       # @api private
@@ -216,9 +281,11 @@ module Kitchen
         instance.transport.name.downcase =~ /win_?rm/
       end
 
-      # Setting up the `cache_directory` to store omnibus packages in cache
-      # and share a local folder to that directory so that we don't pull them
-      # down every single time
+      # The guest-side directory that the host's omnibus package cache should
+      # be shared into, so repeated converges do not re-download packages.
+      #
+      # @return [String,false] the guest path, or false if caching does not
+      #   apply to this box and provider combination
       def cache_directory
         if enable_cache?
           config[:cache_directory]
@@ -229,7 +296,10 @@ module Kitchen
 
       protected
 
+      # Where users are pointed when Vagrant is missing or too old.
       WEBSITE = "https://developer.hashicorp.com/vagrant/install".freeze
+
+      # The oldest Vagrant this driver supports.
       MIN_VER = "2.4.0".freeze
 
       class << self
@@ -238,10 +308,11 @@ module Kitchen
         attr_accessor :vagrant_version
       end
 
-      # Retuns whether or not a platform name could have a correcponding Bento
+      # Returns whether or not a platform name could have a corresponding Bento
       # box produced by the Bento project.
       # (https://github.com/chef/bento).
       #
+      # @param name [String] a Test Kitchen platform name
       # @return [TrueClass,FalseClass] whether or not the name could be a Bento
       #   box
       # @api private
@@ -250,8 +321,13 @@ module Kitchen
       end
 
       # Returns whether or not the we expect the box to work with shared folders
-      # by matching against a whitelist of bento boxes
-      # @return [TrueClass,FalseClass] whether or not the box shoud work with
+      # by matching against a whitelist of bento boxes.
+      #
+      # Providers without usable shared folder support are excluded outright,
+      # whatever the box.
+      #
+      # @param box [String] the Vagrant box name
+      # @return [TrueClass,FalseClass] whether or not the box should work with
       #   shared folders
       # @api private
       def safe_share?(box)
@@ -261,7 +337,11 @@ module Kitchen
       end
 
       # Return true if we found the criteria to enable the cache_directory
-      # functionality
+      # functionality.
+      #
+      # @return [TrueClass,FalseClass] whether the package cache should be
+      #   shared into the guest
+      # @api private
       def enable_cache?
         return false unless config[:cache_directory]
         return true if safe_share?(config[:box])
@@ -271,8 +351,10 @@ module Kitchen
         false
       end
 
-      # Renders and writes out a Vagrantfile dedicated to this instance.
+      # Renders and writes out a Vagrantfile dedicated to this instance. A
+      # no-op if this action has already written one.
       #
+      # @return [void]
       # @api private
       def create_vagrantfile
         return if @vagrantfile_created
@@ -288,6 +370,7 @@ module Kitchen
       # Logs the Vagrantfile's contents to the debug log level.
       #
       # @param vagrantfile [String] path to the Vagrantfile
+      # @return [void]
       # @api private
       def debug_vagrantfile(vagrantfile)
         return unless logger.debug?
@@ -297,8 +380,10 @@ module Kitchen
         debug("------------")
       end
 
-      # Setup path for CA cert
+      # Expands `:box_download_ca_cert` relative to the kitchen root, so a
+      # `.kitchen.yml` can refer to a cert alongside itself.
       #
+      # @return [void]
       # @api private
       def finalize_ca_cert!
         unless config[:box_download_ca_cert].nil?
@@ -308,9 +393,14 @@ module Kitchen
         end
       end
 
-      # Create vagrant command to update box to the latest version
+      # Replaces a truthy `:box_auto_update` with the `vagrant box update`
+      # command line that {#run_box_auto_update} should run. A falsey value is
+      # left alone so that `box_auto_update: false` stays disabled.
+      #
+      # @return [void]
+      # @api private
       def finalize_box_auto_update!
-        return if config[:box_auto_update].nil?
+        return unless config[:box_auto_update]
 
         cmd = "#{config[:vagrant_binary]} box update --box #{config[:box]}"
         cmd += " --architecture #{config[:box_arch]}" if config[:box_arch]
@@ -319,9 +409,14 @@ module Kitchen
         config[:box_auto_update] = cmd
       end
 
-      # Create vagrant command to remove older versions of the box
+      # Replaces a truthy `:box_auto_prune` with the `vagrant box prune`
+      # command line that {#run_box_auto_prune} should run. A falsey value is
+      # left alone so that `box_auto_prune: false` stays disabled.
+      #
+      # @return [void]
+      # @api private
       def finalize_box_auto_prune!
-        return if config[:box_auto_prune].nil?
+        return unless config[:box_auto_prune]
 
         cmd = "#{config[:vagrant_binary]} box prune --force --keep-active-boxes --name #{config[:box]}"
         cmd += " --provider #{config[:provider]}" if config[:provider]
@@ -357,8 +452,26 @@ module Kitchen
         end
       end
 
-      # Replaces an `%{instance_name}` tokens in the synced folder items.
+      # Formats network options for use in the Vagrantfile.
+      #
+      # Accepts either a Hash (rendered as Ruby keyword syntax) or a String
+      # (passed through as-is, which is what {#finalize_network!} produces).
+      #
+      # @param options [Hash,String,#to_s] network options
+      # @return [String] formatted options string for Vagrantfile
+      # @api private
+      def format_network_options(options)
+        return options if options.is_a?(String)
+        return options.map { |k, v| "#{k}: #{v.inspect}" }.join(", ") if options.is_a?(Hash)
+
+        options.to_s
+      end
+
+      # Normalises every `:synced_folders` entry: expands the host path
+      # against the kitchen root, substitutes `%{instance_name}` tokens, and
+      # formats the options for the template.
       #
+      # @return [void]
       # @api private
       def finalize_synced_folders!
         config[:synced_folders] = config[:synced_folders]
@@ -375,9 +488,11 @@ module Kitchen
         add_extra_synced_folders!
       end
 
-      # We would like to sync a local folder to the instance so we can
-      # take advantage of the packages that we might have in cache,
-      # therefore we wont download a package we already have
+      # Shares the host's omnibus package cache into the guest so a converge
+      # does not re-download packages it already has.
+      #
+      # @return [void]
+      # @api private
       def add_extra_synced_folders!
         if cache_directory
           FileUtils.mkdir_p(local_kitchen_cache)
@@ -389,9 +504,12 @@ module Kitchen
         end
       end
 
-      # Truncates the length of `:vm_hostname` to 12 characters for
-      # Windows-based operating systems.
+      # Truncates an over-long `:vm_hostname` on Windows guests, where the
+      # NetBIOS name is capped at 15 characters. The final character of the
+      # original is kept as a suffix so that names which differ only in their
+      # tail do not collapse onto each other.
       #
+      # @return [void]
       # @api private
       def finalize_vm_hostname!
         string = config[:vm_hostname]
@@ -401,17 +519,20 @@ module Kitchen
         end
       end
 
-      # If Hyper-V and no network configuration
-      # check KITCHEN_HYPERV_SWITCH and fallback to helper method
-      # to select the best switch
+      # Gives a Hyper-V instance a default `public_network` bridged onto the
+      # switch named by `KITCHEN_HYPERV_SWITCH`, or whichever switch
+      # {HypervHelpers#hyperv_switch} considers best. Instances that already
+      # configure a network, and every other provider, are left alone.
+      #
+      # @return [void]
       # @api private
       def finalize_network!
-        if config[:provider] == "hyperv" && config[:network].empty?
-          config[:network].push([
-            "public_network",
-            "bridge: \"#{hyperv_switch}\"",
-            ])
-        end
+        return unless config[:provider] == "hyperv" && config[:network].empty?
+
+        # Deliberately a new Array rather than a push: `default_config` hands
+        # every instance the *same* Array object, so mutating it in place would
+        # leak this network into every other instance in the process.
+        config[:network] = [["public_network", %{bridge: "#{hyperv_switch}"}]]
       end
 
       # Renders the Vagrantfile ERb template.
@@ -431,6 +552,90 @@ module Kitchen
         end
       end
 
+      # Asks Vagrant for the machine state.
+      #
+      # `--machine-readable` is parsed rather than the human output because the
+      # human wording is localised and reworded between Vagrant releases, while
+      # the machine format is a stable comma-separated
+      # `timestamp,target,type,data` and the `state` row carries the raw value
+      # (`running`, `poweroff`, `not_created`, ...).
+      #
+      # @return [String, nil] the machine state, or nil when there is no
+      #   Vagrantfile to ask about, the command fails, or no state row is found
+      # @api private
+      def vagrant_machine_state
+        return nil unless File.exist?(File.join(vagrant_root, "Vagrantfile"))
+
+        output = run("#{config[:vagrant_binary]} status --machine-readable")
+        parse_machine_state(output)
+      rescue ::StandardError => e
+        debug("Could not read the Vagrant machine state: #{e.message}")
+        nil
+      end
+
+      # Pulls the `state` row out of Vagrant's machine-readable output.
+      #
+      # @param output [String] the raw `--machine-readable` output
+      # @return [String, nil] the state value, or nil when no state row is present
+      # @api private
+      def parse_machine_state(output)
+        output.to_s.each_line do |line|
+          fields = line.strip.split(",")
+          return fields[3] if fields[2] == "state" && fields[3]
+        end
+        nil
+      end
+
+      # Vagrant itself: present, and new enough.
+      #
+      # @return [Array<String>] a problem, or an empty array
+      def vagrant_problems
+        found = vagrant_version
+        if Gem::Version.new(found) < Gem::Version.new(MIN_VER.dup)
+          return ["Vagrant #{found} is older than the #{MIN_VER} this driver " \
+                  "needs. Upgrade from #{WEBSITE}."]
+        end
+
+        info("vagrant #{found} found at #{config[:vagrant_binary]}")
+        []
+      rescue UserError => e
+        [e.message]
+      rescue ::StandardError => e
+        ["Could not run #{config[:vagrant_binary]} --version: #{e.message}"]
+      end
+
+      # The Vagrantfile template, and any extra Vagrantfiles spliced into it.
+      # Both are `expand_path_for` settings, so a wrong relative path becomes
+      # an absolute path that simply is not there.
+      #
+      # @return [Array<String>] one problem per missing file
+      def template_problems
+        problems = []
+
+        unless File.exist?(config[:vagrantfile_erb].to_s)
+          problems << "vagrantfile_erb #{config[:vagrantfile_erb]} does not exist."
+        end
+
+        Array(config[:vagrantfiles]).each do |path|
+          problems << "vagrantfiles entry #{path} does not exist." unless File.exist?(path.to_s)
+        end
+
+        problems
+      end
+
+      # Host paths in `synced_folders`. Vagrant creates a missing host path
+      # silently for some providers and fails for others, so an absent source
+      # is worth naming either way.
+      #
+      # @return [Array<String>] one problem per missing host path
+      def synced_folder_problems
+        Array(config[:synced_folders]).filter_map do |source, destination, _options|
+          next if source.nil? || File.exist?(source.to_s)
+
+          "synced_folders source #{source} (mounted at #{destination}) does not exist."
+        end
+      end
+
       # Convenience method to run a command locally.
       #
       # @param cmd [String] command to run locally
@@ -454,6 +659,9 @@ module Kitchen
       # any bundler environment should we detect one.  Otherwise, subcommands
       # will inherit our bundled environment.
       # @see https://github.com/test-kitchen/kitchen-vagrant/issues/190
+      # @param cmd [String] command to run locally
+      # @param options [Hash] options hash
+      # @return [String] the standard output of the command
       # @see Kitchen::ShellOut#run_command
       # rubocop:disable Metrics/CyclomaticComplexity
       def run_command(cmd, options = {})
@@ -479,10 +687,10 @@ module Kitchen
         # is passed to a windows process with a PATH, Vagrant's batch installer
         # (https://github.com/mitchellh/vagrant-installers/blob/master/substrate
         # /modules/vagrant_installer/templates/windows_vagrant.bat.erb)
-        # does not efectively prepend the vagrant ruby path in a persistent
+        # does not effectively prepend the vagrant ruby path in a persistent
         # manner which causes vagrant to use the same ruby as test-kitchen and
         # then the environment is essentially corrupted leading to many errors
-        # and dispair
+        # and despair
         unless windows_host?
           gem_home = ENV["GEM_HOME"]
           if gem_home && (env["PATH"] || ENV["PATH"])
@@ -496,8 +704,11 @@ module Kitchen
       end
       # rubocop:enable Metrics/CyclomaticComplexity
 
-      # Check if a newer version of the vagrant box is available and warn the user
+      # Check if a newer version of the vagrant box is available and warn the
+      # user. Skipped when `:box_auto_update` is on, since the update happens
+      # regardless.
       #
+      # @return [void]
       # @api private
       def check_box_outdated
         # Skip if box_auto_update is enabled (they'll get the update anyway)
@@ -519,6 +730,7 @@ module Kitchen
       # Parse vagrant box outdated output and warn if a new version is available
       #
       # @param output [String] output from vagrant box outdated command
+      # @return [void]
       # @api private
       def warn_if_outdated(output)
         return unless box_is_outdated?(output)
@@ -549,15 +761,20 @@ module Kitchen
           output_downcase.include?("newer version of the box")
       end
 
+      # Characters that may legitimately appear inside a box version. Vagrant
+      # quotes versions in prose ("version '202401.31.0'.") and separates them
+      # with punctuation in tabular output ("Current: 1.2.3, Latest: 4.5.6"),
+      # so the version has to end on an alphanumeric to avoid swallowing the
+      # trailing quote, comma or full stop.
+      VERSION_PATTERN = /v?(\w[\w.+-]*\w|\w)/
+
       # Extract current version from vagrant box outdated output
       #
       # @param output [String] output from vagrant box outdated command
       # @return [String, nil] current version or nil if not found
       # @api private
       def extract_current_version(output)
-        match = output.match(/Current:\s+v?(\S+)/i) ||
-          output.match(/currently have version\s+'?v?([^'.\s]+)/i)
-        match ? match[1] : nil
+        extract_version(output, /Current:\s+/i, /currently have version\s+'?/i)
       end
 
       # Extract latest version from vagrant box outdated output
@@ -566,12 +783,32 @@ module Kitchen
       # @return [String, nil] latest version or nil if not found
       # @api private
       def extract_latest_version(output)
-        match = output.match(/Latest:\s+v?(\S+)/i) ||
-          output.match(/latest is version\s+'?v?([^'.\s]+)/i)
-        match ? match[1] : nil
+        extract_version(output, /Latest:\s+/i, /latest is version\s+'?/i)
+      end
+
+      # Finds the first version number that follows any of the given prefixes.
+      #
+      # @param output [String] output from vagrant box outdated command
+      # @param prefixes [Array<Regexp>] prefixes to look for, in priority order
+      # @return [String, nil] the version, or nil if no prefix matched
+      # @api private
+      def extract_version(output, *prefixes)
+        prefixes.each do |prefix|
+          match = output.match(/#{prefix.source}#{VERSION_PATTERN.source}/i)
+          return match[1] if match
+        end
+        nil
       end
 
-      # Tell vagrant to update vagrant box to latest version
+      # Runs the `vagrant box update` command built by
+      # {#finalize_box_auto_update!}, if any.
+      #
+      # A box that has never been downloaded cannot be updated; that specific
+      # failure is expected on a first run and is swallowed.
+      #
+      # @return [void]
+      # @raise [Kitchen::ShellOut::ShellCommandFailed] for any other failure
+      # @api private
       def run_box_auto_update
         if config[:box_auto_update]
           begin
@@ -584,15 +821,21 @@ module Kitchen
         end
       end
 
-      # Tell vagrant to remove older vagrant boxes
+      # Runs the `vagrant box prune` command built by
+      # {#finalize_box_auto_prune!}, if any.
+      #
+      # @return [void]
+      # @api private
       def run_box_auto_prune
         if config[:box_auto_prune]
           run(config[:box_auto_prune])
         end
       end
 
-      # Runs a local command before `vagrant up` has been called.
+      # Runs `:pre_create_command`, if set, from the kitchen root -- before
+      # `vagrant up`, so it can prepare anything the Vagrantfile depends on.
       #
+      # @return [void]
       # @api private
       def run_pre_create_command
         if config[:pre_create_command]
@@ -603,6 +846,8 @@ module Kitchen
       # Runs a local command without streaming the stdout to the logger.
       #
       # @param cmd [String] command to run locally
+      # @param options [Hash] options hash
+      # @return [String] the standard output of the command
       # @api private
       def run_silently(cmd, options = {})
         merged = {
@@ -613,6 +858,7 @@ module Kitchen
 
       # Runs the `vagrant up` command locally.
       #
+      # @return [void]
       # @api private
       def run_vagrant_up
         cmd = "#{config[:vagrant_binary]} up"
@@ -621,9 +867,11 @@ module Kitchen
         run(cmd)
       end
 
-      # Updates any state after creation.
+      # Records the connection details Vagrant reports for the new machine
+      # into the instance state, so the transport can reach it.
       #
       # @param state [Hash] mutable instance state
+      # @return [void]
       # @api private
       def update_state(state)
         hash = winrm_transport? ? vagrant_config(:winrm) : vagrant_config(:ssh)

data/lib/kitchen/driver/vagrant_version.rb

@@ -17,9 +17,10 @@
 
 module Kitchen
 
+  # Test Kitchen driver plugins.
   module Driver
 
     # Version string for Vagrant Kitchen driver
-    VAGRANT_VERSION = "2.2.1".freeze
+    VAGRANT_VERSION = "2.4.0".freeze
   end
 end

data/templates/Vagrantfile.erb

@@ -85,7 +85,7 @@ Vagrant.configure("2") do |c|
 <% end %>
 
 <% Array(config[:network]).each do |opts| %>
-  c.vm.network(:<%= opts[0] %>, <%= opts[1].map { |k, v| "#{k}: #{v.inspect}" }.join(', ') %>)
+  c.vm.network(:<%= opts[0] %>, <%= format_network_options(opts[1]) %>)
 <% end %>
 
   c.vm.synced_folder ".", "/vagrant", disabled: true
@@ -97,6 +97,8 @@ Vagrant.configure("2") do |c|
 <% case config[:provider]
    when "virtualbox" %>
     p.name = "kitchen-<%= File.basename(config[:kitchen_root]) %>-<%= instance.name %>-<%= SecureRandom.uuid %>"
+<% when "tart" %>
+    p.name = "kitchen-<%= File.basename(config[:kitchen_root]) %>-<%= instance.name %>"
 <% end %>
 
 <% case config[:provider]

metadata

@@ -1,22 +1,36 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-vagrant
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.4.0
 platform: ruby
 authors:
 - Fletcher Nichol
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-22 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: test-kitchen
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '3.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'
@@ -26,7 +40,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '3.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'
@@ -55,7 +69,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="