kitchen-hyperv 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94dc838a643b2a5ba1e0d64d1adee689340d7225c28e5a5f8187ab99b62ae548
-  data.tar.gz: d9dc608cd3109eff226ae49e5236cc825133b34ddde863c3838644c52d524e9f
+  metadata.gz: 5c1c78c069680ce6179d290ba250302102bd29da553842ecc3f00e7ddb4114c5
+  data.tar.gz: 05413cbc517eebed2176b0ab9a20f86e742ee2dcf14a58e8babf0a774a64fedd
 SHA512:
-  metadata.gz: 84b37991b3e5a154888e5715d5afd88896ae2ee9e349bed81404f29cc4379e77ebb731f31e452ba32196b650408999d29af6b06cce46f4ff717799c985297737
-  data.tar.gz: '049452452ea2a56b5729821df95fbb75fc0255f82cc98a23b191794c5991bdacc655b13ccf88837c3cfa6aafe04bc152e0d0a4b5ee3f8cead1dba2f04d64e07d'
+  metadata.gz: 723997d9f09f593d941e7ee46cca5a9ec19577142cb99148e7cebc6f9839395ddb06e6f681ed470522753aff12c088ea903440d186f6cd201d7f41616633331f
+  data.tar.gz: f87621dfb332510fa30f6c8fee49a4fa23186c6bf1ae9597fce4cca8467afa8e1387bc5c4a2a3931ad28a20e15475fb6755f747137688a9bd3263b944b8ac48a

data/Gemfile

@@ -1,16 +1,22 @@
 source "https://rubygems.org"
 
-gemspec
+gemspec development_group: :test
 
+# Everything needed to run `rake spec` and `rake style`. Deliberately small:
+# the unit suite fakes the Train connection, so it needs neither Hyper-V nor
+# any other Test Kitchen plugin to run on any platform.
 group :test do
+  gem "rake"
+  gem "rspec", "~> 3.13"
+end
+
+# Only needed to drive a real VM via `kitchen test` against a Hyper-V host.
+# Skip with: bundle config set --local without integration
+group :integration do
   gem "berkshelf"
-  gem "kitchen-inspec"
   gem "kitchen-dokken"
+  gem "kitchen-inspec"
   gem "kitchen-vagrant"
-  gem "rake"
-  gem "minitest", "~> 6.0", "< 6.1"
-  gem "minitest-stub-const"
-  gem "mocha", "~> 3.0"
 end
 
 group :development do
@@ -19,11 +25,10 @@ group :development do
   gem "pry-stack_explorer"
 end
 
-group :chefstyle do
-  gem "chefstyle"
-end
-
 group :docs do
   gem "yard"
 end
 
+group :cookstyle do
+  gem "cookstyle"
+end

data/Rakefile

@@ -1,24 +1,27 @@
 require "bundler/gem_tasks"
-require "kitchen/driver/hyperv_version"
 
-require "rake/testtask"
-Rake::TestTask.new(:unit) do |t|
-  t.libs.push "lib"
-  t.test_files = FileList["spec/**/*_spec.rb"]
-  t.verbose = true
-end
+begin
+  require "rspec/core/rake_task"
+
+  RSpec::Core::RakeTask.new(:spec)
 
-desc "Run all test suites"
-task test: :unit
+  desc "Run the unit tests"
+  task unit: :spec
+
+  desc "Run all test suites"
+  task test: :spec
+rescue LoadError
+  puts "rspec is not available. (sudo) gem install rspec to run the unit tests."
+end
 
 begin
-  require "chefstyle"
+  require "cookstyle/chefstyle"
   require "rubocop/rake_task"
   RuboCop::RakeTask.new(:style) do |task|
     task.options += ["--display-cop-names", "--no-color"]
   end
 rescue LoadError
-  puts "chefstyle is not available. (sudo) gem install chefstyle to do style checking."
+  puts "cookstyle/chefstyle is not available. (sudo) gem install cookstyle to do style checking."
 end
 
 desc "Run all quality tasks"
@@ -26,23 +29,37 @@ task quality: :style
 
 begin
   require "yard" unless defined?(YARD)
-  YARD::Rake::YardocTask.new
+
+  YARD::Rake::YardocTask.new(:yard) do |task|
+    task.stats_options = ["--list-undoc"]
+  end
+
+  namespace :yard do
+    desc "Report documentation coverage and list undocumented objects"
+    task :stats do
+      sh "yard stats --list-undoc"
+    end
+
+    desc "Serve the documentation at http://localhost:8808, reloading on change"
+    task :server do
+      sh "yard server --reload"
+    end
+  end
 rescue LoadError
   puts "yard is not available. (sudo) gem install yard to generate yard documentation."
 end
 
-task default: %i{test quality}
-begin
-  require "github_changelog_generator/task"
-
-  GitHubChangelogGenerator::RakeTask.new :changelog do |config|
-    config.future_release = "v#{Kitchen::Driver::HYPERV_VERSION}"
-    config.issues = false
-    config.pulls = true
-    config.user = "test-kitchen"
-    config.project = "kitchen-hyperv"
+desc "Run the PowerShell (Pester) tests for support/hyperv.ps1"
+task :pester do
+  pwsh = %w{pwsh powershell}.find do |candidate|
+    system("which #{candidate} > /dev/null 2>&1") || system("where #{candidate} > NUL 2>&1")
   end
-rescue LoadError
-  puts "github_changelog_generator is not available. " \
-    "gem install github_changelog_generator to generate changelogs"
+
+  abort "PowerShell was not found on PATH; install PowerShell 7+ to run the Pester tests." unless pwsh
+
+  sh pwsh, "-NoProfile", "-NonInteractive", "-File", File.join(__dir__, "spec", "powershell", "run_tests.ps1")
 end
+
+# `yard` is deliberately not a prerequisite of `default`: documentation coverage
+# should never be able to fail a build.
+task default: %i{test quality}

data/kitchen-hyperv.gemspec

@@ -18,7 +18,10 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 3.1"
 
+  # Required directly by the PowerShell command encoder. base64 is a bundled
+  # gem from Ruby 3.4 on, so it has to be declared rather than assumed.
+  spec.add_dependency "base64", "~> 0.2"
   spec.add_dependency "test-kitchen", ">= 1.4", "< 5"
-  spec.add_dependency "train", "~> 3.5"
-  spec.add_dependency "train-winrm", "~> 0.2"
+  spec.add_dependency "train", ">= 3.5", "< 4.0"
+  spec.add_dependency "train-winrm", ">= 0.2", "< 1.0"
 end

data/lib/kitchen/driver/hyperv.rb

@@ -28,9 +28,26 @@ require "train-winrm" unless defined?(TrainPlugins::WinRM)
 
 module Kitchen
 
+  # Test Kitchen driver plugins.
   module Driver
 
-    # Driver for Hyper-V
+    # Test Kitchen driver that builds instances as Hyper-V virtual machines.
+    #
+    # The driver never talks to Hyper-V directly. It generates PowerShell that
+    # calls the helper functions in `support/hyperv.ps1` and runs that script
+    # through a Train connection -- a local one on a Hyper-V host, or WinRM
+    # when `hyperv_server` points at a remote host.
+    #
+    # Each instance gets a differencing disk cloned from a shared parent VHD,
+    # so creating an instance costs a few seconds and very little disk.
+    #
+    # @example Minimal kitchen.yml
+    #   driver:
+    #     name: hyperv
+    #     parent_vhd_folder: C:\VHDs
+    #     parent_vhd_name: windows-2022.vhdx
+    #
+    # @see https://github.com/test-kitchen/kitchen-hyperv
     class Hyperv < Kitchen::Driver::Base
 
       kitchen_driver_api_version 2
@@ -72,6 +89,17 @@ module Kitchen
 
       include Kitchen::Driver::PowerShellScripts
 
+      # Create the virtual machine and wait until it is reachable.
+      #
+      # Runs the full bring-up in order: validate the configuration, clone the
+      # parent VHD into a differencing disk, create any additional data disks,
+      # create and start the VM, then block on the transport until the guest
+      # accepts connections.
+      #
+      # @param state [Hash] the instance state hash, updated in place with
+      #   `:id`, `:hostname` and `:vm_name`
+      # @return [void]
+      # @raise [RuntimeError] if validation fails or Hyper-V cannot create the VM
       def create(state)
         @state = state
         validate_vm_settings
@@ -86,12 +114,25 @@ module Kitchen
         info("Hyper-V instance #{instance.to_str} created.")
       end
 
+      # Destroy the virtual machine and the disks created alongside it.
+      #
+      # Safe to call repeatedly and safe to call when the VM was removed out of
+      # band: a differencing disk left behind by a partial create is cleaned up
+      # even when no VM exists.
+      #
+      # @param state [Hash] the instance state hash; `:id` is deleted from it
+      # @return [void]
       def destroy(state)
         @state = state
         if differencing_disk_exists && !vm_exists_silent
           remove_differencing_disk
         end
-        return unless vm_exists
+        unless vm_exists
+          # The VM is gone, but a stale id would make every later run believe
+          # otherwise, so clear it rather than returning with it still in place.
+          state.delete(:id)
+          return
+        end
 
         instance.transport.connection(state).close
         remove_virtual_machine
@@ -103,14 +144,24 @@ module Kitchen
 
       private
 
+      # Check the configuration before anything is created.
+      #
+      # Also resolves `vm_switch`, which requires a round trip to the host and
+      # so cannot be handled by a plain `default_config` block.
+      #
+      # @return [void]
+      # @raise [RuntimeError] if the parent VHD is missing, the startup memory
+      #   falls outside the dynamic memory range, or the VLAN id is not a valid
+      #   802.1Q id
+      # @api private
       def validate_vm_settings
         raise "Missing parent_vhd_folder" unless vhd_folder? || remote_hyperv
         raise "Missing parent_vhd_name" unless vhd? || remote_hyperv
 
         if config[:dynamic_memory]
-          startup_bytes = config[:memory_startup_bytes]
-          min = config[:dynamic_memory_min_bytes]
-          max = config[:dynamic_memory_max_bytes]
+          startup_bytes = integer_config(:memory_startup_bytes)
+          min = integer_config(:dynamic_memory_min_bytes)
+          max = integer_config(:dynamic_memory_max_bytes)
           memory_valid = startup_bytes.between?(min, max)
           warning = "memory_startup_bytes (#{startup_bytes}) must" \
                     " fall within dynamic memory range (#{min}-#{max})"
@@ -118,7 +169,7 @@ module Kitchen
         end
         config[:vm_switch] = vm_switch
         if config[:vm_vlan_id]
-          vm_vlan_id = config[:vm_vlan_id]
+          vm_vlan_id = integer_config(:vm_vlan_id)
           vm_vlan_id_min = 1
           vm_vlan_id_max = 4094
           vm_vlan_id_valid = vm_vlan_id.between?(vm_vlan_id_min, vm_vlan_id_max)
@@ -128,6 +179,10 @@ module Kitchen
         end
       end
 
+      # Clone the parent VHD into this instance's differencing disk.
+      #
+      # @return [void]
+      # @api private
       def create_new_differencing_disk
         info("Creating differencing disk for #{instance.name}.")
         run_ps new_differencing_disk_ps
@@ -135,6 +190,15 @@ module Kitchen
         set_new_vhd_size
       end
 
+      # Create each disk described by the `additional_disks` config.
+      #
+      # Records the created paths in `@additional_disk_objects` so
+      # {PowerShellScripts#new_vm_ps} can attach them to the new VM.
+      #
+      # @return [void]
+      # @raise [RuntimeError] if a disk entry has no name, or the target file
+      #   already exists
+      # @api private
       def create_additional_disks
         return if config[:additional_disks].nil?
 
@@ -154,6 +218,14 @@ module Kitchen
         end
       end
 
+      # Resolve the virtual switch to attach the VM to.
+      #
+      # With `vm_switch` unset the host picks its first switch; with it set the
+      # host confirms that switch exists.
+      #
+      # @return [String] the switch name
+      # @raise [RuntimeError] if the host reports no usable switch
+      # @api private
       def vm_switch
         default_switch_object = run_ps vm_default_switch_ps
         if default_switch_object.nil? ||
@@ -165,6 +237,11 @@ module Kitchen
         default_switch_object["Name"]
       end
 
+      # Create and start the VM, unless one already exists for this instance.
+      #
+      # @return [void]
+      # @raise [RuntimeError] if the host returns no VM
+      # @api private
       def create_virtual_machine
         return if vm_exists
 
@@ -176,18 +253,34 @@ module Kitchen
         info("Created virtual machine for #{instance.name}.")
       end
 
+      # Copy the VM's id, address and name into the instance state.
+      #
+      # @return [void]
+      # @raise [RuntimeError] if the host reports no detail for the VM
+      # @api private
       def update_state
         vm_details
+        raise "Unable to fetch details for virtual machine #{instance.name}." if @vm.nil?
+
         @state[:id] = @vm["Id"]
         @state[:hostname] = @vm["IpAddress"]
         @state[:vm_name] = @vm["Name"]
       end
 
+      # Fetch the VM's details from the host, applying a static IP first if one
+      # is configured.
+      #
+      # @return [Hash, nil] the parsed `Get-VmDetail` payload
+      # @api private
       def vm_details
         run_ps set_vm_ipaddress_ps if config[:ip_address]
         @vm = run_ps vm_details_ps
       end
 
+      # Attach the configured ISO to the VM's DVD drive.
+      #
+      # @return [void]
+      # @api private
       def mount_virtual_machine_iso
         return unless config[:iso_path]
 
@@ -196,6 +289,10 @@ module Kitchen
         info("Done mounting #{config[:iso_path]}")
       end
 
+      # Grow the disk to `resize_vhd` bytes, when configured.
+      #
+      # @return [void]
+      # @api private
       def set_new_vhd_size
         return unless config[:resize_vhd]
 
@@ -204,6 +301,11 @@ module Kitchen
         info("Resized differencing disk for #{instance.name}.")
       end
 
+      # Write the configured note onto the VM, so it is identifiable in the
+      # Hyper-V manager.
+      #
+      # @return [void]
+      # @api private
       def set_virtual_machine_note
         return unless config[:vm_note]
 
@@ -211,6 +313,13 @@ module Kitchen
         run_ps set_vm_note
       end
 
+      # Copy the configured files into the running guest.
+      #
+      # Requires the guest service interface, which `enable_guest_services`
+      # turns on.
+      #
+      # @return [void]
+      # @api private
       def copy_vm_files
         return if config[:copy_vm_files].nil?
 
@@ -221,6 +330,10 @@ module Kitchen
         info("Copied files to virtual machine")
       end
 
+      # Whether a VM for this instance exists, starting it if it is stopped.
+      #
+      # @return [Boolean]
+      # @api private
       def vm_exists
         info("Checking for existing virtual machine.")
         return false unless @state.key?(:id) && !@state[:id].nil?
@@ -228,12 +341,18 @@ module Kitchen
         existing_vm = run_ps ensure_vm_running_ps
         return false if existing_vm.nil? || existing_vm["Id"].nil?
 
-        info("Found an exising VM with an ID: #{existing_vm["Id"]}")
+        info("Found an existing VM with an ID: #{existing_vm["Id"]}")
         true
       end
 
-      # Used in testing if a stale diff disk exists.  Silent so the output doesn't
-      # appear twice on the kitchen destroy command for the second check for vm_exists
+      # {#vm_exists} without the logging.
+      #
+      # `destroy` checks for a VM twice -- once to decide whether a leftover
+      # differencing disk is stale, once to decide whether to remove the VM --
+      # and logging both checks makes it look like the driver ran twice.
+      #
+      # @return [Boolean]
+      # @api private
       def vm_exists_silent
         return false unless @state.key?(:id) && !@state[:id].nil?
 
@@ -243,18 +362,45 @@ module Kitchen
         true
       end
 
+      # Whether this instance's differencing disk is on disk.
+      #
+      # @return [Boolean]
+      # @api private
       def differencing_disk_exists
-        return unless File.exist? differencing_disk_path
-
-        true
-      end
-
+        File.exist?(differencing_disk_path)
+      end
+
+      # Read a config value that must be numeric.
+      #
+      # Values coming from `kitchen.yml` may be quoted, and comparing a String
+      # against an Integer raises deep inside Comparable rather than reporting
+      # anything a user can act on.
+      #
+      # @param key [Symbol] the config key
+      # @return [Integer]
+      # @raise [RuntimeError] if the value is not coercible to an Integer
+      # @api private
+      def integer_config(key)
+        value = config[key]
+        Integer(value)
+      rescue ArgumentError, TypeError
+        raise "#{key} (#{value.inspect}) must be an integer"
+      end
+
+      # Force the VM off and remove it.
+      #
+      # @return [void]
+      # @api private
       def remove_virtual_machine
         info("Deleting virtual machine for #{instance.name}")
         run_ps delete_vm_ps
         info("Deleted virtual machine for #{instance.name}")
       end
 
+      # Delete this instance's differencing disk, if present.
+      #
+      # @return [void]
+      # @api private
       def remove_differencing_disk
         return unless differencing_disk_exists
 
@@ -263,6 +409,11 @@ module Kitchen
         info("Removed the differencing disk for #{instance.name}.")
       end
 
+      # Delete every configured additional disk that exists.
+      #
+      # @return [void]
+      # @raise [RuntimeError] if a disk entry has no name
+      # @api private
       def remove_additional_disks
         return if config[:additional_disks].nil?
 
@@ -279,74 +430,141 @@ module Kitchen
         end
       end
 
+      # Where this instance's files live under the local kitchen root.
+      #
+      # @return [String]
+      # @api private
       def kitchen_vm_path
         @kitchen_vm_path ||= File.join(config[:kitchen_root], ".kitchen/#{instance.name}")
       end
 
+      # Where this instance's files live on a remote Hyper-V host.
+      #
+      # @return [String]
+      # @api private
       def remote_kitchen_vm_path
         config[:remote_vm_path]
       end
 
+      # Directory holding every disk belonging to this instance.
+      #
+      # A remote host cannot see the local kitchen root, so a remote run keeps
+      # its disks under `remote_vm_path` instead.
+      #
+      # @return [String]
+      # @api private
+      def vm_base_path
+        remote_hyperv ? remote_kitchen_vm_path : kitchen_vm_path
+      end
+
+      # ISO to boot the VM from, for building an instance from install media.
+      #
+      # @return [String, nil]
+      # @api private
       def boot_iso_path
         @boot_iso_path ||= config[:boot_iso_path]
       end
 
+      # Full path to this instance's differencing disk.
+      #
+      # @return [String]
+      # @api private
       def differencing_disk_path
-        kitchen_vm_base = remote_hyperv ? remote_kitchen_vm_path : kitchen_vm_path
-
-        @differencing_disk_path ||= File.join(kitchen_vm_base, "diff" + "#{config[:disk_type]}")
+        @differencing_disk_path ||= File.join(vm_base_path, "diff#{config[:disk_type]}")
       end
 
+      # Full path to one additional data disk.
+      #
+      # @param disk_name [String] the disk's configured name
+      # @param disk_type [String] the file extension, e.g. `".vhdx"`
+      # @return [String]
+      # @api private
       def additional_disk_path(disk_name, disk_type)
-        File.join(kitchen_vm_path, disk_name + disk_type)
+        File.join(vm_base_path, disk_name + disk_type)
       end
 
+      # Full path to the parent VHD every instance is cloned from.
+      #
+      # @return [String]
+      # @api private
       def parent_vhd_path
         @parent_vhd_path ||= File.join(config[:parent_vhd_folder], config[:parent_vhd_name])
       end
 
+      # Whether the configured parent VHD folder exists locally.
+      #
+      # @return [Boolean]
+      # @api private
       def vhd_folder?
         config[:parent_vhd_folder] && Dir.exist?(config[:parent_vhd_folder])
       end
 
+      # Whether the configured parent VHD file exists locally.
+      #
+      # @return [Boolean]
+      # @api private
       def vhd?
         config[:parent_vhd_name] && File.exist?(parent_vhd_path)
       end
 
+      # Whether the driver is targeting a remote Hyper-V host over WinRM.
+      #
+      # @return [Boolean]
+      # @api private
       def remote_hyperv
         !!config[:hyperv_server]
       end
 
+      # The Train connection commands run over, opened on first use.
+      #
+      # Uses the `local` backend on a Hyper-V host and `winrm` when
+      # `hyperv_server` is set, uploading the support script in that case.
+      #
+      # @return [Train::Plugins::Transport::BaseConnection]
+      # @api private
       def connection
         return @connection if @connection
 
         backend = remote_hyperv ? "winrm" : "local"
 
         train = Train.create(backend, {
-                              host:        config[:hyperv_server],
-                              user:        config[:hyperv_username],
-                              password:    config[:hyperv_password],
-                              ssl:         config[:hyperv_ssl],
+                              host: config[:hyperv_server],
+                              user: config[:hyperv_username],
+                              password: config[:hyperv_password],
+                              ssl: config[:hyperv_ssl],
                               self_signed: config[:hyperv_insecure],
                             })
         @connection = train.connection
 
-        # Copy support PS1
-        @connection.upload(local_script_path, remote_script_path)
+        # Only the remote backend dot-sources the uploaded copy; locally the
+        # driver reads the script straight out of the gem.
+        @connection.upload(local_script_path, remote_script_path) if remote_hyperv
 
         @connection
       end
 
+      # Path every generated script dot-sources to load the helper functions.
+      #
+      # @return [String]
+      # @api private
       def base_script_path
         return remote_script_path if remote_hyperv
 
         local_script_path
       end
 
+      # Path to `support/hyperv.ps1` inside the installed gem.
+      #
+      # @return [String]
+      # @api private
       def local_script_path
-        File.join(File.dirname(__FILE__), "/../../../support/hyperv.ps1")
+        File.expand_path("../../../support/hyperv.ps1", __dir__)
       end
 
+      # Path the support script is uploaded to on a remote host.
+      #
+      # @return [String]
+      # @api private
       def remote_script_path
         File.join(config[:kitchen_root], "kitchen-hyperv", "hyperv.ps1")
       end

data/lib/kitchen/driver/hyperv_version.rb

@@ -17,6 +17,13 @@
 
 module Kitchen
   module Driver
-    HYPERV_VERSION = "0.10.2".freeze
+    # Version of the kitchen-hyperv gem, reported by `kitchen diagnose` as the
+    # driver's plugin version.
+    #
+    # Kept in its own file so the gemspec can read it without loading the
+    # driver, and therefore without loading test-kitchen.
+    #
+    # @return [String] a frozen semantic version
+    HYPERV_VERSION = "0.11.0".freeze
   end
 end

data/lib/kitchen/driver/powershell.rb

@@ -15,6 +15,7 @@
 # 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 "benchmark" unless defined?(Benchmark)
 require "fileutils" unless defined?(FileUtils)
@@ -22,12 +23,42 @@ require "json" unless defined?(JSON)
 
 module Kitchen
   module Driver
+    # PowerShell generation and execution for {Kitchen::Driver::Hyperv}.
+    #
+    # Every method here is either a script generator -- a `*_ps` method
+    # returning PowerShell source -- or part of the pipeline that runs one:
+    # {#run_ps} wraps the script so it dot-sources `support/hyperv.ps1`,
+    # {#encode_command} encodes it for `powershell.exe -encodedcommand`, and
+    # {#execute_command} runs it over the Train connection and parses the JSON
+    # that comes back.
+    #
+    # Encoding sidesteps every layer of quoting between Ruby and PowerShell,
+    # which matters because these scripts embed Windows paths and user-supplied
+    # strings.
+    #
+    # The module reads `config`, `instance` and `@state` from the driver it is
+    # mixed into, so it is not usable standalone.
+    #
+    # @see Kitchen::Driver::Hyperv
     module PowerShellScripts
+      # Encode a script the way `powershell.exe -encodedcommand` expects it:
+      # UTF-16LE, then Base64.
+      #
+      # @param script [String] UTF-8 PowerShell source
+      # @return [String] strict Base64, with no line breaks
+      # @api private
       def encode_command(script)
         encoded_script = script.encode("UTF-16LE", "UTF-8")
         Base64.strict_encode64(encoded_script)
       end
 
+      # Whether a 64-bit PowerShell is directly reachable.
+      #
+      # Always true for a remote host, where the local architecture is
+      # irrelevant.
+      #
+      # @return [Boolean]
+      # @api private
       def is_64bit?
         return true if remote_hyperv
 
@@ -36,12 +67,26 @@ module Kitchen
         os_arch == "AMD64" && ruby_arch == 64
       end
 
+      # Whether both the OS and Ruby are 32-bit, so no WOW64 redirection is in
+      # play.
+      #
+      # @return [Boolean]
+      # @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
       end
 
+      # Path to a PowerShell that can see the Hyper-V cmdlets.
+      #
+      # When a 32-bit Ruby runs on 64-bit Windows the WOW64 filesystem
+      # redirector rewrites `system32` to `SysWOW64`, which would launch a
+      # 32-bit PowerShell with no Hyper-V module. `sysnative` is the virtual
+      # path that escapes redirection.
+      #
+      # @return [String]
+      # @api private
       def powershell_64_bit
         if is_64bit? || is_32bit?
           'c:\windows\system32\windowspowershell\v1.0\powershell.exe'
@@ -50,6 +95,14 @@ module Kitchen
         end
       end
 
+      # Turn a script into a full `powershell.exe` command line.
+      #
+      # Prepends a dot-source of the support script so the helper functions are
+      # defined, then encodes the result.
+      #
+      # @param script [String] PowerShell source
+      # @return [String] the command line to hand to the connection
+      # @api private
       def wrap_command(script)
         debug("Loading functions from #{base_script_path}")
         new_script = [ ". #{base_script_path}", "#{script}" ].join(";\n")
@@ -58,11 +111,16 @@ module Kitchen
         " -encodedcommand #{encode_command new_script} -outputformat Text"
       end
 
-      # Convenience method to run a powershell command locally.
+      # Run a PowerShell script on the Hyper-V host.
+      #
+      # With `dry_run` set the script is echoed rather than executed, which is
+      # the quickest way to see exactly what the driver would have run.
       #
-      # @param cmd [String] command to run locally
-      # @param options [Hash] options hash
-      # @see Kitchen::ShellOut.run_command
+      # @param cmd [String] PowerShell source
+      # @param options [Hash] options passed through to the Train connection
+      # @return [Hash, Array, nil] the parsed JSON output, or nil when the
+      #   script produced none
+      # @raise [RuntimeError] if the script exits non-zero
       # @api private
       def run_ps(cmd, options = {})
         cmd = "echo #{cmd}" if config[:dry_run]
@@ -72,6 +130,14 @@ module Kitchen
         execute_command wrapped_command, options
       end
 
+      # Run a prepared command line and parse its output.
+      #
+      # @param cmd [String] the full command line from {#wrap_command}
+      # @param options [Hash] options passed through to the Train connection
+      # @return [Hash, Array, nil] the parsed JSON output, or nil when the
+      #   script produced none
+      # @raise [RuntimeError] if the command exits non-zero
+      # @api private
       def execute_command(cmd, options = {})
         debug("#Command BEGIN (#{cmd})")
 
@@ -87,10 +153,21 @@ module Kitchen
         JSON.parse(stdout) if stdout.length > 2
       end
 
+      # Strip the interactive prompt lines PowerShell interleaves with output,
+      # which would otherwise make the result invalid JSON.
+      #
+      # @param stdout [String] raw stdout from the host
+      # @return [String] stdout with prompt lines removed
+      # @api private
       def sanitize_stdout(stdout)
         stdout.split("\n").select { |s| !s.start_with?("PS") }.join("\n")
       end
 
+      # Script that clones the parent VHD into this instance's differencing
+      # disk.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def new_differencing_disk_ps
         <<-DIFF
 
@@ -98,6 +175,12 @@ module Kitchen
         DIFF
       end
 
+      # Script that creates one additional data disk.
+      #
+      # @param disk_path [String] full path of the disk to create
+      # @param disk_size [Integer] size in gigabytes
+      # @return [String] PowerShell source
+      # @api private
       def new_additional_disk_ps(disk_path, disk_size)
         <<-ADDDISK
 
@@ -105,6 +188,10 @@ module Kitchen
         ADDDISK
       end
 
+      # Script that confirms the VM exists and starts it if it is stopped.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def ensure_vm_running_ps
         <<-RUNNING
 
@@ -112,6 +199,10 @@ module Kitchen
         RUNNING
       end
 
+      # Script that creates the VM from the current configuration.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def new_vm_ps
         <<-NEWVM
 
@@ -137,6 +228,14 @@ module Kitchen
         NEWVM
       end
 
+      # The `AdditionalDisks` entry spliced into {#new_vm_ps}.
+      #
+      # Reads the paths {Hyperv#create_additional_disks} recorded, so it is only
+      # meaningful after that has run.
+      #
+      # @return [String, nil] the parameter line, or nil when no additional
+      #   disks are configured
+      # @api private
       def additional_disks
         return if config[:additional_disks].nil?
 
@@ -145,7 +244,11 @@ module Kitchen
         EOH
       end
 
-      # TODO: Report if VM has no IP address instead of silently waiting forever
+      # Script that reads the VM's name, id and IP address.
+      #
+      # @return [String] PowerShell source
+      # @api private
+      # @todo Report if VM has no IP address instead of silently waiting forever
       def vm_details_ps
         <<-DETAILS
 
@@ -153,6 +256,10 @@ module Kitchen
         DETAILS
       end
 
+      # Script that forces the VM off and removes it.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def delete_vm_ps
         <<-REMOVE
 
@@ -162,6 +269,10 @@ module Kitchen
         REMOVE
       end
 
+      # Script that assigns the VM a static address once its adapter is up.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def set_vm_ipaddress_ps
         <<-VMIP
 
@@ -178,30 +289,55 @@ module Kitchen
         VMIP
       end
 
+      # Script that resolves the virtual switch to attach the VM to.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def vm_default_switch_ps
         <<-VMSWITCH
           Get-DefaultVMSwitch "#{config[:vm_switch]}" | ConvertTo-Json
         VMSWITCH
       end
 
+      # Script that attaches the configured ISO to the VM's DVD drive.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def mount_vm_iso
         <<-MOUNTISO
           mount-vmiso -id "#{@state[:id]}" -Path #{config[:iso_path]}
         MOUNTISO
       end
 
+      # Script that grows the parent VHD to the configured size.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def resize_vhd
         <<-VMNOTE
           Resize-VHD -Path "#{parent_vhd_path}" -SizeBytes #{config[:resize_vhd]}
         VMNOTE
       end
 
+      # Script that writes the configured note onto the VM.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def set_vm_note
         <<-VMNOTE
           Set-VM -Name (Get-VM | Where-Object{ $_.ID -eq "#{@state[:id]}"}).Name -Note "#{config[:vm_note]}"
         VMNOTE
       end
 
+      # Script that copies a file or directory into the running guest.
+      #
+      # Enables the guest service interface first if it is off, and walks a
+      # directory source file by file since `Copy-VMFile` handles only files.
+      #
+      # @param source [String] path on the Hyper-V host
+      # @param dest [String] path inside the guest
+      # @return [String] PowerShell source
+      # @api private
       def copy_vm_file_ps(source, dest)
         <<-FILECOPY
           Function CopyFile ($VM, [string]$SourcePath, [string]$DestPath) {
@@ -240,6 +376,11 @@ module Kitchen
 
       private
 
+      # Render a Ruby array as a PowerShell array literal.
+      #
+      # @param list [Array<String>, nil] the values
+      # @return [String] e.g. `@("8.8.8.8", "8.8.4.4")`, or `@()` when empty
+      # @api private
       def ruby_array_to_ps_array(list)
         return "@()" if list.nil? || list.empty?
 

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-hyperv
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.11.0
 platform: ruby
 authors:
 - Steven Murawski
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-22 00:00:00.000000000 Z
+date: 2026-08-22 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
@@ -34,30 +48,42 @@ dependencies:
   name: train
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: train-winrm
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: Hyper-V Driver for Test-Kitchen
 email:
 - steven.murawski@gmail.com