test-kitchen 1.2.1 → 1.3.0

data/lib/kitchen/diagnostic.rb

@@ -16,7 +16,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'kitchen/util'
+require "kitchen/util"
+require "kitchen/version"
 
 module Kitchen
 
@@ -26,12 +27,23 @@ module Kitchen
   # @author Fletcher Nichol <fnichol@nichol.ca>
   class Diagnostic
 
+    # Constructs a new Diagnostic object with an optional loader and optional
+    # instances array.
+    #
+    # @param options [Hash] optional configuration
+    # @option options [#diagnose,Hash] :loader a loader instance that responds
+    #   to `#diagnose` or an error Hash
+    # @option options [Array<#diagnose>,Hash] :instances an Array of instances
+    #   that respond to `#diagnose` or an error Hash
     def initialize(options = {})
       @loader = options.fetch(:loader, nil)
       @instances = options.fetch(:instances, [])
       @result = Hash.new
     end
 
+    # Returns a Hash with stringified keys containing diagnostic information.
+    #
+    # @return [Hash] a configuration Hash
     def read
       prepare_common
       prepare_loader
@@ -42,13 +54,31 @@ module Kitchen
 
     private
 
-    attr_reader :result, :loader, :instances
+    # @return [Hash] a result hash
+    # @api private
+    attr_reader :result
 
+    # @return [#diagnose,Hash] a loader instance that responds to `#diagnose`
+    #   or an error Hash
+    # @api private
+    attr_reader :loader
+
+    # @return [Array<#diagnose>,Hash] an Array of instances that respond to
+    #   `#diagnose` or an error Hash
+    # @api private
+    attr_reader :instances
+
+    # Adds common information to the result Hash.
+    #
+    # @api private
     def prepare_common
-      result[:timestamp] = Time.now.gmtime
+      result[:timestamp] = Time.now.gmtime.to_s
       result[:kitchen_version] = Kitchen::VERSION
     end
 
+    # Adds loader information to the result Hash.
+    #
+    # @api private
     def prepare_loader
       if error_hash?(loader)
         result[:loader] = loader
@@ -57,6 +87,9 @@ module Kitchen
       end
     end
 
+    # Adds instance information to the result Hash.
+    #
+    # @api private
     def prepare_instances
       result[:instances] = Hash.new
       if error_hash?(instances)
@@ -66,8 +99,14 @@ module Kitchen
       end
     end
 
+    # Determins whether or not the object is an error hash. An error hash is
+    # defined as a Hash containing an `:error` key.
+    #
+    # @param obj [Object] an object
+    # @return [true,false] whether or not the object is an error hash
+    # @api private
     def error_hash?(obj)
-      obj.is_a?(Hash) && obj.has_key?(:error)
+      obj.is_a?(Hash) && obj.key?(:error)
     end
   end
 end

data/lib/kitchen/driver.rb

@@ -16,7 +16,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'thor/util'
+require "thor/util"
 
 module Kitchen
 
@@ -40,7 +40,7 @@ module Kitchen
       first_load = require("kitchen/driver/#{plugin}")
 
       str_const = Thor::Util.camel_case(plugin)
-      klass = self.const_get(str_const)
+      klass = const_get(str_const)
       object = klass.new(config)
       object.verify_dependencies if first_load
       object
@@ -48,8 +48,8 @@ module Kitchen
       raise
     rescue LoadError, NameError
       raise ClientError,
-        "Could not load the '#{plugin}' driver from the load path." +
-          " Please ensure that your driver is installed as a gem or included" +
+        "Could not load the '#{plugin}' driver from the load path." \
+          " Please ensure that your driver is installed as a gem or included" \
           " in your Gemfile if using Bundler."
     end
   end

data/lib/kitchen/driver/base.rb

@@ -16,9 +16,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'thor/util'
+require "thor/util"
 
-require 'kitchen/lazy_hash'
+require "kitchen/lazy_hash"
 
 module Kitchen
 
@@ -30,78 +30,58 @@ module Kitchen
     class Base
 
       include ShellOut
+      include Configurable
       include Logging
 
-      attr_accessor :instance
-
-      class << self
-        attr_reader :serial_actions
-      end
-
+      # Creates a new Driver object using the provided configuration data
+      # which will be merged with any default configuration.
+      #
+      # @param config [Hash] provided driver configuration
       def initialize(config = {})
-        @config = LazyHash.new(config, self)
-        self.class.defaults.each do |attr, value|
-          @config[attr] = value unless @config.has_key?(attr)
-        end
-      end
-
-      def validate_config!
-        Array(self.class.validations).each do |tuple|
-          tuple.last.call(tuple.first, config[tuple.first], self)
-        end
+        init_config(config)
       end
 
       # Returns the name of this driver, suitable for display in a CLI.
       #
       # @return [String] name of this driver
       def name
-        self.class.name.split('::').last
-      end
-
-      # Provides hash-like access to configuration keys.
-      #
-      # @param attr [Object] configuration key
-      # @return [Object] value at configuration key
-      def [](attr)
-        config[attr]
-      end
-
-      # Returns an array of configuration keys.
-      #
-      # @return [Array] array of configuration keys
-      def config_keys
-        config.keys
+        self.class.name.split("::").last
       end
 
       # Creates an instance.
       #
       # @param state [Hash] mutable instance and driver state
       # @raise [ActionFailed] if the action could not be completed
-      def create(state) ; end
+      def create(state) # rubocop:disable Lint/UnusedMethodArgument
+      end
 
       # Converges a running instance.
       #
       # @param state [Hash] mutable instance and driver state
       # @raise [ActionFailed] if the action could not be completed
-      def converge(state) ; end
+      def converge(state) # rubocop:disable Lint/UnusedMethodArgument
+      end
 
       # Sets up an instance.
       #
       # @param state [Hash] mutable instance and driver state
       # @raise [ActionFailed] if the action could not be completed
-      def setup(state) ; end
+      def setup(state) # rubocop:disable Lint/UnusedMethodArgument
+      end
 
       # Verifies a converged instance.
       #
       # @param state [Hash] mutable instance and driver state
       # @raise [ActionFailed] if the action could not be completed
-      def verify(state) ; end
+      def verify(state) # rubocop:disable Lint/UnusedMethodArgument
+      end
 
       # Destroys an instance.
       #
       # @param state [Hash] mutable instance and driver state
       # @raise [ActionFailed] if the action could not be completed
-      def destroy(state) ; end
+      def destroy(state) # rubocop:disable Lint/UnusedMethodArgument
+      end
 
       # Returns the shell command that will log into an instance.
       #
@@ -109,7 +89,7 @@ module Kitchen
       # @return [LoginCommand] an object containing the array of command line
       #   tokens and exec options to be used in a fork/exec
       # @raise [ActionFailed] if the action could not be completed
-      def login_command(state)
+      def login_command(state) # rubocop:disable Lint/UnusedMethodArgument
         raise ActionFailed, "Remote login is not supported in this driver."
       end
 
@@ -120,36 +100,80 @@ module Kitchen
       #
       # @raise [UserError] if the driver will not be able to perform or if a
       #   documented dependency is missing from the system
-      def verify_dependencies ; end
+      def verify_dependencies
+      end
 
-      # Returns a Hash of configuration and other useful diagnostic information.
-      #
-      # @return [Hash] a diagnostic hash
-      def diagnose
-        result = Hash.new
-        config_keys.sort.each { |k| result[k] = config[k] }
-        result
+      class << self
+        # @return [Array<Symbol>] an array of action method names that cannot
+        #   be run concurrently and must be run in serial via a shared mutex
+        attr_reader :serial_actions
       end
 
-      protected
+      # Registers certain driver actions that cannot be safely run concurrently
+      # in threads across multiple instances. Typically this might be used
+      # for create or destroy actions that use an underlying resource that
+      # cannot be used at the same time.
+      #
+      # A shared mutex for this driver object will be used to synchronize all
+      # registered methods.
+      #
+      # @example a single action method that cannot be run concurrently
+      #
+      #   no_parallel_for :create
+      #
+      # @example multiple action methods that cannot be run concurrently
+      #
+      #   no_parallel_for :create, :destroy
+      #
+      # @param methods [Array<Symbol>] one or more actions as symbols
+      # @raise [ClientError] if any method is not a valid action method name
+      def self.no_parallel_for(*methods)
+        action_methods = [:create, :converge, :setup, :verify, :destroy]
 
-      attr_reader :config
+        Array(methods).each do |meth|
+          next if action_methods.include?(meth)
 
-      ACTION_METHODS = %w{create converge setup verify destroy}.
-        map(&:to_sym).freeze
+          raise ClientError, "##{meth} is not a valid no_parallel_for method"
+        end
 
+        @serial_actions ||= []
+        @serial_actions += methods
+      end
+
+      private
+
+      # Returns a suitable logger to use for output.
+      #
+      # @return [Kitchen::Logger] a logger
       def logger
         instance ? instance.logger : Kitchen.logger
       end
 
+      # Intercepts any bare #puts calls in subclasses and issues an INFO log
+      # event instead.
+      #
+      # @param msg [String] message string
       def puts(msg)
         info(msg)
       end
 
+      # Intercepts any bare #print calls in subclasses and issues an INFO log
+      # event instead.
+      #
+      # @param msg [String] message string
       def print(msg)
         info(msg)
       end
 
+      # Delegates to Kitchen::ShellOut.run_command, overriding some default
+      # options:
+      #
+      # * `:use_sudo` defaults to the value of `config[:use_sudo]` in the
+      #   Driver object
+      # * `:log_subject` defaults to a String representation of the Driver's
+      #   class name
+      #
+      # @see ShellOut#run_command
       def run_command(cmd, options = {})
         base_options = {
           :use_sudo => config[:use_sudo],
@@ -158,70 +182,11 @@ module Kitchen
         super(cmd, base_options)
       end
 
-      def busser_setup_cmd
-        busser.setup_cmd
-      end
-
-      def busser_sync_cmd
-        busser.sync_cmd
-      end
-
-      def busser_run_cmd
-        busser.run_cmd
-      end
-
+      # Returns the Busser object associated with the driver.
+      #
+      # @return [Busser] a busser
       def busser
-        @busser ||= begin
-          raise ClientError, "Instance must be set for Driver" if instance.nil?
-          instance.busser
-        end
-      end
-
-      def self.defaults
-        @defaults ||= Hash.new.merge(super_defaults)
-      end
-
-      def self.super_defaults
-        klass = self.superclass
-
-        if klass.respond_to?(:defaults)
-          klass.defaults
-        else
-          Hash.new
-        end
-      end
-
-      def self.default_config(attr, value = nil, &block)
-        defaults[attr] = block_given? ? block : value
-      end
-
-      def self.validations
-        @validations
-      end
-
-      def self.required_config(attr, &block)
-        @validations = [] if @validations.nil?
-        if ! block_given?
-          klass = self
-          block = lambda do |attr, value, driver|
-            if value.nil? || value.to_s.empty?
-              attribute = "#{klass}#{driver.instance.to_str}#config[:#{attr}]"
-              raise UserError, "#{attribute} cannot be blank"
-            end
-          end
-        end
-        @validations << [attr, block]
-      end
-
-      def self.no_parallel_for(*methods)
-        Array(methods).each do |meth|
-          if ! ACTION_METHODS.include?(meth)
-            raise ClientError, "##{meth} is not a valid no_parallel_for method"
-          end
-        end
-
-        @serial_actions ||= []
-        @serial_actions += methods
+        instance.busser
       end
     end
   end

data/lib/kitchen/driver/dummy.rb

@@ -2,7 +2,7 @@
 #
 # Author:: Fletcher Nichol (<fnichol@nichol.ca>)
 #
-# Copyright (C) 2012, Fletcher Nichol
+# Copyright (C) 2012, 2013, 2014 Fletcher Nichol
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,13 +16,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'kitchen'
+require "kitchen"
 
 module Kitchen
 
   module Driver
 
-    # Dummy driver for Kitchen.
+    # Dummy driver for Kitchen. This driver does nothing but report what would
+    # happen if this driver did anything of consequence. As a result it may
+    # be a useful driver to use when debugging or developing new features or
+    # plugins.
     #
     # @author Fletcher Nichol <fnichol@nichol.ca>
     class Dummy < Kitchen::Driver::Base
@@ -30,23 +33,28 @@ module Kitchen
       default_config :sleep, 0
       default_config :random_failure, false
 
+      # (see Base#create)
       def create(state)
         state[:my_id] = "#{instance.name}-#{Time.now.to_i}"
         report(:create, state)
       end
 
+      # (see Base#converge)
       def converge(state)
         report(:converge, state)
       end
 
+      # (see Base#setup)
       def setup(state)
         report(:setup, state)
       end
 
+      # (see Base#verify)
       def verify(state)
         report(:verify, state)
       end
 
+      # (see Base#destroy)
       def destroy(state)
         report(:destroy, state)
         state.delete(:my_id)
@@ -54,25 +62,45 @@ module Kitchen
 
       private
 
+      # Report what action is taking place, sleeping if so configured, and
+      # possibly fail randomly.
+      #
+      # @param action [Symbol] the action currently taking place
+      # @param state [Hash] the state hash
+      # @api private
       def report(action, state)
         what = action.capitalize
         info("[Dummy] #{what} on instance=#{instance} with state=#{state}")
         sleep_if_set
-        random_failure_if_set(action)
+        failure_if_set(action)
         debug("[Dummy] #{what} completed (#{config[:sleep]}s).")
       end
 
+      # Sleep for a period of time, if a value is set in the config.
+      #
+      # @api private
       def sleep_if_set
         sleep(config[:sleep].to_f) if config[:sleep].to_f > 0.0
       end
 
-      def random_failure_if_set(action)
-        if config[:random_failure] && randomly_fail?
+      # Simulate a failure in an action, if set in the config.
+      #
+      # @param action [Symbol] the action currently taking place
+      # @api private
+      def failure_if_set(action)
+        if config[:"fail_#{action}"]
+          debug("[Dummy] Failure for action ##{action}.")
+          raise ActionFailed, "Action ##{action} failed for #{instance.to_str}."
+        elsif config[:random_failure] && randomly_fail?
           debug("[Dummy] Random failure for action ##{action}.")
           raise ActionFailed, "Action ##{action} failed for #{instance.to_str}."
         end
       end
 
+      # Determine whether or not to randomly fail.
+      #
+      # @return [true, false]
+      # @api private
       def randomly_fail?
         [true, false].sample
       end