test-kitchen 1.2.1 → 1.3.0

data/lib/kitchen/logging.rb

@@ -18,12 +18,39 @@
 
 module Kitchen
 
+  # Mixin module that delegates logging methods to a local `#logger`.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
   module Logging
 
-    %w{banner debug info warn error fatal}.map(&:to_sym).each do |meth|
-      define_method(meth) do |*args|
-        logger.public_send(meth, *args)
+    class << self
+
+      private
+
+      # @api private
+      # @!macro logger_method
+      #   @method $1($2)
+      #   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.
+      #   @yield evaluates to the message to log. This is not evaluated unless
+      #     the logger's level is sufficient to log the message. This allows
+      #     you to create potentially expensive logging messages that are
+      #     only called when the logger is configured to show them.
+      #   @return [nil,true] when the given severity is not high enough (for
+      #     this particular logger), log no message, and return true
+      def logger_method(meth)
+        define_method(meth) do |*args|
+          logger.public_send(meth, *args)
+        end
       end
     end
+
+    logger_method :banner
+    logger_method :debug
+    logger_method :info
+    logger_method :warn
+    logger_method :error
+    logger_method :fatal
   end
 end

data/lib/kitchen/login_command.rb

@@ -24,10 +24,19 @@ module Kitchen
   # @author Fletcher Nichol <fnichol@nichol.ca>
   class LoginCommand
 
-    attr_reader :cmd_array, :options
+    # @return [Array] array of login command arguments
+    attr_reader :cmd_array
 
+    # @return [Hash] options hash, passed to `Kernel#exec`
+    attr_reader :options
+
+    # Constructs a new LoginCommand instance.
+    #
+    # @param cmd_array [Array] array of login command arguments
+    # @param options [Hash] options hash, passed to `Kernel#exec`
+    # @see http://www.ruby-doc.org/core-2.1.2/Kernel.html#method-i-exec
     def initialize(cmd_array, options = {})
-      @cmd_array = cmd_array
+      @cmd_array = Array(cmd_array)
       @options = options
     end
   end

data/lib/kitchen/metadata_chopper.rb

@@ -42,10 +42,10 @@ module Kitchen
     #
     # @param metadata_file [String] path to a metadata.rb file
     def initialize(metadata_file)
-      eval(IO.read(metadata_file), nil, metadata_file)
+      instance_eval(IO.read(metadata_file), metadata_file)
     end
 
-    def method_missing(meth, *args, &block)
+    def method_missing(meth, *args, &_block)
       self[meth] = args.first
     end
   end

data/lib/kitchen/provisioner.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,12 +40,12 @@ module Kitchen
       require("kitchen/provisioner/#{plugin}")
 
       str_const = Thor::Util.camel_case(plugin)
-      klass = self.const_get(str_const)
+      klass = const_get(str_const)
       klass.new(config)
     rescue LoadError, NameError
       raise ClientError,
-        "Could not load the '#{plugin}' provisioner from the load path." +
-          " Please ensure that your provisioner is installed as a gem or" +
+        "Could not load the '#{plugin}' provisioner from the load path." \
+          " Please ensure that your provisioner is installed as a gem or" \
           " included in your Gemfile if using Bundler."
     end
   end

data/lib/kitchen/provisioner/base.rb

@@ -16,8 +16,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'kitchen/lazy_hash'
-
 module Kitchen
 
   module Provisioner
@@ -27,53 +25,95 @@ module Kitchen
     # @author Fletcher Nichol <fnichol@nichol.ca>
     class Base
 
+      include Configurable
       include Logging
 
-      attr_accessor :instance
+      default_config :root_path, "/tmp/kitchen"
+      default_config :sudo, true
 
+      expand_path_for :test_base_path
+
+      # Constructs a new provisioner by providing a configuration hash.
+      #
+      # @param config [Hash] initial provided 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
+        init_config(config)
       end
 
-      def instance=(instance)
-        @instance = instance
-        expand_paths!
+      # Performs any final configuration required for the provisioner to do its
+      # work. A reference to an Instance is required as configuration dependant
+      # data may need access through an Instance. This also acts as a hook
+      # point where the object may wish to perform other last minute checks,
+      # valiations, or configuration expansions.
+      #
+      # @param instance [Instance] an associated instance
+      # @return [self] itself, used for chaining
+      # @raise [ClientError] if instance parameter is nil
+      def finalize_config!(instance)
+        super
         load_needed_dependencies!
+        self
       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
+        self.class.name.split("::").last
       end
 
-      # Provides hash-like access to configuration keys.
+      # Generates a command string which will install and configure the
+      # provisioner software on an instance. If no work is required, then `nil`
+      # will be returned.
       #
-      # @param attr [Object] configuration key
-      # @return [Object] value at configuration key
-      def [](attr)
-        config[attr]
+      # @return [String] a command string
+      def install_command
       end
 
-      # Returns an array of configuration keys.
+      # Generates a command string which will perform any data initialization
+      # or configuration required after the provisioner software is installed
+      # but before the sandbox has been transferred to the instance. If no work
+      # is required, then `nil` will be returned.
       #
-      # @return [Array] array of configuration keys
-      def config_keys
-        config.keys
+      # @return [String] a command string
+      def init_command
       end
 
-      def init_command ; end
-
-      def install_command ; end
-
-      def prepare_command ; end
+      # Generates a command string which will perform any commands or
+      # configuration required just before the main provisioner run command but
+      # after the sandbox has been transferred to the instance. If no work is
+      # required, then `nil` will be returned.
+      #
+      # @return [String] a command string
+      def prepare_command
+      end
 
-      def run_command ; end
+      # Generates a command string which will invoke the main provisioner
+      # command on the prepared instance. If no work is required, then `nil`
+      # will be returned.
+      #
+      # @return [String] a command string
+      def run_command
+      end
 
+      # Creates a temporary directory on the local workstation into which
+      # provisioner related files and directories can be copied or created. The
+      # contents of this directory will be copied over to the instance before
+      # invoking the provisioner's run command. After this method completes, it
+      # is expected that the contents of the sandbox is complete and ready for
+      # copy to the remote instance.
+      #
+      # **Note:** any subclasses would be well advised to call super first when
+      # overriding this method, for example:
+      #
+      # @example overriding `#create_sandbox`
+      #
+      #   class MyProvisioner < Kitchen::Provisioner::Base
+      #     def create_sandbox
+      #       super
+      #       # any further file copies, preparations, etc.
+      #     end
+      #   end
       def create_sandbox
         @sandbox_path = Dir.mktmpdir("#{instance.name}-sandbox-")
         File.chmod(0755, sandbox_path)
@@ -81,12 +121,21 @@ module Kitchen
         debug("Creating local sandbox in #{sandbox_path}")
       end
 
+      # Returns the absolute path to the sandbox directory or raises an
+      # 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
+      #   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 " +
+        @sandbox_path || (raise ClientError, "Sandbox directory has not yet " \
+          "been created. Please run #{self.class}#create_sandox before " \
           "trying to access the path.")
       end
 
+      # Deletes the sandbox path. Without calling this method, the sandbox path
+      # will persist after the process terminates. In other words, cleanup is
+      # explicit. This method is safe to call multiple times.
       def cleanup_sandbox
         return if sandbox_path.nil?
 
@@ -94,91 +143,46 @@ module Kitchen
         FileUtils.rmtree(sandbox_path)
       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
-      end
-
-      def calculate_path(path, type = :directory)
-        base = config[:test_base_path]
-        candidates = []
-        candidates << File.join(base, instance.suite.name, path)
-        candidates << File.join(base, path)
-        candidates << File.join(Dir.pwd, path)
-
-        candidates.find do |c|
-          type == :directory ? File.directory?(c) : File.file?(c)
-        end
-      end
-
-      protected
-
-      attr_reader :config
-
-      def expand_paths!
-        expanded_paths = LazyHash.new(self.class.expanded_paths, self).to_hash
+      private
 
-        expanded_paths.each do |key, should_expand|
-          if should_expand && !config[key].nil?
-            config[key] = File.expand_path(config[key], config[:kitchen_root])
-          end
-        end
+      # Loads any required third party Ruby libraries or runs any shell out
+      # commands to prepare the provisioner. This method will be called in the
+      # context of the main thread of execution and so does not necessarily
+      # have to be thread safe.
+      #
+      # **Note:** any subclasses overriding this method would be well advised
+      # to call super when overriding this method, for example:
+      #
+      # @example overriding `#load_needed_dependencies!`
+      #
+      #   class MyProvisioner < Kitchen::Provisioner::Base
+      #     def load_needed_dependencies!
+      #       super
+      #       # any further work
+      #     end
+      #   end
+      #
+      # @raise [ClientError] if any library loading fails or any of the
+      #   dependency requirements cannot be satisfied
+      # @api private
+      def load_needed_dependencies!
       end
 
-      def load_needed_dependencies! ; end
-
+      # @return [Logger] the instance's logger or Test Kitchen's common logger
+      #   otherwise
+      # @api private
       def logger
         instance ? instance.logger : Kitchen.logger
       end
 
+      # Conditionally prefixes a command with a sudo command.
+      #
+      # @param command [String] command to be prefixed
+      # @return [String] the command, conditionaly prefixed with sudo
+      # @api private
       def sudo(script)
         config[:sudo] ? "sudo -E #{script}" : script
       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.expanded_paths
-        @expanded_paths ||= Hash.new.merge(super_expanded_paths)
-      end
-
-      def self.super_expanded_paths
-        klass = self.superclass
-
-        if klass.respond_to?(:expanded_paths)
-          klass.expanded_paths
-        else
-          Hash.new
-        end
-      end
-
-      def self.expand_path_for(attr, value = true, &block)
-        expanded_paths[attr] = block_given? ? block : value
-      end
-
-      default_config :root_path, "/tmp/kitchen"
-      default_config :sudo, true
-
-      expand_path_for :test_base_path
     end
   end
 end

data/lib/kitchen/provisioner/chef/berkshelf.rb

@@ -16,8 +16,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'kitchen/errors'
-require 'kitchen/logging'
+require "kitchen/errors"
+require "kitchen/logging"
 
 module Kitchen
 
@@ -33,16 +33,29 @@ module Kitchen
 
         include Logging
 
+        # Creates a new cookbook resolver.
+        #
+        # @param berksfile [String] path to a Berksfile
+        # @param path [String] path in which to vendor the resulting
+        #   cookbooks
+        # @param logger [Kitchen::Logger] a logger to use for output, defaults
+        #   to `Kitchen.logger`
         def initialize(berksfile, path, logger = Kitchen.logger)
           @berksfile  = berksfile
           @path       = path
           @logger     = logger
         end
 
+        # Loads the library code required to use the resolver.
+        #
+        # @param logger [Kitchen::Logger] a logger to use for output, defaults
+        #   to `Kitchen.logger`
         def self.load!(logger = Kitchen.logger)
           load_berkshelf!(logger)
         end
 
+        # Performs the cookbook resolution and vendors the resulting cookbooks
+        # in the desired path.
         def resolve
           version = ::Berkshelf::VERSION
           info("Resolving cookbook dependencies with Berkshelf #{version}...")
@@ -54,17 +67,32 @@ module Kitchen
               FileUtils.rm_rf(path)
               ::Berkshelf::Berksfile.from_file(berksfile).vendor(path)
             else
-              ::Berkshelf::Berksfile.from_file(berksfile).install(path: path)
+              ::Berkshelf::Berksfile.from_file(berksfile).install(:path => path)
             end
           end
         end
 
         private
 
-        attr_reader :berksfile, :path, :logger
+        # @return [String] path to a Berksfile
+        # @api private
+        attr_reader :berksfile
 
+        # @return [String] path in which to vendor the resulting cookbooks
+        # @api private
+        attr_reader :path
+
+        # @return [Kitchen::Logger] a logger to use for output
+        # @api private
+        attr_reader :logger
+
+        # Load the Berkshelf-specific libary code.
+        #
+        # @param logger [Kitchen::Logger] the logger to use
+        # @raise [UserError] if the library couldn't be loaded
+        # @api private
         def self.load_berkshelf!(logger)
-          first_load = require 'berkshelf'
+          first_load = require "berkshelf"
 
           version = ::Berkshelf::VERSION
           if first_load
@@ -73,9 +101,9 @@ module Kitchen
             logger.debug("Berkshelf #{version} previously loaded")
           end
         rescue LoadError => e
-          logger.fatal("The `berkshelf' gem is missing and must be installed" +
-            " or cannot be properly activated. Run" +
-            " `gem install berkshelf` or add the following to your" +
+          logger.fatal("The `berkshelf' gem is missing and must be installed" \
+            " or cannot be properly activated. Run" \
+            " `gem install berkshelf` or add the following to your" \
             " Gemfile if you are using Bundler: `gem 'berkshelf'`.")
           raise UserError,
             "Could not load or activate Berkshelf (#{e.message})"