test-kitchen 4.1.0 → 4.1.2

data/lib/kitchen/platform_filter.rb

@@ -18,8 +18,8 @@
 module Kitchen
   # A wrapper on Regexp and strings to mix them in platform filters.
   #
-  # This should handle backward compatibility in most cases were
-  # platform are matched against a filters array using Array.include?
+  # This should handle backward compatibility in most cases where
+  # platforms are matched against a filter array using Array.include?
   #
   # This wrapper does not work if filters arrays are converted to Set.
   #
@@ -29,7 +29,7 @@ module Kitchen
     REGEXP_LIKE_PATTERN = %r{^/(?<pattern>.*)/(?<options>[ix]*)$}
 
     # Converts platform filters into an array of PlatformFilter handling both strings and Regexp.
-    # A string "looks-like" a regexp if it starts by / and end by / + Regexp options i or x
+    # A string "looks-like" a regexp if it starts with / and ends with / + Regexp options i or x
     #
     # @return [Array] filters with regexp-like string converted to PlatformRegexpFilter
     def self.convert(filters)
@@ -57,7 +57,7 @@ module Kitchen
       @value = value
     end
 
-    # Override of the equality operator to check whether the wrapped Regexp match the given object.
+    # Override of the equality operator to check whether the wrapped Regexp matches the given object.
     #
     # @param [Object] other object to compare to
     # @return [Boolean] whether the objects are equal or the wrapped Regexp matches the given string or symbol

data/lib/kitchen/plugin.rb

@@ -20,10 +20,13 @@ require_relative "errors"
 require_relative "util"
 
 module Kitchen
+  # Namespace for plugin loading and the shared plugin base class.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
   module Plugin
     # Returns an instance of a plugin given a type, name, and config.
     #
-    # @param type [Module] a Kitchen::<Module> of one of the plugin types
+    # @param type [Module] a `Kitchen::<Module>` of one of the plugin types
     #   (Driver, Provisioner, Transport, Verifier)
     # @param plugin [String] a plugin name, which will be constantized
     # @param config [Hash] a configuration hash to initialize the plugin

data/lib/kitchen/plugin_base.rb

@@ -17,6 +17,11 @@
 
 module Kitchen
   module Plugin
+    # Common base class for every plugin type (Driver, Provisioner, Transport,
+    # and Verifier), providing the shared plugin lifecycle and the
+    # serial-action registry.
+    #
+    # @author Fletcher Nichol <fnichol@nichol.ca>
     class Base
       class << self
         # @return [Array<Symbol>] an array of action method names that cannot

data/lib/kitchen/provisioner/base.rb

@@ -142,7 +142,7 @@ module Kitchen
       # Check system and configuration for common errors.
       #
       # @param state [Hash] mutable instance state
-      # @returns [Boolean] Return true if a problem is found.
+      # @return [Boolean] Return true if a problem is found.
       def doctor(state)
         false
       end
@@ -211,11 +211,11 @@ module Kitchen
       # exception if `#create_sandbox` has not yet been called.
       #
       # @return [String] the absolute path to the sandbox directory
-      # @raise [ClientError] if the sandbox directory has no yet been created
+      # @raise [ClientError] if the sandbox directory has not yet been created
       #   by calling `#create_sandbox`
       def sandbox_path
         @sandbox_path ||= raise ClientError, "Sandbox directory has not yet " \
-          "been created. Please run #{self.class}#create_sandox before " \
+          "been created. Please run #{self.class}#create_sandbox before " \
           "trying to access the path."
       end
 
@@ -264,7 +264,7 @@ module Kitchen
 
       # Conditionally prefixes a command with a sudo command.
       #
-      # @param command [String] command to be prefixed
+      # @param script [String] command to be prefixed
       # @return [String] the command, conditionally prefixed with sudo
       # @api private
       def sudo(script)
@@ -285,7 +285,7 @@ module Kitchen
       # Cisco Nexus, require all commands to be run with a prefix to
       # obtain outbound network access.
       #
-      # @param command [String] command to be prefixed
+      # @param script [String] command to be prefixed
       # @return [String] the command, conditionally prefixed with the configured prefix
       # @api private
       def prefix_command(script)

data/lib/kitchen/provisioner/dummy.rb

@@ -19,7 +19,7 @@ require_relative "../../kitchen"
 
 module Kitchen
   module Provisioner
-    # Dummy provisioner for Kitchen. This driver does nothing but report what
+    # Dummy provisioner for Kitchen. This provisioner does nothing but report what
     # would happen if this provisioner did anything of consequence. As a result
     # it may be a useful provisioner to use when debugging or developing new
     # features or plugins.

data/lib/kitchen/provisioner/external.rb

@@ -25,12 +25,30 @@ module Kitchen
   module Provisioner
     # Executes an external provisioner provider over the v1 stdio protocol.
     class External < Base
+      # The provider protocol version this provisioner speaks. A provider
+      # reporting any other version is rejected during capability negotiation.
+      #
+      # @return [String] a protocol version string
       PROTOCOL_VERSION = "1.0".freeze
+      # The result statuses a provider may report for an action.
+      #
+      # @return [Array<String>] valid result statuses
       RESULT_STATUSES = %w{passed failed skipped}.freeze
+      # The log levels a provider may attach to a log message.
+      #
+      # @return [Array<String>] valid log levels
       LOG_LEVELS = %w{debug info warn error}.freeze
+      # Configuration keys consumed by this provisioner itself, and so withheld
+      # from the configuration passed out to the provider.
+      #
+      # @return [Array<Symbol>] internal-only configuration keys
       INTERNAL_CONFIG_KEYS = %i{
         command provider pass_env kitchen_root test_base_path
       }.freeze
+      # Configuration keys whose values are redacted before configuration is
+      # logged or handed to a provider.
+      #
+      # @return [Array<String>] keys to redact
       REDACTED_KEYS = %w{password ssh_http_proxy_password}.freeze
 
       kitchen_provisioner_api_version 2
@@ -50,6 +68,10 @@ module Kitchen
         persist_provider_state(state, result)
       end
 
+      # Derives the provider's name from the configured command, stripping any
+      # directory portion and the conventional `kitchen-provider-` prefix.
+      #
+      # @return [String] the provider name
       def provider_name_from_command
         first_part = Shellwords.split(config[:command].to_s).first.to_s
         File.basename(first_part).sub(/^kitchen-provider-/, "")

data/lib/kitchen/provisioner.rb

@@ -20,7 +20,7 @@ require_relative "plugin"
 
 module Kitchen
   # A provisioner is responsible for generating the commands necessary to
-  # install set up and use a configuration management tool such as Chef and
+  # install, set up, and use a configuration management tool such as Chef and
   # Puppet.
   #
   # @author Fletcher Nichol <fnichol@nichol.ca>

data/lib/kitchen/state_file.rb

@@ -26,7 +26,7 @@ module Kitchen
   #
   # @author Fletcher Nichol <fnichol@nichol.ca>
   class StateFile
-    # Constructs an new instance taking the kitchen root and instance name.
+    # Constructs a new instance taking the kitchen root and instance name.
     #
     # @param kitchen_root [String] path to the Kitchen project's root directory
     # @param name [String] name of the instance representing this state

data/lib/kitchen/suite.rb

@@ -35,7 +35,7 @@ module Kitchen
     # Constructs a new suite.
     #
     # @param [Hash] options configuration for a new suite
-    # @option options [String] :name logical name of this suit (**Required**)
+    # @option options [String] :name logical name of this suite (**Required**)
     # @option options [String] :excludes Array of names of excluded platforms
     # @option options [String] :includes Array of names of only included
     #   platforms

data/lib/kitchen/transport/base.rb

@@ -69,7 +69,7 @@ module Kitchen
       # Check system and configuration for common errors.
       #
       # @param state [Hash] mutable instance state
-      # @returns [Boolean] Return true if a problem is found.
+      # @return [Boolean] Return true if a problem is found.
       def doctor(state)
         false
       end

data/lib/kitchen/transport/dummy.rb

@@ -31,14 +31,21 @@ module Kitchen
       default_config :sleep, 1
       default_config :random_exit_code, 0
 
+      # Creates a new dummy connection, merging the instance state into the
+      # transport's configuration.
+      #
+      # @param state [Hash] the instance state hash
+      # @yield [Connection] yields the connection for block-style invocation
+      # @return [Connection] a new connection
       def connection(state, &block)
         options = config.to_hash.merge(state)
         Kitchen::Transport::Dummy::Connection.new(options, &block)
       end
 
-      # TODO: comment
+      # A connection that reports the actions it would have carried out
+      # rather than contacting any remote host.
       class Connection < Kitchen::Transport::Base::Connection
-        # (see Base#execute)
+        # (see Base::Connection#execute)
         def execute(command)
           report(:execute, command)
           if options[:random_exit_code] != 0
@@ -46,10 +53,20 @@ module Kitchen
           end
         end
 
+        # Reports that the given files would have been uploaded.
+        #
+        # @param locals [Array<String>] local paths that would be uploaded
+        # @param remote [String] the remote destination path
+        # @return [void]
         def upload(locals, remote)
           report(:upload, "#{locals.inspect} => #{remote}")
         end
 
+        # Reports that the given files would have been downloaded.
+        #
+        # @param remotes [Array<String>] remote paths that would be downloaded
+        # @param local [String] the local destination path
+        # @return [void]
         def download(remotes, local)
           report(:download, "#{remotes.inspect} => #{local}")
         end
@@ -60,7 +77,8 @@ module Kitchen
         # possibly fail randomly.
         #
         # @param action [Symbol] the action currently taking place
-        # @param state [Hash] the state hash
+        # @param msg [String] an optional message describing the action's
+        #   subject, appended to the log output
         # @api private
         def report(action, msg = "")
           what = action.capitalize

data/lib/kitchen/transport/exec.rb

@@ -66,7 +66,7 @@ module Kitchen
           end
         end
 
-        # (see Base#init_options)
+        # (see Base::Connection#init_options)
         def init_options(options)
           super
           @instance_name = @options.delete(:instance_name)

data/lib/kitchen/transport/ssh.rb

@@ -77,6 +77,10 @@ module Kitchen
         transport[:compression] == false ? 0 : 6
       end
 
+      # (see Base#finalize_config!)
+      #
+      # Casts legacy `:compression` values to what net-ssh 2.10 and later
+      # expect.
       def finalize_config!(instance)
         super
 
@@ -106,7 +110,7 @@ module Kitchen
       # (see Base#cleanup!)
       def cleanup!
         if @connection
-          string_to_mask = "[SSH] shutting previous connection #{@connection}"
+          string_to_mask = "[SSH] shutting down previous connection #{@connection}"
           masked_string = Util.mask_values(string_to_mask, %w{password ssh_http_proxy_password})
           logger.debug(masked_string)
           @connection.close
@@ -121,7 +125,10 @@ module Kitchen
       #
       # @author Fletcher Nichol <fnichol@nichol.ca>
       class Connection < Kitchen::Transport::Base::Connection
-        # (see Base::Connection#initialize)
+        # Create a new Connection instance.
+        #
+        # @param config [Hash] connection options
+        # @yield [self] yields itself for block-style invocation
         def initialize(config = {})
           super(config)
           @session = nil
@@ -299,17 +306,17 @@ module Kitchen
         # @api private
         attr_reader :ssh_http_proxy
 
-        # @return [Integer] The port to use when using an kitchen ssh proxy
+        # @return [Integer] The port to use when using a kitchen ssh proxy
         #   remote SSH host via http proxy
         # @api private
         attr_reader :ssh_http_proxy_port
 
-        # @return [String] The username to use when using an kitchen ssh proxy
+        # @return [String] The username to use when using a kitchen ssh proxy
         #   remote SSH host via http proxy
         # @api private
         attr_reader :ssh_http_proxy_user
 
-        # @return [String] The password to use when using an kitchen ssh proxy
+        # @return [String] The password to use when using a kitchen ssh proxy
         #   remote SSH host via http proxy
         # @api private
         attr_reader :ssh_http_proxy_password
@@ -570,7 +577,7 @@ module Kitchen
         current_net_ssh >= new_option_version ? :never : false
       end
 
-      # Creates a new SSH Connection instance and save it for potential future
+      # Creates a new SSH Connection instance and saves it for potential future
       # reuse.
       #
       # @param options [Hash] connection options

data/lib/kitchen/transport/winrm.rb

@@ -58,6 +58,9 @@ module Kitchen
         transport[:winrm_transport] == :ssl ? 5986 : 5985
       end
 
+      # (see Base#finalize_config!)
+      #
+      # Coerces `:winrm_transport` to a Symbol.
       def finalize_config!(instance)
         super
 
@@ -84,7 +87,10 @@ module Kitchen
       #
       # @author Fletcher Nichol <fnichol@nichol.ca>
       class Connection < Kitchen::Transport::Base::Connection
-        # (see Base::Connection#initialize)
+        # Create a new Connection instance.
+        #
+        # @param config [Hash] connection options
+        # @yield [self] yields itself for block-style invocation
         def initialize(config = {})
           super(config)
           @unelevated_session = nil
@@ -225,7 +231,7 @@ module Kitchen
         # @api private
         attr_reader :max_wait_until_ready
 
-        # @return [Integer] the TCP port number to use when connection to the
+        # @return [Integer] the TCP port number to use when connecting to the
         #   remote WinRM host
         # @api private
         attr_reader :rdp_port
@@ -293,7 +299,7 @@ module Kitchen
           @file_transporter ||= WinRM::FS::Core::FileTransporter.new(unelevated_session)
         end
 
-        # (see Base#init_options)
+        # (see Base::Connection#init_options)
         def init_options(options)
           super
           @instance_name = @options.delete(:instance_name)
@@ -494,15 +500,15 @@ module Kitchen
         end
       end
 
-      # Creates a new WinRM Connection instance and save it for potential
+      # Creates a new WinRM Connection instance and saves it for potential
       # future reuse.
       #
       # @param options [Hash] connection options
-      # @return [Ssh::Connection] a WinRM Connection instance
+      # @return [Winrm::Connection] a WinRM Connection instance
       # @api private
       def create_new_connection(options, &block)
         if @connection
-          string_to_mask = "[WinRM] shutting previous connection #{@connection}"
+          string_to_mask = "[WinRM] shutting down previous connection #{@connection}"
           masked_string = Util.mask_values(string_to_mask, %w{password ssh_http_proxy_password})
           logger.debug(masked_string)
           @connection.close

data/lib/kitchen/util.rb

@@ -37,7 +37,7 @@ module Kitchen
       Logger.const_get(symbol.to_s.upcase)
     end
 
-    # Returns the symbol representation of a logging levels for a given
+    # Returns the symbol representation of a logging level for a given
     # standard library Logger::Severity constant.
     #
     # @param const [Integer] Logger::Severity constant value for a logging
@@ -91,7 +91,7 @@ module Kitchen
     # Returns a string with masked values for specified parameters.
     #
     # @param string_to_mask [String] the object whose string representation is parsed
-    # @param [Array] the list of keys whose values should be masked
+    # @param keys [Array] the list of keys whose values should be masked
     # @return [String] the string representation of passed object with masked values
     def self.mask_values(string_to_mask, keys)
       masked_string = string_to_mask
@@ -118,7 +118,7 @@ module Kitchen
     # This method uses the Bourne shell (/bin/sh) to maximize the chance of
     # cross platform portability on Unixlike systems.
     #
-    # @param [String] the command
+    # @param cmd [String] the command
     # @return [String] a wrapped command string
     def self.wrap_command(cmd)
       cmd = "false" if cmd.nil?
@@ -166,7 +166,7 @@ module Kitchen
     # @return A listing of the specified path
     #
     # @note You should prefer this method to using Dir.glob directly. The reason is
-    # because Dir.glob behaves strangely on Windows. It wont accept '\'
+    # because Dir.glob behaves strangely on Windows. It won't accept '\'
     # and doesn't like fake directories (C:\Documents and Settings)
     # It also does not do any sort of error checking, so things one would
     # expect to fail just return an empty list
@@ -221,10 +221,18 @@ module Kitchen
       end
     end
 
+    # Returns a CamelCase version of a snake_case string.
+    #
+    # @param a_string [String] a snake_case string
+    # @return [String] a CamelCase string
     def self.camel_case(a_string)
       Thor::Util.camel_case(a_string)
     end
 
+    # Returns a snake_case version of a CamelCase string.
+    #
+    # @param a_string [String] a CamelCase string
+    # @return [String] a snake_case string
     def self.snake_case(a_string)
       Thor::Util.snake_case(a_string)
     end

data/lib/kitchen/verifier/base.rb

@@ -106,7 +106,7 @@ module Kitchen
       # Check system and configuration for common errors.
       #
       # @param state [Hash] mutable instance state
-      # @returns [Boolean] Return true if a problem is found.
+      # @return [Boolean] Return true if a problem is found.
       def doctor(state)
         false
       end
@@ -180,11 +180,11 @@ module Kitchen
       # exception if `#create_sandbox` has not yet been called.
       #
       # @return [String] the absolute path to the sandbox directory
-      # @raise [ClientError] if the sandbox directory has no yet been created
+      # @raise [ClientError] if the sandbox directory has not yet been created
       #   by calling `#create_sandbox`
       def sandbox_path
         @sandbox_path ||= raise ClientError, "Sandbox directory has not yet " \
-           "been created. Please run #{self.class}#create_sandox before " \
+           "been created. Please run #{self.class}#create_sandbox before " \
            "trying to access the path."
       end
 
@@ -240,7 +240,7 @@ module Kitchen
 
       # Conditionally prefixes a command with a sudo command.
       #
-      # @param command [String] command to be prefixed
+      # @param script [String] command to be prefixed
       # @return [String] the command, conditionally prefixed with sudo
       # @api private
       def sudo(script)
@@ -253,7 +253,7 @@ module Kitchen
       # Cisco Nexus, require all commands to be run with a prefix to
       # obtain outbound network access.
       #
-      # @param command [String] command to be prefixed
+      # @param script [String] command to be prefixed
       # @return [String] the command, conditionally prefixed with the configured prefix
       # @api private
       def prefix_command(script)

data/lib/kitchen/verifier/busser.rb

@@ -23,7 +23,7 @@ require_relative "base"
 module Kitchen
   module Verifier
     # Command string generator to interface with Busser. The commands that are
-    # generated are safe to pass to an SSH command or as an unix command
+    # generated are safe to pass to an SSH command or as a Unix command
     # argument (escaped in single quotes).
     #
     # @author Fletcher Nichol <fnichol@nichol.ca>

data/lib/kitchen/verifier/shell.rb

@@ -19,7 +19,7 @@ require_relative "base"
 
 module Kitchen
   module Verifier
-    # Shell verifier for Kitchen. This verifier just execute shell command from local.
+    # Shell verifier for Kitchen. This verifier just executes a shell command locally.
     #
     # @author SAWANOBORI Yukihiko (<sawanoboriyu@higanworks.com>)
     class Shell < Kitchen::Verifier::Base

data/lib/kitchen/version.rb

@@ -16,5 +16,8 @@
 # limitations under the License.
 
 module Kitchen
-  VERSION = "4.1.0".freeze
+  # The currently released version of Test Kitchen.
+  #
+  # @return [String] a semantic version string
+  VERSION = "4.1.2".freeze
 end

data/lib/kitchen/which.rb

@@ -19,6 +19,8 @@ require "chef-utils/dsl/which" unless defined?(ChefUtils::DSL::Which)
 require_relative "chef_utils_wiring" unless defined?(Kitchen::ChefUtilsWiring)
 
 module Kitchen
+  # Mixin providing a `which` helper for locating executables on the PATH,
+  # wired up to Test Kitchen's chef-utils configuration.
   module Which
     include ChefUtils::DSL::Which
     include ChefUtilsWiring

data/lib/kitchen.rb

@@ -85,7 +85,7 @@ module Kitchen
     # log file.
     #
     # @param [Symbol] level logging level
-    # @param [Boolean] log_overwrite logging level
+    # @param [Boolean] log_overwrite whether to overwrite the log file
     # @return [Logger] a logger
     def default_file_logger(level = nil, log_overwrite = nil)
       level ||= env_log
@@ -162,7 +162,7 @@ end
 # Initialize the base logger
 Kitchen.logger = Kitchen.default_logger
 
-# Setup a collection of instance crash exceptions for error reporting
+# Set up a collection of instance crash exceptions for error reporting
 Kitchen.mutex = Mutex.new
 
 # Initialize the mutex for Dir.chdir coordination

data/lib/vendor/hash_recursive_merge.rb

@@ -74,6 +74,11 @@ module HashRecursiveMerge
   end
 end
 
+# Reopened to mix in {HashRecursiveMerge}, which adds the `#rmerge` and
+# `#rmerge!` deep-merge methods used throughout Test Kitchen's
+# configuration merging.
+#
+# This file is vendored third-party code; see the header for attribution.
 class Hash
   include HashRecursiveMerge
 end

data/templates/driver/README.md.erb

@@ -26,7 +26,7 @@ installed. There are several different behaviors available:
 * `latest` - the latest release will be installed. Subsequent converges
   will always re-install even if chef is present.
 * `<VERSION_STRING>` (ex: `10.24.0`) - the desired version string will
-  be passed the the install.sh script. Subsequent converges will skip if
+  be passed to the install.sh script. Subsequent converges will skip if
   the installed version and the desired version match.
 * `false` or `nil` - no chef is installed.
 

data/test-kitchen.gemspec

@@ -35,8 +35,8 @@ Gem::Specification.new do |gem|
   gem.add_dependency "ostruct",            "~> 0.6"
   gem.add_dependency "syslog",             "~> 0.3"
   gem.add_dependency "thor",               ">= 0.19", "< 2.0"
-  # Chef Forked versions with additional fixes since no one is maintining them upstream
+  # Chef Forked versions with additional fixes since no one is maintaining them upstream
   gem.add_dependency "chef-winrm",         ">= 2.5.0", "< 3.0"
   gem.add_dependency "chef-winrm-elevated", ">= 1.0", "< 2.0"
-  gem.add_dependency "chef-winrm-fs",      ">= 1.0", "< 2.0"
+  gem.add_dependency "chef-winrm-fs", ">= 1.0", "< 2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: test-kitchen
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.1.2
 platform: ruby
 authors:
 - Fletcher Nichol
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-16 00:00:00.000000000 Z
+date: 2026-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bcrypt_pbkdf