test-kitchen 4.1.0 → 4.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37110df4f18f03d75c627d0095a7cfee87e12add45de4265ddbcb3afe5d207da
-  data.tar.gz: 94c3173ff1268904ec591d0de22f15635e1e1a453ce9f3167a4e10c26f6eed48
+  metadata.gz: a2d33ad099262a074eb6c0d0a7e76f86d7e4f06d8400263390569e5ca464bcde
+  data.tar.gz: 3bbbe927caee591ad59ae92c676bda2066e2c27730f8f522ef9d7aad6cf5e48a
 SHA512:
-  metadata.gz: 30070f63b980cdf6ee9139232b013092c08ee838c6534b4af11736beeab7bf0aab1e3bba152665bbc07ac6a9723cee89e1c0cf6251dc4054a8c281c2866274d8
-  data.tar.gz: 1e1ab92e31f6b83b97df09df37e6e853be9f982b78aeabbf96045a1b0ee61fd8012704ad45fdcf2ff249fb489211e470ab5eed8a2db49209597fa05ae473a121
+  metadata.gz: 56befe75562ba39e8e1b5c35e6827fe5fe44c34a62f8bffd02d0b2dbbf80671e269926bcf578c20c4bfcae0ff282616c50e87b2f3d6a0aeb89b1c0f8ab8440aa
+  data.tar.gz: eb059e0f0f76ef6ce30ba1dbd9b09ab28dae4314ac67c83e060a200e7974d26a814e745a2626133a926d2a37f133e1f4d8c46e0ab95597d034eb837f7f3bfe55

data/Gemfile

@@ -12,6 +12,7 @@ group :test do
   gem "maruku",    "~> 0.7"
   gem "minitest",  "~> 6.0", "< 6.1"
   gem "mocha",     "~> 3.0"
+  gem "yard",      "~> 0.9"
 end
 
 group :integration do

data/Rakefile

@@ -38,6 +38,16 @@ rescue LoadError
   puts "cookstyle/chefstyle is not available. (sudo) gem install cookstyle to do style checking."
 end
 
+# Generation options live in .yardopts so that `yard` and `rake yard` agree.
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new(:yard) do |task|
+    task.options += ["--no-cache"]
+  end
+rescue LoadError
+  puts "yard is not available. (sudo) gem install yard to generate the docs."
+end
+
 desc "Run all quality tasks"
 task quality: %i{style stats}
 

data/lib/kitchen/cli.rb

@@ -32,7 +32,7 @@ module Kitchen
       #
       # @param task [String] action to take, usually corresponding to the
       #   subcommand name
-      # @param command [String] command class to create and invoke]
+      # @param command [String] command class to create and invoke
       # @param args [Array] remainder arguments from processed ARGV
       #   (default: `nil`)
       # @param additional_options [Hash] additional configuration needed to
@@ -121,6 +121,11 @@ module Kitchen
       type: :boolean,
       desc: "[Deprecated] Please use `kitchen diagnose'"
     log_options
+    # Lists one or more instances and their last known action state.
+    #
+    # @param args [Array<String>] instance names or regexps to match; matches
+    #   all instances when empty
+    # @return [void]
     def list(*args)
       log_overwrite = options[:log_overwrite].nil? ? false : options[:log_overwrite]
       update_config!(log_overwrite:)
@@ -144,6 +149,12 @@ module Kitchen
       desc: "Include all diagnostics"
     log_options
     test_base_path
+    # Prints the fully computed diagnostic configuration for one or more
+    # instances, after all loader and plugin data has been merged.
+    #
+    # @param args [Array<String>] instance names or regexps to match; matches
+    #   all instances when empty
+    # @return [void]
     def diagnose(*args)
       update_config!
       perform("diagnose", "diagnose", args, loader: @loader)
@@ -250,6 +261,12 @@ module Kitchen
       desc: "Run the converge and verify with debugging enabled."
     test_base_path
     log_options
+    # Runs a full test cycle (destroy, create, converge, setup, verify,
+    # destroy) against one or more instances.
+    #
+    # @param args [Array<String>] instance names or regexps to match; matches
+    #   all instances when empty
+    # @return [void]
     def test(*args)
       update_config!
       ensure_initialized
@@ -258,6 +275,11 @@ module Kitchen
 
     desc "login INSTANCE|REGEXP", "Log in to one instance"
     log_options
+    # Opens an interactive login session on a single instance.
+    #
+    # @param args [Array<String>] an instance name or regexp matching exactly
+    #   one instance
+    # @return [void]
     def login(*args)
       update_config!
       perform("login", "login", args)
@@ -279,6 +301,11 @@ module Kitchen
       type: :boolean,
       desc: "Follow the structured log file"
     log_options
+    # Prints the structured log events recorded for one or more instances.
+    #
+    # @param args [Array<String>] instance names or regexps to match; matches
+    #   all instances when empty
+    # @return [void]
     def logs(*args)
       update_config!(log_overwrite: false)
       perform("logs", "logs", args)
@@ -286,6 +313,12 @@ module Kitchen
 
     desc "package INSTANCE|REGEXP", "package an instance"
     log_options
+    # Packages a single instance into a distributable artifact, as
+    # implemented by the instance's driver.
+    #
+    # @param args [Array<String>] an instance name or regexp matching exactly
+    #   one instance
+    # @return [void]
     def package(*args)
       update_config!
       perform("package", "package", args)
@@ -296,34 +329,56 @@ module Kitchen
     method_option :all,
       aliases: "-a",
       desc: "Check all instances"
+    # Checks one or more instances for common system and configuration
+    # problems.
+    #
+    # @param args [Array<String>] instance names or regexps to match; matches
+    #   all instances when empty
+    # @return [void]
     def doctor(*args)
       update_config!
       perform("doctor", "doctor", args)
     end
 
     desc "exec INSTANCE|REGEXP -c REMOTE_COMMAND",
-      "Execute command on one or more instance"
+      "Execute command on one or more instances"
     method_option :command,
       aliases: "-c",
       desc: "execute via ssh"
     log_options
+    # Executes a remote command on one or more instances over their
+    # configured transport.
+    #
+    # @param args [Array<String>] instance names or regexps to match; matches
+    #   all instances when empty
+    # @return [void]
     def exec(*args)
       update_config!
       perform("exec", "exec", args)
     end
 
     desc "version", "Print Test Kitchen's version information"
+    # Prints Test Kitchen's version information to stdout.
+    #
+    # @return [void]
     def version
       puts "Test Kitchen version #{Kitchen::VERSION}"
     end
     map %w{-v --version} => :version
 
     desc "sink", "Show the Kitchen sink!", hide: true
+    # Shows the Kitchen sink. A hidden easter egg command.
+    #
+    # @return [void]
     def sink
       perform("sink", "sink")
     end
 
     desc "console", "Test Kitchen Console!"
+    # Starts an interactive console session with the Test Kitchen
+    # configuration loaded.
+    #
+    # @return [void]
     def console
       perform("console", "console")
     end
@@ -341,7 +396,7 @@ module Kitchen
     class << self
       private
 
-      # Ensure the any failing commands exit non-zero.
+      # Ensure that any failing commands exit non-zero.
       #
       # @return [true] you die always on failure
       # @api private
@@ -374,7 +429,7 @@ module Kitchen
 
       @config.debug = options[:debug]
 
-      # Now that we have required configs, lets create our file logger
+      # Now that we have required configs, let's create our file logger
       Kitchen.logger = Kitchen.default_file_logger(
         log_level,
         log_overwrite
@@ -401,7 +456,7 @@ module Kitchen
       @log_level = level
     end
 
-    # Check to whether a provided log level is valid
+    # Check whether a provided log level is valid
     #
     # @api private
     def valid_log_level?(level)

data/lib/kitchen/color.rb

@@ -22,6 +22,9 @@ module Kitchen
   #
   # @author Fletcher Nichol <fnichol@nichol.ca>
   module Color
+    # Maps color names to their ANSI SGR parameter codes.
+    #
+    # @return [Hash{Symbol => Integer}] color name to ANSI code mapping
     ANSI = {
       reset: 0, black: 30, red: 31, green: 32, yellow: 33,
       blue: 34, magenta: 35, cyan: 36, white: 37,
@@ -30,6 +33,10 @@ module Kitchen
       bright_cyan: 96, bright_white: 97
     }.freeze
 
+    # The subset of {ANSI} color names cycled through when assigning a
+    # distinct color to each instance.
+    #
+    # @return [Array<String>] assignable color names
     COLORS = %w{
       cyan yellow green magenta blue bright_cyan bright_yellow
       bright_green bright_magenta bright_blue

data/lib/kitchen/command/action.rb

@@ -21,7 +21,7 @@ require "benchmark" unless defined?(Benchmark)
 
 module Kitchen
   module Command
-    # Command to run a single action one or more instances.
+    # Command to run a single action on one or more instances.
     #
     # @author Fletcher Nichol <fnichol@nichol.ca>
     class Action < Kitchen::Command::Base

data/lib/kitchen/command/diagnose.rb

@@ -22,7 +22,7 @@ autoload :YAML, "yaml"
 
 module Kitchen
   module Command
-    # Command to log into to instance.
+    # Command to show the computed diagnostic configuration.
     #
     # @author Fletcher Nichol <fnichol@nichol.ca>
     class Diagnose < Kitchen::Command::Base

data/lib/kitchen/command/login.rb

@@ -19,7 +19,7 @@ require_relative "../command"
 
 module Kitchen
   module Command
-    # Command to log into to instance.
+    # Command to log into an instance.
     #
     # @author Fletcher Nichol <fnichol@nichol.ca>
     class Login < Kitchen::Command::Base

data/lib/kitchen/command/logs.rb

@@ -19,6 +19,10 @@ module Kitchen
   module Command
     # Command to print structured logs for one instance.
     class Logs < Kitchen::Command::Base
+      # Log severity names in ascending order, used to resolve the minimum
+      # level filter.
+      #
+      # @return [Array<String>] severity names, lowest to highest
       LEVELS = %w{debug info warn error fatal unknown}.freeze
 
       # Invoke the command.

data/lib/kitchen/command/package.rb

@@ -16,7 +16,7 @@ require_relative "../command"
 
 module Kitchen
   module Command
-    # Execute command on remote instance.
+    # Command to package one or more instances.
     #
     class Package < Kitchen::Command::Base
       # Invoke the command.

data/lib/kitchen/command.rb

@@ -19,6 +19,9 @@ require_relative "errors"
 require_relative "logging"
 
 module Kitchen
+  # Namespace for the classes implementing each `kitchen` subcommand.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
   module Command
     # Base class for CLI commands.
     #
@@ -100,7 +103,7 @@ module Kitchen
         end
       end
 
-      # Return an array on instances whose name matches the regular expression.
+      # Return an array of instances whose name matches the regular expression.
       #
       # @param regexp [Regexp] a regular expression matching on instance names
       # @return [Array<Instance>] an array of instances
@@ -131,7 +134,7 @@ module Kitchen
         Kitchen.logger
       end
 
-      # Return an array on instances whose name matches the regular expression,
+      # Return an array of instances whose name matches the regular expression,
       # the full instance name, or  the `"all"` literal.
       #
       # @param arg [String] an instance name, a regular expression, the literal
@@ -191,6 +194,12 @@ module Kitchen
         end
       end
 
+      # Determines how many instances may be acted on at once, clamped to the
+      # number of instances available.
+      #
+      # @param instances [Array<Instance>] the instances to be acted on
+      # @return [Integer] the number of worker threads to start
+      # @api private
       def concurrency_setting(instances)
         concurrency = 1
         if options[:concurrency]
@@ -200,6 +209,14 @@ module Kitchen
         concurrency
       end
 
+      # Performs an action on a single instance, recording any instance or
+      # action failure rather than letting it escape the worker thread.
+      #
+      # @param action [String] action to perform
+      # @param instance [Instance] the instance to act on
+      # @param args [Array] additional arguments forwarded to the action
+      # @return [void]
+      # @api private
       def run_action_in_thread(action, instance, *args)
         instance.public_send(action, *args)
       rescue Kitchen::InstanceFailure => e
@@ -212,6 +229,12 @@ module Kitchen
         instance.cleanup!
       end
 
+      # Records an error raised by an action, synchronized across worker
+      # threads.
+      #
+      # @param error [StandardError] the error to record
+      # @return [void]
+      # @api private
       def record_action_error(error)
         @action_errors_mutex.synchronize { @action_errors << error }
       end

data/lib/kitchen/config.rb

@@ -136,7 +136,7 @@ module Kitchen
 
     # Builds the filtered list of Instance objects.
     #
-    # @return [Array<Instance] an array of Instances
+    # @return [Array<Instance>] an array of Instances
     # @api private
     def build_instances
       filter_instances.map.with_index do |(suite, platform), index|
@@ -163,7 +163,7 @@ module Kitchen
     end
 
     # Determines the default absolute path to the testing files directory,
-    # based on the the value of `#kitchen_root`.
+    # based on the value of `#kitchen_root`.
     #
     # @return [String] an absolute path to the testing files directory
     # @api private
@@ -289,12 +289,12 @@ module Kitchen
       )
     end
 
-    # Builds a newly configured LifecycleHooks object, for a given a Suite and
+    # Builds a newly configured LifecycleHooks object, for a given Suite and
     # Platform.
     #
     # @param suite [Suite,#name] a Suite
     # @param platform [Platform,#name] a Platform
-    # @param state_file [Kitchen::StateFile] a SateFile
+    # @param state_file [Kitchen::StateFile] a StateFile
     # @return [LifecycleHooks] a new LifecycleHooks object
     # @api private
     def new_lifecycle_hooks(suite, platform, state_file)
@@ -337,7 +337,7 @@ module Kitchen
       Transport.for_plugin(tdata[:name], tdata)
     end
 
-    # Builds a newly configured Verifier object, for a given a Suite and
+    # Builds a newly configured Verifier object, for a given Suite and
     # Platform.
     #
     # @param suite [Suite,#name] a Suite

data/lib/kitchen/configurable.rb

@@ -26,6 +26,13 @@ module Kitchen
   #
   # @author Fletcher Nichol <fnichol@nichol.ca>
   module Configurable
+    # Extends the including class with {ClassMethods} so that the
+    # `default_config`, `required_config`, and related DSL is available at the
+    # class level.
+    #
+    # @param base [Class] the class including this module
+    # @return [void]
+    # @api private
     def self.included(base)
       base.extend(ClassMethods)
     end
@@ -35,7 +42,7 @@ module Kitchen
 
     # 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 also acts as a
+    # dependent data may be accessed through an Instance. This also acts as a
     # hook point where the object may wish to perform other last minute
     # checks, validations, or configuration expansions.
     #
@@ -73,7 +80,7 @@ module Kitchen
     # fallback rules or returns nil if path cannot be determined.
     #
     # Given an instance with suite named `"server"`, a `test_base_path` of
-    # `"/a/b"`, and a path segment of `"roles"` then following will be tried
+    # `"/a/b"`, and a path segment of `"roles"` then the following will be tried
     # in order (first match that exists wins):
     #
     # 1. /a/b/server/roles
@@ -207,7 +214,7 @@ module Kitchen
     end
 
     # Expands file paths for certain configuration values. A configuration
-    # value is marked for file expansion with a expand_path_for declaration
+    # value is marked for file expansion with an expand_path_for declaration
     # in the included class.
     #
     # @api private
@@ -396,7 +403,7 @@ module Kitchen
     # Helper method to export
     #
     # @param env [Array] the environment to modify
-    # @param code [String] the type of proxy to export, one of 'http', 'https' or 'ftp'
+    # @param type [String] the type of proxy to export, one of 'http', 'https' or 'ftp'
     # @api private
     def export_proxy(env, type)
       env << shell_env_var(type.to_s, ENV[type.to_s]) if ENV[type.to_s]
@@ -586,10 +593,16 @@ module Kitchen
         end
       end
 
+      # @return [Hash] a hash of attribute keys and deprecation messages which
+      #   has been merged with any superclass deprecations
+      # @api private
       def deprecated_attributes
         @deprecated_attributes ||= {}.merge(super_deprecated_attributes)
       end
 
+      # @return [Hash] a hash of deprecated attributes from the superclass, or
+      #   an empty hash when the superclass has none
+      # @api private
       def super_deprecated_attributes
         if superclass.respond_to?(:deprecated_attributes)
           superclass.deprecated_attributes

data/lib/kitchen/data_munger.rb

@@ -651,6 +651,11 @@ module Kitchen
     # Runs all legacy configuration conversions while keeping DataMunger as the
     # public facade for destructive normalization.
     class LegacyConfigNormalizer
+      # The legacy conversion methods to invoke, in order, when normalizing
+      # raw configuration data.
+      #
+      # @return [Array<Symbol>] ordered DataMunger method names
+      # @api private
       STEPS = %i{
         convert_legacy_driver_format!
         convert_legacy_chef_paths_format!
@@ -665,6 +670,10 @@ module Kitchen
         @data_munger = data_munger
       end
 
+      # Destructively runs every conversion in {STEPS} against the data.
+      #
+      # @return [void]
+      # @api private
       def normalize!
         STEPS.each { |step| data_munger.send(step) }
       end
@@ -680,6 +689,16 @@ module Kitchen
         @data_munger = data_munger
       end
 
+      # Merges the default, common, platform, and suite layers for one plugin
+      # key, with later layers winning over earlier ones.
+      #
+      # @param key [Symbol] the plugin key to merge, such as `:driver`
+      # @param suite [String] a suite name
+      # @param platform [String] a platform name
+      # @param default_key [Symbol] the key used when normalizing data
+      #   sub-hashes
+      # @return [Hash] a new merged Hash
+      # @api private
       def merged_data_for(key, suite, platform, default_key)
         ddata = data_munger.send(:normalized_default_data, key, default_key, suite, platform)
         cdata = data_munger.send(:normalized_common_data, key, default_key)

data/lib/kitchen/driver/base.rb

@@ -16,7 +16,7 @@ require_relative "../lazy_hash"
 require_relative "../logging"
 require_relative "../plugin_base"
 require_relative "../shell_out"
-require "time" unless defined?(Time)
+require "time" unless defined?(Time.zone_offset)
 
 module Kitchen
   module Driver
@@ -59,7 +59,7 @@ module Kitchen
       # Check system and configuration for common errors.
       #
       # @param state [Hash] mutable instance and driver state
-      # @returns [Boolean] Return true if a problem is found.
+      # @return [Boolean] Return true if a problem is found.
       def doctor(state)
         false
       end
@@ -108,7 +108,7 @@ module Kitchen
       # Cache directory that a driver could implement to inform the provisioner
       # that it can leverage it internally
       #
-      # @return path [String] a path of the cache directory
+      # @return [String] a path of the cache directory
       def cache_directory; end
 
       private

data/lib/kitchen/driver/dummy.rb

@@ -11,7 +11,7 @@
 # limitations under the License.
 
 require_relative "../../kitchen"
-require "time" unless defined?(Time)
+require "time" unless defined?(Time.zone_offset)
 
 module Kitchen
   module Driver
@@ -36,12 +36,18 @@ module Kitchen
         report(:create, state)
       end
 
-      # (see Base#setup)
+      # Reports that the setup action would have taken place.
+      #
+      # @param state [Hash] the instance state hash
+      # @return [void]
       def setup(state)
         report(:setup, state)
       end
 
-      # (see Base#verify)
+      # Reports that the verify action would have taken place.
+      #
+      # @param state [Hash] the instance state hash
+      # @return [void]
       def verify(state)
         report(:verify, state)
       end

data/lib/kitchen/errors.rb

@@ -59,6 +59,12 @@ module Kitchen
       arr.flatten
     end
 
+    # Creates an array of strings representing an exception's backtrace,
+    # wrapped in header and footer lines.
+    #
+    # @param exception [::Exception] an exception
+    # @return [Array<String>] a formatted backtrace, or an empty array when the
+    #   exception has none
     def self.formatted_backtrace(exception)
       if exception.backtrace.nil?
         []
@@ -100,7 +106,7 @@ module Kitchen
     # output when parsing the output from the commands like
     # kitchen diagnose.
     #
-    # @params lines [Array<String>] Array of lines that needs to be printed
+    # @param lines [Array<String>] Array of lines that needs to be printed
     def self.warn_on_stderr(lines)
       Array(lines).each do |line|
         line = Color.colorize(line, :blue) if Kitchen.tty?

data/lib/kitchen/generator/init.rb

@@ -19,6 +19,10 @@ require "rubygems/gem_runner"
 require "thor/group"
 
 module Kitchen
+  # Namespace for Thor generators that scaffold Test Kitchen configuration
+  # into a project.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
   module Generator
     # A project initialization generator, to help prepare a cookbook project
     # for testing with Kitchen.