test-kitchen 4.1.1 → 4.1.2

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

@@ -22,7 +22,7 @@ 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

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.