test-kitchen 4.1.0 → 4.1.2

data/lib/kitchen/instance.rb

@@ -18,7 +18,7 @@
 require "benchmark" unless defined?(Benchmark)
 require "fileutils" unless defined?(FileUtils)
 require "securerandom" unless defined?(SecureRandom)
-require "time" unless defined?(Time)
+require "time" unless defined?(Time.zone_offset)
 
 module Kitchen
   # An instance of a suite running on a platform. A created instance may be a
@@ -60,7 +60,7 @@ module Kitchen
     # @return [LifecycleHooks] lifecycle hooks manager object
     attr_accessor :lifecycle_hooks
 
-    # @return [Provisioner::Base] provisioner object which will the setup
+    # @return [Provisioner::Base] provisioner object which will provide the setup
     #   and invocation instructions for configuration management and other
     #   automation tools
     attr_accessor :provisioner
@@ -83,9 +83,10 @@ module Kitchen
     # @option options [Platform] :platform the platform (**Required**)
     # @option options [Driver::Base] :driver the driver (**Required**)
     # @option options [Provisioner::Base] :provisioner the provisioner
+    #   (**Required**)
     # @option options [Transport::Base] :transport the transport
     #   (**Required**)
-    # @option options [Verifier] :verifier the verifier logger (**Required**)
+    # @option options [Verifier] :verifier the verifier (**Required**)
     # @option options [Logger] :logger the instance logger
     #   (default: Kitchen.logger)
     # @option options [StateFile] :state_file the state file object to use
@@ -343,10 +344,10 @@ module Kitchen
     # @api private
     attr_reader :state_file
 
-    # Validate the initial internal state of this object and raising an
+    # Validate the initial internal state of this object, raising an
     # exception if any preconditions are not met.
     #
-    # @param options[Hash] options hash passed into the constructor
+    # @param options [Hash] options hash passed into the constructor
     # @raise [ClientError] if any validations fail
     # @api private
     def validate_options(options)
@@ -375,7 +376,7 @@ module Kitchen
     end
 
     # Perform any final configuration or preparation needed for the driver
-    # object carry out its duties.
+    # object to carry out its duties.
     #
     # @api private
     def setup_driver
@@ -384,7 +385,7 @@ module Kitchen
     end
 
     # Perform any final configuration or preparation needed for the lifecycle hooks
-    # object carry out its duties.
+    # object to carry out its duties.
     #
     # @api private
     def setup_lifecycle_hooks
@@ -392,7 +393,7 @@ module Kitchen
     end
 
     # Perform any final configuration or preparation needed for the provisioner
-    # object carry out its duties.
+    # object to carry out its duties.
     #
     # @api private
     def setup_provisioner
@@ -401,7 +402,7 @@ module Kitchen
     end
 
     # Perform any final configuration or preparation needed for the transport
-    # object carry out its duties.
+    # object to carry out its duties.
     #
     # @api private
     def setup_transport
@@ -410,7 +411,7 @@ module Kitchen
     end
 
     # Perform any final configuration or preparation needed for the verifier
-    # object carry out its duties.
+    # object to carry out its duties.
     #
     # @api private
     def setup_verifier
@@ -653,6 +654,16 @@ module Kitchen
         @state_file = state_file
       end
 
+      # Runs one instance action, wrapping it in structured logging metadata
+      # and benchmarking, and serializing it when the action is registered as
+      # non-concurrent.
+      #
+      # @param what [Symbol] the action to run
+      # @yield the action body, given the current state hash
+      # @return [void]
+      # @raise [ActionFailed] if the state file could not be read or the action
+      #   did not complete
+      # @api private
       def call(what, &block)
         state = nil
         begin
@@ -774,12 +785,16 @@ module Kitchen
         end
       end
 
+      # The instance state lifecycle, ordered from least to most converged.
+      #
+      # @return [Array<Symbol>] ordered state names
+      # @api private
       TRANSITIONS = %i{destroy create converge setup verify}.freeze
 
-      # Determines the index of a state in the state lifecycle vector. Woah.
+      # Determines the index of a state in the state lifecycle vector. Whoa.
       #
       # @param transition [Symbol,#to_sym] a state
-      # @param [Integer] the index position
+      # @return [Integer] the index position
       # @api private
       def self.index(transition)
         if transition.nil?

data/lib/kitchen/lazy_hash.rb

@@ -77,7 +77,7 @@ module Kitchen
 
     # Returns a rendered value from the hash for the given key. If the key
     # can't be found, there are several options: With no other arguments, it
-    # will raise an KeyError exception; if default is given, then that will be
+    # will raise a KeyError exception; if default is given, then that will be
     # returned; if the optional code block is specified, then that will be run
     # and its result returned.
     #
@@ -115,7 +115,7 @@ module Kitchen
 
     # If no block provided, returns an enumerator over the keys and
     # rendered values in the underlying object.  If a block is
-    # provided, calls the block once for each [key, rendered_value]
+    # provided, calls the block once for each `[key, rendered_value]`
     # pair in the underlying object.
     #
     # @return [Enumerator, Array]

data/lib/kitchen/lifecycle_hook/base.rb

@@ -1,15 +1,22 @@
 require_relative "../platform_filter"
 
 module Kitchen
+  # Namespace for the lifecycle hook implementations that run user-defined
+  # commands around instance actions.
   class LifecycleHook
+    # Base class for a lifecycle hook implementation.
+    #
+    # A hook is bound to a single phase (for example `pre_create`) and decides,
+    # via `#should_run?`, whether it applies to the instance's platform before
+    # `#run` carries out the command.
     class Base
       # @return [Kitchen::LifecycleHooks]
       attr_reader :lifecycle_hooks
 
-      # return [String]
+      # @return [String] the lifecycle phase this hook is bound to
       attr_reader :phase
 
-      # return [Hash]
+      # @return [Hash] the raw hook configuration
       attr_reader :hook
 
       # @param lifecycle_hooks [Kitchen::LifecycleHooks]
@@ -21,7 +28,10 @@ module Kitchen
         @hook = hook
       end
 
-      # return [void]
+      # Carries out the hook's command. Subclasses must implement this.
+      #
+      # @return [void]
+      # @raise [NotImplementedError] unless overridden by a subclass
       def run
         raise NotImplementedError
       end
@@ -37,7 +47,7 @@ module Kitchen
         end
       end
 
-      # @return [Logger] the lifecycle hooks's logger
+      # @return [Logger] the lifecycle hook's logger
       #   otherwise
       # @api private
       def logger

data/lib/kitchen/lifecycle_hook/local.rb

@@ -4,6 +4,8 @@ require_relative "../logging"
 
 module Kitchen
   class LifecycleHook
+    # A lifecycle hook that runs a command on the workstation running Test
+    # Kitchen, with the instance's details exported as environment variables.
     class Local < Base
       include ShellOut
       include Logging

data/lib/kitchen/lifecycle_hook/remote.rb

@@ -3,6 +3,8 @@ require_relative "../errors"
 
 module Kitchen
   class LifecycleHook
+    # A lifecycle hook that runs a command on the instance itself, over the
+    # instance's configured transport.
     class Remote < Base
       # Execute a specific remote command hook.
       #
@@ -33,7 +35,7 @@ module Kitchen
 
       private
 
-      # return [String]
+      # @return [String] the command to run on the instance
       def command
         hook.fetch(:remote)
       end

data/lib/kitchen/loader/yaml.rb

@@ -21,6 +21,10 @@ require "psych" unless defined?(Psych)
 require "yaml" unless defined?(YAML)
 
 module Kitchen
+  # Namespace for configuration loaders, which turn on-disk configuration
+  # into the raw data hash Test Kitchen operates on.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
   module Loader
     # YAML file loader for Test Kitchen configuration. This class is
     # responsible for parsing the main YAML file and the local YAML if it
@@ -57,7 +61,7 @@ module Kitchen
       end
 
       # Reads, parses, and merges YAML configuration files and returns a Hash
-      # of tne merged data.
+      # of the merged data.
       #
       # @return [Hash] merged configuration data
       def read
@@ -99,7 +103,7 @@ module Kitchen
       # @api private
       attr_reader :global_config_file
 
-      # Performed a prioritized recursive merge of several source Hashes and
+      # Performs a prioritized recursive merge of several source Hashes and
       # returns a new merged Hash. There are 3 sources of configuration data:
       #
       # 1. local config
@@ -178,7 +182,7 @@ module Kitchen
       # Reads a file and returns its contents as a string.
       #
       # @param file [String] a path to a file
-      # @return [String] the files contents, or an empty string if the file
+      # @return [String] the file's contents, or an empty string if the file
       #   does not exist
       # @api private
       def read_file(file)
@@ -208,7 +212,7 @@ module Kitchen
         File.join(Dir.pwd, "kitchen.yml")
       end
 
-      # The absolute path to an hidden Kitchen config YAML file.
+      # The absolute path to a hidden Kitchen config YAML file.
       def dot_kitchen_yml
         File.join(Dir.pwd, ".kitchen.yml")
       end

data/lib/kitchen/logger.rb

@@ -18,11 +18,11 @@
 require "fileutils" unless defined?(FileUtils)
 require "json" unless defined?(JSON)
 require "logger" unless defined?(Logger)
-require "time" unless defined?(Time)
+require "time" unless defined?(Time.zone_offset)
 
 module Kitchen
   # Logging implementation for Kitchen. By default the console/stdout output
-  # will be displayed differently than the file log output. Therefor, this
+  # will be displayed differently than the file log output. Therefore, this
   # class wraps multiple loggers that conform to the stdlib `Logger` class
   # behavior.
   #
@@ -49,11 +49,11 @@ module Kitchen
     # Constructs a new logger.
     #
     # @param options [Hash] configuration for a new logger
-    # @option options [Symbol] :color color to use when when outputting
+    # @option options [Symbol] :color color to use when outputting
     #   messages
     # @option options [Integer] :level the logging severity threshold
     #   (default: `Kitchen::DEFAULT_LOG_LEVEL`)
-    # @option options [Boolean] whether to overwrite the log
+    # @option options [Boolean] :log_overwrite whether to overwrite the log
     #   when Test Kitchen runs. Only applies if the :logdev is a String.
     #   (default: `Kitchen::DEFAULT_LOG_OVERWRITE`)
     # @option options [String,IO] :logdev filepath String or IO object to be
@@ -111,61 +111,72 @@ module Kitchen
       private
 
       # @api private
-      # @!macro delegate_to_first_logger
-      #   @method $1()
       def delegate_to_first_logger(meth)
         define_method(meth) { |*args, &block| @sink_set.first(meth, *args, &block) }
       end
 
       # @api private
-      # @!macro delegate_to_all_loggers
-      #   @method $1()
       def delegate_to_all_loggers(meth)
         define_method(meth) { |*args, &block| @sink_set.all(meth, *args, &block) }
       end
     end
 
+    # @!method level
     # @return [Integer] the logging severity threshold
     # @see http://is.gd/Okuy5p
     delegate_to_first_logger :level
 
+    # @!method level=(level)
     # Sets the logging severity threshold.
     #
     # @param level [Integer] the logging severity threshold
     # @see http://is.gd/H1VBFH
     delegate_to_all_loggers :level=
 
+    # @!method progname
     # @return [String] program name to include in log messages
     # @see http://is.gd/5uHGK0
     delegate_to_first_logger :progname
 
+    # @!method progname=(progname)
     # Sets the program name to include in log messages.
     #
     # @param progname [String] the program name to include in log messages
     # @see http://is.gd/f2U5Xj
     delegate_to_all_loggers :progname=
 
+    # @!method datetime_format
     # @return [String] the date format being used
     # @see http://is.gd/btmFWJ
     delegate_to_first_logger :datetime_format
 
+    # @!method datetime_format=(format)
     # Sets the date format being used.
     #
     # @param format [String] the date format
     # @see http://is.gd/M36ml8
     delegate_to_all_loggers :datetime_format=
 
+    # @!method add(severity, message = nil, progname = nil, &block)
     # Log a message if the given severity is high enough.
     #
+    # @param severity [Integer] a stdlib Logger severity constant
+    # @param message [#to_s, nil] the message to log; when nil the block's
+    #   value is used, falling back to +progname+
+    # @param progname [#to_s, nil] used as the message when both +message+ and
+    #   a block are absent
+    # @yield evaluates to the message to log
     # @see http://is.gd/5opBW0
     delegate_to_all_loggers :add
 
+    # @!method <<(message)
     # Dump one or more messages to info.
     #
     # @param message [#to_s] the message to log
     # @see http://is.gd/BCp5KV
     delegate_to_all_loggers :<<
 
+    # @!method banner(message_or_progname = nil, &block)
     # Log a message with severity of banner (high level).
     #
     # @param message_or_progname [#to_s] the message to log. In the block
@@ -179,6 +190,7 @@ module Kitchen
     # @see http://is.gd/pYUCYU
     delegate_to_all_loggers :banner
 
+    # @!method debug(message_or_progname = nil, &block)
     # Log a message with severity of debug.
     #
     # @param message_or_progname [#to_s] the message to log. In the block
@@ -192,11 +204,13 @@ module Kitchen
     # @see http://is.gd/Re97Zp
     delegate_to_all_loggers :debug
 
+    # @!method debug?
     # @return [true,false] whether or not the current severity level
     #   allows for the printing of debug messages
     # @see http://is.gd/Iq08xB
     delegate_to_first_logger :debug?
 
+    # @!method info(message_or_progname = nil, &block)
     # Log a message with severity of info.
     #
     # @param message_or_progname [#to_s] the message to log. In the block
@@ -210,11 +224,13 @@ module Kitchen
     # @see http://is.gd/pYUCYU
     delegate_to_all_loggers :info
 
+    # @!method info?
     # @return [true,false] whether or not the current severity level
     #   allows for the printing of info messages
     # @see http://is.gd/lBtJkT
     delegate_to_first_logger :info?
 
+    # @!method error(message_or_progname = nil, &block)
     # Log a message with severity of error.
     #
     # @param message_or_progname [#to_s] the message to log. In the block
@@ -228,11 +244,13 @@ module Kitchen
     # @see http://is.gd/mLwYMl
     delegate_to_all_loggers :error
 
+    # @!method error?
     # @return [true,false] whether or not the current severity level
     #   allows for the printing of error messages
     # @see http://is.gd/QY19JL
     delegate_to_first_logger :error?
 
+    # @!method warn(message_or_progname = nil, &block)
     # Log a message with severity of warn.
     #
     # @param message_or_progname [#to_s] the message to log. In the block
@@ -246,11 +264,13 @@ module Kitchen
     # @see http://is.gd/PX9AIS
     delegate_to_all_loggers :warn
 
+    # @!method warn?
     # @return [true,false] whether or not the current severity level
     #   allows for the printing of warn messages
     # @see http://is.gd/Gdr4lD
     delegate_to_first_logger :warn?
 
+    # @!method fatal(message_or_progname = nil, &block)
     # Log a message with severity of fatal.
     #
     # @param message_or_progname [#to_s] the message to log. In the block
@@ -264,11 +284,13 @@ module Kitchen
     # @see http://is.gd/5ElFPK
     delegate_to_all_loggers :fatal
 
+    # @!method fatal?
     # @return [true,false] whether or not the current severity level
     #   allows for the printing of fatal messages
     # @see http://is.gd/7PgwRl
     delegate_to_first_logger :fatal?
 
+    # @!method unknown(message_or_progname = nil, &block)
     # Log a message with severity of unknown.
     #
     # @param message_or_progname [#to_s] the message to log. In the block
@@ -282,6 +304,7 @@ module Kitchen
     # @see http://is.gd/Y4hqpf
     delegate_to_all_loggers :unknown
 
+    # @!method close
     # Close the logging devices.
     #
     # @see http://is.gd/b13cVn
@@ -341,10 +364,26 @@ module Kitchen
         @loggers = loggers
       end
 
+      # Invokes a method on the first configured sink only.
+      #
+      # @param meth [Symbol] the method to invoke
+      # @param args [Array] arguments to forward to the sink
+      # @yield an optional block forwarded to the sink
+      # @return [Object] the first sink's return value
+      # @api private
       def first(meth, *args, &block)
         @loggers.first.public_send(meth, *args, &block)
       end
 
+      # Invokes a method on every configured sink. A given block is memoized so
+      # that an expensive message block is evaluated at most once, no matter how
+      # many sinks consume it.
+      #
+      # @param meth [Symbol] the method to invoke
+      # @param args [Array] arguments to forward to each sink
+      # @yield an optional block forwarded to each sink
+      # @return [Object] the last sink's return value
+      # @api private
       def all(meth, *args, &block)
         result = nil
         block = memoized_block(block) if block
@@ -449,6 +488,13 @@ module Kitchen
         @line_handler = line_handler
       end
 
+      # Appends a chunk of stream output to the buffer, emitting each complete
+      # newline-terminated line to the line handler.
+      #
+      # @param msg [String] a chunk of stream output, which may contain zero or
+      #   more complete lines
+      # @return [void]
+      # @api private
       def <<(msg)
         @buffer += msg
         flush_lines
@@ -470,6 +516,12 @@ module Kitchen
         @logger = logger
       end
 
+      # Routes an already-prefixed stream line to the logger call matching its
+      # prefix, stripping the prefix before logging.
+      #
+      # @param line [String] a single line of prefixed stream output
+      # @return [void]
+      # @api private
       def format(line)
         case line
         when /^-----> / then log_line(:banner, line.gsub(/^[ >-]{6} /, ""))
@@ -540,6 +592,11 @@ module Kitchen
     class StructuredLogdevLogger
       include ::Logger::Severity
 
+      # Maps stdlib Logger severity constants to their lowercase string names
+      # as they appear in emitted JSON events.
+      #
+      # @return [Hash{Integer => String}] severity constant to name mapping
+      # @api private
       SEVERITY_NAMES = {
         DEBUG => "debug",
         INFO => "info",
@@ -562,6 +619,17 @@ module Kitchen
         @mutex = Mutex.new
       end
 
+      # Writes a log event if the given severity meets the current level.
+      #
+      # @param severity [Integer] a stdlib Logger severity constant
+      # @param message [#to_s, nil] the message to log; when nil the block's
+      #   value is used, falling back to +progname+
+      # @param progname [#to_s, nil] used as the message when both +message+ and
+      #   a block are absent
+      # @yield evaluates to the message to log, only when the severity is high
+      #   enough to be recorded
+      # @return [true] always, once the event has been considered
+      # @api private
       def add(severity, message = nil, progname = nil)
         severity ||= UNKNOWN
         return true if severity < level
@@ -574,40 +642,102 @@ module Kitchen
         write_event(severity, message, "log")
       end
 
+      # Appends raw stream output, emitting a structured event per complete
+      # line.
+      #
+      # @param msg [String] a chunk of stream output
+      # @return [void]
+      # @api private
       def <<(msg)
         line_buffer << msg
       end
 
+      # Writes a banner event at info severity.
+      #
+      # @param msg [#to_s, nil] the message to log; when nil the block's value is
+      #   used
+      # @yield evaluates to the message to log
+      # @return [void]
+      # @api private
       def banner(msg = nil)
         message = block_given? ? yield : msg
         write_event(INFO, message, "banner") unless INFO < level
       end
 
+      # Writes a stream event at the given severity.
+      #
+      # @param severity [Integer, Symbol] a stdlib Logger severity constant or its
+      #   symbol name
+      # @param msg [#to_s] the message to log
+      # @return [void]
+      # @api private
       def stream(severity, msg)
         severity = severity_const(severity)
         write_event(severity, msg, "stream") unless severity < level
       end
 
+      # Writes a log event at debug severity.
+      #
+      # @param msg [#to_s, nil] the message to log; when nil the block's value is
+      #   used
+      # @yield evaluates to the message to log
+      # @return [true]
+      # @api private
       def debug(msg = nil, &block)
         add(DEBUG, msg, nil, &block)
       end
 
+      # Writes a log event at info severity.
+      #
+      # @param msg [#to_s, nil] the message to log; when nil the block's value is
+      #   used
+      # @yield evaluates to the message to log
+      # @return [true]
+      # @api private
       def info(msg = nil, &block)
         add(INFO, msg, nil, &block)
       end
 
+      # Writes a log event at warn severity.
+      #
+      # @param msg [#to_s, nil] the message to log; when nil the block's value is
+      #   used
+      # @yield evaluates to the message to log
+      # @return [true]
+      # @api private
       def warn(msg = nil, &block)
         add(WARN, msg, nil, &block)
       end
 
+      # Writes a log event at error severity.
+      #
+      # @param msg [#to_s, nil] the message to log; when nil the block's value is
+      #   used
+      # @yield evaluates to the message to log
+      # @return [true]
+      # @api private
       def error(msg = nil, &block)
         add(ERROR, msg, nil, &block)
       end
 
+      # Writes a log event at fatal severity.
+      #
+      # @param msg [#to_s, nil] the message to log; when nil the block's value is
+      #   used
+      # @yield evaluates to the message to log
+      # @return [true]
+      # @api private
       def fatal(msg = nil, &block)
         add(FATAL, msg, nil, &block)
       end
 
+      # Writes a log event at unknown severity.
+      #
+      # @param msg [#to_s, nil] the message to log; when nil the block's value is
+      #   used
+      # @yield evaluates to the message to log
+      # @return [true]
+      # @api private
       def unknown(msg = nil, &block)
         add(UNKNOWN, msg, nil, &block)
       end
@@ -632,6 +762,10 @@ module Kitchen
         level <= FATAL
       end
 
+      # Closes the underlying log device if it is open and supports closing.
+      #
+      # @return [void]
+      # @api private
       def close
         return unless @logdev.respond_to?(:close)
 

data/lib/kitchen/logging.rb

@@ -25,7 +25,7 @@ module Kitchen
 
       # @api private
       # @!macro logger_method
-      #   @method $1($2)
+      #   @method $1(message_or_progname = nil, &block)
       #   Log a message with severity of $1
       #   @param message_or_progname [#to_s] the message to log. In the block
       #     form, this is the progname to use in the log message.

data/lib/kitchen/login_command.rb

@@ -42,6 +42,9 @@ module Kitchen
       @options = options
     end
 
+    # Returns the arguments in the form expected by `Kernel#exec`.
+    #
+    # @return [Array] the command, its arguments, and the options hash
     def exec_args
       [command, *arguments, options]
     end

data/lib/kitchen/metadata_chopper.rb

@@ -33,7 +33,7 @@ module Kitchen
       [mc[:name], mc[:version]]
     end
 
-    # Creates a new instances and loads in the contents of the metadata.rb
+    # Creates a new instance and loads in the contents of the metadata.rb
     # file. If you value your life, you may want to avoid reading the
     # implementation.
     #
@@ -42,6 +42,13 @@ module Kitchen
       instance_eval(File.read(metadata_file), metadata_file)
     end
 
+    # Captures any attribute call made while evaluating the metadata file,
+    # storing its first argument under the attribute name.
+    #
+    # @param meth [Symbol] the attribute name being set
+    # @param args [Array] the attribute's arguments; the first becomes the value
+    # @return [Object] the stored value
+    # @api private
     def method_missing(meth, *args, &_block)
       self[meth] = args.first
     end